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  ```