editor — Functions for scripting Editorial’s text editor

The editor module provides access to the text you’re currently editing. You can get and set the selected range and replace text in a given range.

Please note: Invalid input values for the selection and text manipulation functions (e.g. ranges that are out of bounds) are silently ignored as of now. This may change in a future release.

The following functions are provided by the editor module:

editor.fold_range(start, end[, label])

Fold (hides) the given range of text. The optional label parameter (a string) is shown as a placeholder. By default, the word count is used.

editor.unfold_range(start, end)

Unfold all text in the given range. Note that the unfolding is recursive, i.e. if there are nested folds, they are all unfolded at once. The return value is the unfolded text.

editor.unfold_all()

Unfold all text in the current document.

editor.close()

Close the document that is currently loaded in the editor. Changes are saved automatically.

editor.get_text([unfold])

Return the entire text of the document that is currently being edited.

The optional unfold argument controls how folded (hidden) text is treated. By default, any folded text is represented by a placeholder character (\ufffc). If unfold is True, the text is returned as if all text was unfolded.

editor.get_selection()

Return the selected range as a tuple of the form (start, end).

If no file is currently open in the editor, None is returned.

editor.get_selected_text()

Return the text that is currently selected in the editor, or None if no document is open (if a document is open, but no text is selected, an empty string is returned).

editor.get_line_selection()

Return the range of all lines that are part of the current selection as a tuple of the form (start, end)

If no file is currently open in the editor, None is returned.

editor.get_path()

Return the absolute file path of the document that is currently open in the editor, or None if no document is open.

Do NOT use this to write to the file. The editor does not recognize automatically when the underlying file changes. You can use set_file_contents() for this purpose, but note that set_file_contents() expects a relative path, not an absolute one, so the return value of this function is not suitable as input.

editor.get_scroll_position()

Return the relative scroll position in the document (between 0.0 and 1.0).

editor.set_scroll_position(pos)

Scroll the editor to a relative position between 0.0 (start of document) and 1.0 (end of document).

editor.insert_text(text[, scroll])

Insert text at the current caret position. If text is selected, it is replaced.

By default, the editor adjusts its scroll position, so that the new selection (cursor position) becomes visible. Passing False as the optional scroll parameter disables this behavior.

editor.set_selection(start[, end, scroll])

Set the selected range in the editor.

start and end must be integers. If end is not given, the caret is positioned at start with no text selected. By default, the editor adjusts its scroll position, so that the new selection becomes visible. Passing False as the optional scroll parameter disables this behavior.

editor.replace_text(start, end, replacement[, scroll])

Replace the text in the given range with replacement.

To insert/append text, a zero-length range can be used.

All changes can be undone by the user (using the regular undo key). Each separate call is a single undo step, regardless of how many characters were affected.

By default, the editor adjusts its scroll position, so that the inserted text becomes visible. Passing False as the optional scroll parameter disables this behavior.

editor.get_file_contents(name[, root])

Return the contents of a file in the document library. root can be either ‘local’ or ‘dropbox’. The default is ‘local’.

Note that this returns a plain byte string. If you want to get the text of a file that contains unicode, you have to decode it yourself (Editorial saves text files as UTF-8).

editor.set_file_contents(name, new_contents[, root])

Writes new data to the file with the given name (a relative path). If a file with this name exists, it is overwritten.

Note that new_contents is a byte string, which means that you can also use this to write binary files (such as images), but if you write non-ASCII text, you have to encode it yourself.

root can be either ‘local’ or ‘dropbox’. ‘local’ is the default.

editor.get_selected_folder()

Return the folder that is currently selected in the file browser as a tuple of root (‘local’ or ‘dropbox’) and relative path, e.g. ('dropbox', '/Notes').

editor.get_theme()

Return the name of the selected color theme, currently either ‘Default’ or ‘Dark’. The primary use case for this is to adjust HTML output that is shown in the browser or preview panel.

editor.reload_files()

Reload the document library UI. This can be useful if you write files from Python code that you want to open in the editor. Note: This is handled automatically if the get_file_contents() or set_file_contents() functions are used. While writing files in the local library is generally acceptable, you should never attempt to write in the Dropbox-synced library.

editor.get_workflows_path()

Return the absolute path where workflows are stored. This is also the default working directory for any scripts that are run as part of a workflow.

editor.reload_workflows()

Reload the list of workflows. This can be useful if you want to modify workflows programmatically (be very careful with that however). Workflows are stored as JSON, but the exact format is currently not documented and may change in future releases.

editor.get_bookmarks(collection='editor')

Return the list of bookmarks in either the editor’s bookmarks bar, or the browser’s bookmarks menu.

Each bookmark is a dictionary with the keys 'title' and 'URL'.

The collection parameter can be 'editor' or 'browser'.

editor.set_bookmarks(bookmarks[, collection='editor')

Set the list of bookmarks in the editor’s bookmarks bar, or the browser’s bookmarks menu.

bookmarks should be a sequence of dictionaries, with each dictionary representing a single bookmark. Each of the bookmark dictionaries must have a 'title' and a 'URL' key.

The collection parameter can be 'editor' or 'browser'.