# Script CotEditor on Mac with AppleScript

CotEditor works with AppleScript and JXA (JavaScript for Automation).

It has its own AppleScript dictionary so that you can look up all the classes or commands available with CotEditor. To open the dictionary:

- Choose Help > CotEditor Scripting Guide > AppleScript Dictionary.

In addition, script hooks can be used to automatically execute scripts in response to specific events. For details, see Run script on specific events.

To confirm the version history of the AppleScript support on CotEditor, see Support different CotEditor versions in AppleScript.

## Classes

The original classes and properties that are defined in CotEditor.

### Application

The CotEditor application.

### Window

A CotEditor window.

### Document

A CotEditor document.

Properties
  `contents`
    The contents of the document. (text)
  `text`
    The contents of the document. (text)
  `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, e.g., `Shift_JIS`, `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)

### 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 string in the frontmost 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 form CotEditor 5.0, characters are counted in the Unicode grapheme cluster unit. This is the same as the specification of AppleScript 2.0.

When ‘location’ is a negative value, the selection range starts from the ‘location’-th last character.
When ‘length’ is a positive value, the selection range becomes the ‘length’ characters starting from ‘location.’ If ‘length’ is larger than the number of the rest characters in the document, the range is from ‘location’ to the end.
When ‘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 caret 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.

## Commands

The original commands that are defined in CotEditor.
(properties surrounded by [ ] are options)

### write to console

`write to console`
  Print a string on CotEditor’s console window.
  [`title` (boolean)]
    Should the script name be displayed with? (added on CotEditor 5.0.7)
  [`timestamp` (boolean)]
    Should the timestamp be displayed with? (added on CotEditor 5.0.7)

#### Availability

CotEditor 3.2.0+

#### Example

    write to console "Script failed."

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

    write to console "calculating…" without title and timestamp

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

### find

`find`
  Searches a string, selects the string and returns `true`, if any, otherwise returns `false`.
  `for` (text)
    The string 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” with ignoring case, starting from the current selection to the end of the frontmost document, and returns the result.

#### Discussion

The search starts from the current selection (caret position).
For example, when not using the `wrap` or `backwards` options and when there are no matching string 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.

### replace

`replace`
  Searches a string, replaces the string and returns the number of replacements, if any, otherwise returns `0`.
  `for` (text)
    The string to search for.
  `to` (text)
    The string 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 frontmost document, replaces the matching strings with “Orange” and returns the number of replacements.

#### Discussion

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

After replacing the whole document using the `all` option, the caret moves to the head of the document. If there were no matching string, the caret doesn’t move.

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

### scroll to caret

`scroll to caret`
  Scrolls the window so that the caret or the selection can be seen.
  target
    ‘document’ object

#### Example

    scroll to caret front document

Scrolls the frontmost window so that the caret or the selection can be seen.

### jump

`jump`
  Move the caret to the specified location. At least, either one of a parameter is required.
  `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.

### convert

`convert`
  Converts the text encoding of the document.
  `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 frontmost 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.

### reinterpret

`reinterpret`
  Reinterpret the document with the specified text encoding.
  `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 are not yet saved are lost.

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

### shift

`shift left`
  Shifts the current line left.
`shift right`
  Shifts the current line right.
  target
    ‘selection’ object

#### Example

    shift right selection of front document

Shifts the line where the selection/caret is positioned right.

### comment out

`comment out`
  Append comment delimiters to selected text if possible.
`uncomment`
  Remove comment delimiters from selected text if possible.
  target
    ‘selection’ object

#### Availability

CotEditor 2.0.1+

#### Example

    comment out selection of front document

Comment out the selected text.

#### Discussion

These commands do nothing if not possible for example in cases where no delimiters are set in the current syntax or no comment delimiters to remove are available.

### string

`string`
  Returns the string in the specified range regardless of the current selection.
  `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 an empty string if the specified range was invalid.

This command does not change the specified range.

### change case

`change case`
  Uppercases/Lowercases/Capitalizes words.
  `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.

### change roman width

`change roman width`
  Converts between halfwidth and full-width characters.
  `to` `half`/`full`
    The text width to change.
  target
    ‘selection’ object

#### Example

    change roman width selection of front document to full

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

### change kana

`change kana`
  Converts between Japanese Hiragana and Katakana.
  `to` `hiragana`/`katakana`
    The Japanese character mode to change.
  target
    ‘selection’ object

#### Example

    change kana selection of front document to katakana

Converts Hiragana in the selection to Katakana.

### smart quotes

`smarten quotes`
  Convert straight quotes in the selected text to typographical quotes if exists.
`straighten quotes`
  Convert typographical quotes in the selected text to straight quotes if exists.
  target
    ‘selection’ object

#### Availability

CotEditor 3.9.7+

#### Example

    smarten quotes selection of front document

Convert straight quotes in the selected text to typographical quotes.

### smart dashes

`smarten dashes`
  Convert double hyphens in the selected text to dashes if exists.
  target
    ‘selection’ object

#### Availability

CotEditor 3.9.7+

#### Example

    smarten dashes selection of front document

Convert straight double hyphens in the selected text to dashes.

### normalize unicode

`normalize unicode`
  Performs Unicode normalization.
  `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).

### move line

`move line up`
  Swap selected lines with the line just above.
`move line down`
  Swap selected lines with the line just below.
  target
    ‘selection’ object

#### Availability

CotEditor 2.3.0+

### sort lines

`sort lines`
  Sort selected lines ascending.
`reverse lines`
  Reverse selected lines.
  target
    ‘selection’ object

#### Availability

CotEditor 2.3.0+

### delete duplicate line

`delete duplicate line`
  Delete duplicate lines in selection.
  target
    ‘selection’ object

#### Availability

CotEditor 2.3.0+

## See also

- Script CotEditor
- Support different CotEditor versions in AppleScript
- Run script on specific events