github.com/aretext/aretext@v1.3.0/docs/custom-menu-commands.md (about) 1 Custom Menu Commands 2 ==================== 3 4 Aretext allows you to define custom menu items to run shell commands. This provides a simple, yet powerful, way to extend the editor. 5 6 Adding Custom Menu Comands 7 -------------------------- 8 9 You can add new menu commands by [editing the config file](configuration.md) to add this rule: 10 11 ```yaml 12 - name: custom menu rule 13 pattern: "**/myproject/**" 14 config: 15 menuCommands: 16 - name: my custom menu command 17 shellCmd: echo 'hello world!' | less 18 mode: terminal # or "silent" or "insert" or "fileLocations" 19 ``` 20 21 After restarting the editor, the new command will be available in the command menu. Selecting the new command will launch a shell to execute the given command (in this case, echoing "hello world"). 22 23 The shell program can be configured by environment variables: `$ARETEXT_SHELL` has highest priority, then `$SHELL`. If neither environment variable is set, aretext uses `sh`. 24 25 The "mode" parameter controls how aretext handles the command's input and output. The table below shows the available modes: 26 27 | Mode | Input | Output | Use Cases | 28 |---------------|-------|------------------------|-------------------------------------------------------------------------------| 29 | terminal | tty | tty | `make`, `git commit`, `go test`, `man`, ... | 30 | silent | none | none | `go fmt`, tmux commands, copy to system clipboard, ... | 31 | insert | none | insert into document | paste from system clipboard, insert snippet, comment/uncomment selection, ... | 32 | insertChoice | none | insert choice menu | choose a word to insert from a dictionary like `/usr/share/dict/words`, ... | 33 | fileLocations | none | file location menu | grep for word under cursor, ... | 34 | workingDir | none | working directory menu | select the current working directory from a preset list | 35 36 In addition, the following environment variables are provided to the shell command: 37 38 - `$FILEPATH` is the absolute path to the current file. 39 - `$WORD` is the current word under the cursor. 40 - `$LINE` is the line number of the cursor, starting from one. 41 - `$COLUMN` is the column position of the cursor in bytes, starting from one. 42 - `$SELECTION` is the currently selected text (if any). 43 44 If there are multiple commands with the same name, only the last of these commands will appear in the menu. 45 46 Examples 47 -------- 48 49 ### Build a project with make 50 51 Add a menu command to build a project using `make`. Piping to `less` allows us to page through the output. 52 53 ```yaml 54 - name: custom make cmd 55 pattern: "**/myproject/**" 56 config: 57 menuCommands: 58 - name: build 59 shellCmd: make | less 60 save: true # save the file before running `make` 61 ``` 62 63 ### Copy and paste using the system clipboard 64 65 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. 66 67 On Linux (Wayland): 68 69 ```yaml 70 - name: linux wayland clipboard commands 71 pattern: "**" 72 config: 73 menuCommands: 74 - name: copy to clipboard 75 shellCmd: wl-copy "$SELECTION" 76 mode: silent 77 - name: paste from clipboard 78 shellCmd: wl-paste 79 mode: insert 80 ``` 81 82 On macOS: 83 84 ```yaml 85 - name: macos clipboard commands 86 pattern: "**" 87 config: 88 menuCommands: 89 - name: copy to clipboard 90 shellCmd: printenv SELECTION | pbcopy 91 mode: silent 92 - name: paste from clipboard 93 shellCmd: pbpaste 94 mode: insert 95 ``` 96 97 Using tmux: 98 99 ```yaml 100 - name: tmux clipboard commands 101 pattern: "**" 102 config: 103 menuCommands: 104 - name: copy to clipboard 105 shellCmd: printenv SELECTION | tmux load-buffer - 106 mode: silent 107 - name: paste from clipboard 108 shellCmd: tmux show-buffer 109 mode: insert 110 ``` 111 112 ### Format the current file 113 114 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. 115 116 For example, this command uses `go fmt` to format a Go file: 117 118 ```yaml 119 - name: custom fmt command 120 pattern: "**/*.go" 121 config: 122 menuCommands: 123 - name: go fmt current file 124 shellCmd: go fmt $FILEPATH | less 125 save: true # save the file before running `go fmt` 126 ``` 127 128 ### Git blame the current file 129 130 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. 131 132 ```yaml 133 - name: git blame command 134 pattern: "**" 135 config: 136 menuCommands: 137 - name: git blame 138 shellCmd: git blame "$FILEPATH" | less +$LINE 139 ``` 140 141 ### Insert a snippet 142 143 You can add a custom menu command to insert a snippet of code. 144 145 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: 146 147 ```yaml 148 - name: custom snippet command 149 pattern: "**/*.go" 150 config: 151 menuCommands: 152 - name: insert test snippet 153 shellCmd: cat ~/snippets/go-test.go 154 mode: insert 155 ``` 156 157 ### Grep for the word under the cursor 158 159 You can add a custom menu command to grep for the word under the cursor. The following example uses [ripgrep](https://github.com/BurntSushi/ripgrep) to perform the search: 160 161 ```yaml 162 - name: custom grep command 163 pattern: "**" 164 config: 165 menuCommands: 166 - name: rg word 167 shellCmd: rg $WORD --vimgrep # or `grep $WORD -n -R .` 168 mode: fileLocations 169 ``` 170 171 Once the search has completed, aretext loads the locations into a searchable menu. This allows you to easily navigate to a particular result. 172 173 The "fileLocations" mode works with any command that outputs file locations as lines with the format: `<file>:<line>:<snippet>` or `<file>:<line>:<col>:<snippet>`. You can use grep, ripgrep, or a script you write yourself! 174 175 ### Open a document in a new tmux window 176 177 If you use [tmux](https://wiki.archlinux.org/title/Tmux), you can add a custom menu command to open the current document in a new window. 178 179 ```yaml 180 - name: tmux window commands 181 pattern: "**" 182 config: 183 menuCommands: 184 - name: split window horizontal 185 shellCmd: tmux split-window -h "aretext -line $LINE $FILEPATH" 186 mode: silent 187 - name: split window vertical 188 shellCmd: tmux split-window -v "aretext -line $LINE $FILEPATH 189 mode: silent 190 ```