Automate tasks using UNIX scripts in CotEditor on Mac

From CotEditor’s Script menu, you can run UNIX scripts to pass information and text from the document you’re editing to the script, and apply the script’s output to the document.

Create a UNIX script for the Script menu

You can write UNIX scripts for CotEditor in any scripting language, as long as the execution environment is available on your Mac. However, script files must have one of the following file extensions: .sh, .pl, .php, .rb, .py, .js, .awk, or .swift.

To run a script properly, include a #! (shebang) line that specifies the interpreter, and make sure the script file is executable. For example, you can make a script executable in Terminal on Mac.

Get the document’s file path

If the current document has been saved, its absolute file path is passed to the script as an argument.

Pass text data to a script

A script can receive the content of the current document through standard input (STDIN). To specify what CotEditor passes to your script, add a comment at the top of the script that contains: “%%%{CotEditorXInput=xxxx}%%%”. Replace “xxxx” with one of the parameters below. If you don’t specify a parameter, CotEditor passes no data. This is the same as using “None.”

For “xxxx,” you can specify one of the following input source:

KeywordDescription
Selection

Pass the currently selected text.

CurrentLine

The text on the line containing the insertion point

AllText

Pass the entire content of the document.

None

Pass nothing (default).

Text passed from CotEditor to a script is always encoded in UTF-8, regardless of the document’s text encoding.

Receive output data from a script

CotEditor can receive output from the script through standard output (STDOUT) and apply it to the document. To define how CotEditor handles the output, add a comment at the top of the script that contains: “%%%{CotEditorXOutput=xxxx}%%%”. Replace xxxx with one of the parameters below. If you don’t specify a parameter, CotEditor performs no action. This is the same as using “Discard.”

For “xxxx,” you can specify one of the following output target:

KeywordDescription
ReplaceSelection

Replace the current selection with the output text.

ReplaceCurrentLine

Replace the entire line containing the insertion point with the output.

ReplaceAllText

Replace the entire content of the document with the output text.

InsertAfterSelection

Insert the output text immediately after the current selection.

AppendToAllText

Insert the output text at the end of the document.

NewDocument

Create a new document and insert the output text into it.

Pasteboard

Place the output text on the Clipboard.

Discard

Do nothing (default).

Text returned from a script to CotEditor must also be encoded in UTF-8, regardless of the document’s text encoding.

Print text to the Console

Any text written to standard error (STDERR) appears in the Console window.

Write a script

For example, the following Python script adds a “>” character to the beginning of each selected line in the current document and prints the number of processed lines to the Console.

#!/usr/bin/env python3
# %%%{CotEditorXInput=Selection}%%%
# %%%{CotEditorXOutput=ReplaceSelection}%%%

import sys

count = 0
for line in sys.stdin:
    count += 1
    print(">" + line.rstrip())
sys.stderr.write("Processed {} lines.".format(count))

The following message appears when running the script from the Script menu in CotEditor:

[2022-05-06 18:35:00] Example Code Processed 5 lines.

See also