Custom Menu Commands
Aretext allows you to define custom menu items to run shell commands. This provides a simple, yet powerful, way to extend the editor.
Adding Custom Menu Comands
You can add new menu commands by editing the config file to add this rule:
After restarting the editor, the new command will be available in the command menu. Selecting the new command will launch a shell (configured by the
$SHELL environment variable) and execute the shell command (in this case, echoing "hello world").
The "mode" parameter controls how aretext handles the command's input and output. The table below shows the available modes:
|insert||none||insert into document||paste from system clipboard, insert snippet, comment/uncomment selection, ...|
|insertChoice||none||insert choice menu||choose a word to insert from a dictionary like
|fileLocations||none||file location menu||grep for word under cursor, ...|
|workingDir||none||working directory menu||select the current working directory from a preset list|
In addition, the following environment variables are provided to the shell command:
$FILEPATHis the absolute path to the current file.
$WORDis the current word under the cursor.
$LINEis the line number of the cursor, starting from one.
$COLUMNis the column position of the cursor in bytes, starting from one.
$SELECTIONis the currently selected text (if any).
If there are multiple commands with the same name, only the last of these commands will appear in the menu.
Build a project with make
Add a menu command to build a project using
make. Piping to
less allows us to page through the output.
Copy and paste using the system clipboard
Most systems provide command-line utilities for interacting with the system clipboard. Custom menu commands can invoke these tools to copy the current selection and paste into the document.
On Linux (Wayland):
Format the current file
Many programming languages provide command line tools to automatically format code. You can add a custom menu command to run these tools on the current file.
For example, this command uses
go fmt to format a Go file:
Git blame the current file
When working in a git repository, you might want to know who last edited a line of code. You can find this using
git blame on the current file.
Insert a snippet
You can add a custom menu command to insert a snippet of code.
For example, suppose you have written a template for a Go test. You can then create a menu command to
cat the contents of the file into the document:
Grep for the word under the cursor
You can add a custom menu command to grep for the word under the cursor. The following example uses ripgrep to perform the search:
Once the search has completed, aretext loads the locations into a searchable menu. This allows you to easily navigate to a particular result.
The "fileLocations" mode works with any command that outputs file locations as lines with the format:
<file>:<line>:<col>:<snippet>. You can use grep, ripgrep, or a script you write yourself!
Open a document in a new tmux window
If you use tmux, you can add a custom menu command to open the current document in a new window.