Automate tasks using AppleScript in CotEditor on Mac

You can automate many tasks such as creating and editing documents, working with selections, and controlling windows using AppleScript or JavaScript for Automation (JXA). This page describes the scripting interface provided by CotEditor, focusing on the available classes and commands.

CotEditor extends the standard system scripting terms with its own classes and commands, allowing scripts to interact more directly with CotEditor documents and features. You can also use script hooks to automatically run scripts in response to specific events. For details, see Run script on specific events.

You can also view CotEditor’s scripting interface in Script Editor’s library. To open the scripting dictionary:

class

`document`

A CotEditor document.

Properties

contents: The contents of the document. (text)
text: The contents of the document. (text)
editable: Is the document editable? (boolean) new on CotEditor 5.1
length: The number of characters of the document in UTF-16. (int) deprecated on CotEditor 4.4
selection: The current selection. (text selection)
encoding: The text encoding name of the document. (text)
IANA charset: The IANA charset name of the document. (text, such as Shift_JIS or EUC-JP)
has BOM: Has the text encoding a BOM (byte order mark)? (boolean) new on CotEditor 4.1
line ending: The line ending code of the document. (CR / LF / CRLF / NEL / LS / PS)
tab width: The width of a tab character in space equivalents. (int) new on CotEditor 2.1
expands tab: Are tab characters expanded to space? (boolean) new on CotEditor 3.1.2
wrap lines: Whether to wrap lines or not. (boolean)
coloring style: The syntax name of the document. (text)

class

`folder document`

CotEditor folder document

Properties

current document: The currently displayed document (document).

A document opened by opening a folder is treated as an instance of the folder document class. You can obtain the currently open document in that folder document via the current document property. In addition, any document API sent directly to a folder document is forwarded to its current document. If no current document exists, commands that target document will return an error.

Example

The following two commands produce the same result:

if front document is folder document then
	set theDocument to front document's current document
else
	set theDocument to front document
end if

tell theDocument
	set theText to contents of selection
end tell

Gets the front text document and sets its selection contents.

tell front document
	set theText to contents of selection
end tell

Sets the selection contents of the front document.

class

`text selection`

The current selection.

Properties

contents: The contents of the selection.
range: The range of characters in the selection. The format is '{location, length}'.
line range: The range of lines in the selection. The format is '{location, length}'. (length can be omitted, one line is selected even if it were 0 or 1)

Example

contents of selection of document 1

Returns the selected text in the current document.

set contents of selection of front document to "Apple"

Replaces the selection with “Apple.”

range of selection of front document

Returns the selection range with {location, length}.

set range of selection of front document to {1, 12}

Select from the 1st character to the 12th character.

set line range of selection of front document to 10

Select the 10th line (no scrolling).

set range of selection of front document to {-15, -1}

Select from the 15th last character to the last but one (no scrolling).

Discussion

The selection property doesn’t work by itself. Use this property with others such as contents.

Starting from CotEditor 5.0, characters are counted in the Unicode grapheme cluster unit. This is the same as the specification of AppleScript 2.0.

If you specify a negative value for location, CotEditor counts from the end of the document. If the specified length exceeds the remaining characters, CotEditor selects text up to the end of the document. If length is a negative value, the selection range ends at the length-th last character. If the absolute value of length is smaller than location (that is, the selection’s end point is before location), the insertion point just moves to location (same as when {location, 0} was input).

This specifying method is based on substr in PHP.

The command for changing selection doesn’t scroll through the editor. Use the scroll to caret command or jump command to make the selection remain in the view.

command

`write to console`

Print text on CotEditor’s console window.

Parameters

[title (boolean)]: Should the script name appear with? (added on CotEditor 5.0.7)
[timestamp (boolean)]: Should the timestamp appear with? (added on CotEditor 5.0.7)

Availability

CotEditor 3.2.0+

Example

write to console "Script failed."

Displays the message "Script failed." on CotEditor’s console.

write to console "calculating…" without title and timestamp

Displays the message "calculating…" without the script name and timestamp on CotEditor’s console.

command

`find`

Searches for text and selects the first match. Returns true if a match is found; otherwise, returns false.

Parameters

for (text): The text to search for.
[RE (boolean)]: Perform regular expression search or not.
[wrap (boolean)]: Perform wrap search or not.
[ignore case (boolean)]: Ignore case or not.
[backwards (boolean)]: Perform backwards search or not.

Return value

boolean

Target

document object

Example

find front document for "Apple" with ignore case

Searches “Apple” ignoring case, starting from the current selection to the end of the current document, then returns the result.

Discussion

The search starts from the current selection (insertion point). For example, when not using the wrap or backwards options and when there are no matching text after the current selection, then false is returned.

The regular expression search cannot search backwards. If both options were specified at the same time, RE takes precedence and backwards is ignored.

command

`replace`

Searches for text and replaces them with other text. Returns the number of replacements, if any, otherwise returns 0.

Parameters

for (text): The text to search for.
to (text): The text to replace with.
[all (boolean)]: Search the whole document or not.
[RE (boolean)]: Perform regular expression search or not.
[wrap (boolean)]: Perform wrap search or not.
[ignore case (boolean)]: Ignore case or not.
[backwards (boolean)]: Perform backwards search or not.

Return value

int

Target

document object

Example

replace front document for "Apple" to "Orange" with all and ignore case

Searches “Apple” with ignoring case in the current document, replaces the matching text with “Orange” and returns the number of replacements.

Discussion

As in the case of the find command, the search starts from the current selection (insertion point). Use the all option for searching the whole document.

After replacing the whole document using the all option, the insertion point moves to the head of the document. If there were no matching text, the insertion point doesn’t move.

The regular expression search cannot search backwards. If both options were specified at the same time, the backwards option is ignored.

command

`jump`

Move the insertion point to the specified location. At least one parameter is required.

Parameters

to line (int): The number of the line to jump.
[column (int)]: The location in the line to jump.

Availability

CotEditor 2.1.0+

Example

jump front document to line -1

Move the insertion point to the last line and scroll through the editor to view the specified area.

Discussion

If a negative value is provided, the line/column is counted from the end.

command

`convert`

Converts the text encoding of the document.

Parameters

to (text): The new encoding, either in localized encoding name or an IANA charset name.
[lossy] (boolean): Whether to allow “lossy” conversion (might result in loss of character that couldn’t be converted) or not.
[BOM] (boolean): Whether to add a BOM (byte order mark). (added on CotEditor 4.1)

Return value

boolean

Target

document object

Example

convert front document to "Unicode (UTF-8)" with BOM without lossy

Converts the text encoding of the current window to Unicode (UTF-8) with BOM, returns the result.

Discussion

From CotEditor 4.0.7 on, the new encoding name accepts also IANA charset names.

command

`reinterpret`

Reinterpret the document with the specified text encoding.

Parameters

as (text): The encoding for reinterpreting, either in localized encoding name or an IANA charset name.

Return value

boolean

Target

document object

Example

reinterpret front document as "Japanese (EUC)"

Reinterprets the document with EUC-JP, returns the result.

Discussion

Returns false if the file has never been saved.

Changes that aren’t yet saved are lost.

From CotEditor 4.0.7 on, the new encoding name accepts also IANA charset names.

command

`string`

Returns the text in the specified range regardless of the current selection.

Parameters

in (list): The range.

Return value

text

Target

selection object

Example

string front document in {0, 10}

Returns the first ten letters of the document.

Discussion

Returns empty text if the specified range was invalid.

This command doesn’t change the specified range.

command

`change case`

Uppercases/Lowercases/Capitalizes words.

Parameters

to upper / lower / capitalized: The case type to change.

Target

selection object

Example

change case selection of front document to upper

Uppercases alphabetic words in the selection.

command

`change roman width`

Converts between halfwidth and full-width characters.

Parameters

to half / full: The text width to change.

Target

selection object

Example

change roman width selection of front document to full

Converts alphanumeric characters in the selection to their full-width equivalents.

command

`normalize unicode`

Performs Unicode normalization.

Parameters

to NFKC / NFD / NFC / NFKD / NFKC Casefold / Modified NFC / Modified NFD: The normalized forms of Unicode text.

Target

selection object

Availability

CotEditor 2.0.0+

Example

normalize unicode selection of front document to NFC

Perform Unicode normalization on the selection using normalization form C (NFC).

Automate tasks using AppleScript in CotEditor on Mac

document

folder document

Example

text selection

Example

Discussion

write to console

Example

find

Example

Discussion

replace

Example

Discussion

scroll to caret

Example

jump

Example

Discussion

convert

Example

Discussion

reinterpret

Example

Discussion

shift left

shift right

Example

comment out

Example

Discussion

uncomment

Discussion

string

Example

Discussion

change case

Example

change roman width

Example

smart quotes

Example

straighten quotes

smart dashes

Example

normalize unicode

Example

move line up

move line down

sort lines

reverse lines

delete duplicate line

See also

`document`

`folder document`

`text selection`

`write to console`

`find`

`replace`

`scroll to caret`

`jump`

`convert`

`reinterpret`

`shift left`

`shift right`

`comment out`

`uncomment`

`string`

`change case`

`change roman width`

`smart quotes`

`straighten quotes`

`smart dashes`

`normalize unicode`

`move line up`

`move line down`

`sort lines`

`reverse lines`

`delete duplicate line`