kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

commands.asciidoc (22237B)


      1 = Commands
      2 
      3 Some commands take an exclamation mark (*!*), which can be used to force
      4 the execution of the command (i.e. to quit a modified buffer, the
      5 command *q!* has to be used). Aliases are mentioned below each command.
      6 
      7 For all commands that accept switches, a parameter beginning with
      8 a single dash (*-*) will be interpreted as a switch. Any unknown switches
      9 will cause an error. To force the remaining parameters to not be interpreted as
     10 switches even if they begin with a dash, you can pass two dashes (*--*) as a parameter.
     11 
     12 *doc* <topic>::
     13     *alias* help +
     14     display documentation about a topic. The completion list displays the
     15     available topics
     16 
     17 == Files and Buffers
     18 
     19 For the following *write* commands, the *-sync* switch forces the synchronization
     20 of the file onto the filesystem
     21 
     22 *arrange-buffers* <buffer>...::
     23     Reorder the buffers in the buffers list.
     24     The named buffers will be moved to the front of the buffer list, in the order
     25     given. Buffers that do not appear in the parameters will remain at the
     26     end of the list, keeping their current order.
     27 
     28     *-back*:::
     29         Move the named buffers to the back, rather than the front, of the buffer list.
     30 
     31 *change-directory* [<directory>]::
     32     *alias* cd +
     33     change the current directory to *directory*, or the home directory if
     34     unspecified
     35 
     36 *edit[!]* [<switches>] <filename> [<line> [<column>]]::
     37     *alias* e +
     38     open buffer on file, go to given line and column. If file is already
     39     opened, just switch to this file. Use edit! to force reloading
     40 
     41     *-debug*:::
     42         The new buffer (if any) will be created as a debug buffer.
     43         (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
     44 
     45     *-existing*:::
     46         If the named file does not exist, fail instead of creating a new buffer.
     47 
     48     *-readonly*:::
     49         The new buffer (if any) will be set read-only.
     50 
     51     *-fifo* <fifoname>:::
     52         Creates a new scratch buffer named <filename>, and continually appends
     53         data from the fifo (named pipe) <fifoname> as it arrives.
     54         (See <<buffers#fifo-buffers,`:doc buffers fifo-buffers`>>)
     55 
     56     *-scratch*:::
     57         Creates a new buffer named <filename>, which doesn't correspond to any
     58         file on disk. If no filename is given, the buffer name will be
     59         generated based on format `\*scratch-$ID*`, where `$ID` is an
     60         integer automatically incremented for new buffers.
     61         (See <<buffers#scratch-buffers,`:doc buffers scratch-buffers`>>)
     62 
     63     *-scroll*:::
     64         If used with `-fifo`, when new data arrives Kakoune will scroll the
     65         buffer down to make the new data visible.
     66         Otherwise, does nothing.
     67 
     68 
     69 *write[!]* [-force] [-sync] [-method <writemethod>] [<filename>]::
     70     *alias* w +
     71     write buffer to <filename> or use its name if filename is not
     72     given. If the file is write-protected, its permissions are temporarily
     73     changed to allow saving the buffer and restored afterwards when
     74     the write! command is used.
     75 
     76     *-force*:::
     77         Equivalent to `!`, allow overwiting existing files if `<filename>`
     78         is given and set permissions temporarily if necessary.
     79 
     80     *-sync*:::
     81         Synchronise the filesystem after the write
     82 
     83     *-method <writemethod>*:::
     84         Enforce write method instead of relying on the `writemethod` option
     85 
     86         `replace`::::
     87             Write to a temporary file then rename to the target file so that
     88             the modification appears atomically.
     89 
     90         `overwrite`::::
     91             Open the existing file and overwrite its content with the new
     92             content.
     93 
     94         (See <<options#builtin-options,`:doc options builtin-options`>>)
     95 
     96 *write-all* [-sync] [-method <writemethod>]::
     97     *alias* wa +
     98     write all changed buffers that are associated with a file
     99 
    100 *quit[!]* [<exit status>]::
    101     *alias* q +
    102     exit Kakoune, use quit! to force quitting even if there is some
    103     unsaved buffer remaining. If specified, the client exit status
    104     will be set to <exit status>
    105 
    106 *write-quit[!]* [-sync] [-method <writemethod>] [<exit status>]::
    107     *alias* wq +
    108     write current buffer and quit current client. If specified, the client
    109     exit status will be set to <exit status>
    110 
    111 *write-all-quit* [-sync] [-method <writemethod>] [<exit status>]::
    112     *alias* waq +
    113     write all buffers and quit. If specified, the client exit status
    114     will be set to <exit status>
    115 
    116 *buffer* <name>::
    117     *alias* b +
    118     switch to buffer <name>
    119 
    120 *buffer-next*::
    121     *alias* bn +
    122     switch to the next buffer.
    123     Debug buffers are skipped.
    124     (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
    125 
    126 *buffer-previous*::
    127     *alias* bp +
    128     switch to the previous buffer.
    129     Debug buffers are skipped.
    130     (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
    131 
    132 *delete-buffer[!]* [<name>]::
    133     *alias* db +
    134     delete current buffer or the buffer <name> if specified
    135 
    136 *rename-buffer* [-file|-scratch] <name>::
    137     set current buffer name, if *-scratch* or *-file* is given, ensure
    138     the buffer is set to the corresponding type.
    139 
    140 *source* <filename> <param>...::
    141     execute commands in <filename>
    142     parameters are available in the sourced script as `%arg{0}`, `%arg{1}`, …
    143 
    144 == Clients and Sessions
    145 
    146 *rename-client* <name>::
    147     set current client name
    148     Client names may only contain letters, numbers, `-`, and `_`.
    149 
    150 *rename-session* <name>::
    151     set current session name
    152 
    153 *kill[!]* [<exit status>]::
    154     terminate the current session, all the clients as well as the server.
    155     If specified, the server and clients exit status will be set to <exit status>
    156 
    157 == Options
    158 
    159 *declare-option* [<switches>] <type> <name> [<value>]::
    160     *alias* decl +
    161     declare a new option, the -hidden switch hides the option in completion
    162     suggestions (See <<options#declare-option,`:doc options declare-option`>>)
    163 
    164 *set-option* [<switches>] <scope> <name> <value>::
    165     *alias* set +
    166     change the value of an option in *scope*
    167     (See <<options#set-option,`:doc options set-option`>>
    168     and <<scopes#,`:doc scopes`>>)
    169 
    170 *unset-option* <scope> <name>::
    171     *alias* unset +
    172     unset the value of an option in *scope*, so the value from an outer scope
    173     is used
    174     (See <<options#unset-option,`:doc options unset-option`>>
    175     and <<scopes#,`:doc scopes`>>)
    176 
    177 *update-option* <scope> <name>::
    178     update the value of an option if its type supports that operation
    179     (See <<options#update-option,`:doc options update-option`>>
    180     and <<scopes#,`:doc scopes`>>)
    181 
    182 == Commands and Keys
    183 
    184 *define-command* [<switches>] <name> <command>::
    185     *alias* def +
    186     define a new command (See <<declaring-new-commands,Declaring new commands>>)
    187 
    188 *alias* <scope> <name> <command>::
    189     define a new alias named *name* in *scope*
    190     (See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
    191 
    192 *complete-command* [<switches>] <name> <type> [<param>]::
    193     *alias* compl +
    194     configure how a command completion works
    195     (See <<configuring-command-completion,Configuring command completion>>)
    196 
    197 *unalias* <scope> <name> [<command>]::
    198     remove an alias if its current value is the same as the one passed
    199     as an optional parameter, remove it unconditionally otherwise
    200     (See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
    201 
    202 *evaluate-commands* [<switches>] <command> ...::
    203     *alias* eval +
    204     evaluate commands, as if they were entered in the command prompt
    205     (See <<execeval#,`:doc execeval`>>)
    206 
    207 *execute-keys* [<switches>] <key> ...::
    208     *alias* exec +
    209     execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
    210 
    211 *map* [<switches>] <scope> <mode> <key> <keys>::
    212     bind a list of keys to a combination (See <<mapping#,`:doc mapping`>>
    213     and <<scopes#,`:doc scopes`>>)
    214 
    215 *unmap* <scope> <mode> <key> [<expected>]::
    216     unbind a key combination (See <<mapping#,`:doc mapping`>>
    217     and <<scopes#,`:doc scopes`>>)
    218 
    219 *declare-user-mode* <name>::
    220     declare a new user keymap mode
    221 
    222 *enter-user-mode* [<switches>] <name>::
    223     enable <name> keymap mode for next key
    224 
    225     *-lock*:::
    226         stay in mode until `<esc>` is pressed
    227 
    228     *-count <count>*:::
    229         Forward *count* to the underlying normal mode parameters
    230 
    231     *-register <register>*:::
    232         Forward *register* to the underlying normal mode parameters
    233 
    234 == Hooks
    235 
    236 *hook* [<switches>] <scope> <hook_name> <filtering_regex> <command>::
    237     execute *command* whenever a *hook_name* is triggered in *scope*
    238     (See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
    239 
    240     *-group <groupname>*:::
    241         Add this hook to the *groupname* group, so it can be removed by the
    242         `remove-hooks` command (below)
    243         or disabled with the `disabled_hooks` option
    244         (see <<options#builtin-options,`:doc options builtin-options`>>).
    245 
    246     *-once*:::
    247         This hook will be automatically removed after it has been executed.
    248 
    249     *-always*:::
    250         This hook will run even while hooks are disabled.
    251         See <<hooks#disabling-hooks,`:doc hooks disabling-hooks`>>.
    252 
    253 *remove-hooks* <scope> <group>::
    254     *alias* rmhooks +
    255     remove every hook in *scope* whose group matches the regex *group*
    256     (See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
    257 
    258 *trigger-user-hook* <param>::
    259     trigger the `User` hook with the given *param* as filter string in
    260     the current context. (See <<hooks#,`:doc hooks`>>)
    261 
    262 == Display
    263 
    264 *echo* [<switches>] <text>::
    265     show *text* in status line, with the following *switches*:
    266 
    267     *-markup*:::
    268         expand the markup strings in *text* (See
    269         <<faces#markup-strings,`:doc faces markup-strings`>>)
    270 
    271     *-debug*:::
    272         print the given text to the `\*debug*` buffer
    273 
    274     *-to-file* <filename>:::
    275         write the given text to the given file on the host
    276         filesystem.
    277 
    278     *-to-shell-script* <script>:::
    279         execute the given shell script with the given text
    280         written to its standard input
    281 
    282     *-quoting* <quoting>:::
    283         define how arguments are quoted in echo output:
    284 
    285         - *raw* (default)::::
    286             just join each argument with a space
    287 
    288         - *kakoune*::::
    289             also wrap each argument in single quotes, doubling-up
    290             embedded quotes.
    291 
    292         - *shell*::::
    293             also wrap each arguments in single quotes and escape
    294             embedded quotes in a shell compatible way.
    295 
    296 *set-face* <scope> <name> <facespec>::
    297     *alias* face +
    298     define a face in *scope*
    299     (See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>)
    300 
    301 *unset-face* <scope> <name>::
    302     Remove a face definition from *scope*
    303     (See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>)
    304 
    305 *colorscheme* <name>::
    306     load named colorscheme +
    307     Colorschemes are just `.kak` scripts that set faces. Colorschemes are searched for in `%val{config}/colors` and `%val{runtime}/colors`. +
    308     (See <<faces#, `:doc faces`>> and <<expansions#, `:doc expansions`>>)
    309 
    310 *add-highlighter* [<switches>] <highlighter_path> <highlighter_parameters> ...::
    311     *alias* addhl +
    312     add a highlighter to the current window
    313     (See <<highlighters#,`:doc highlighters`>>)
    314 
    315 *remove-highlighter* <highlighter_path>::
    316     *alias* rmhl +
    317     remove the highlighter whose id is *highlighter_id*
    318     (See <<highlighters#,`:doc highlighters`>>)
    319 
    320 == Helpers
    321 
    322 Kakoune provides some helper commands that can be used to define composite
    323 commands in scripts. They are also available in the interactive mode,
    324 but not really useful in that context.
    325 
    326 *prompt* [<switches>] <prompt> <command>::
    327     prompt the user for a string, when the user validates, executes the
    328     command. The entered text is available in the `text` value accessible
    329     through `$kak_text` in shells or `%val{text}` in commands.
    330 
    331     The *-init <str>* switch allows setting initial content, the
    332     *-password* switch hides the entered text and clears the register
    333     after command execution.
    334 
    335     The *-on-change* and *-on-abort* switches, followed by a command
    336     will have this command executed whenever the prompt content changes
    337     or the prompt is aborted, respectively.
    338 
    339     Completion support can be controlled with the same switches provided
    340     by the *define-command* command, see
    341     <<declaring-new-commands,Declaring new commands>>.
    342 
    343     For *-shell-script-completion* and *-shell-script-candidates*
    344     completions, token_to_complete will always be 1, and the full
    345     prompt content will be passed as a single token. In other words,
    346     word splitting does not take place.
    347 
    348     NOTE: The prompt is displayed in and receives input from the
    349     current client context, so inside a draft context like
    350     `evaluate-commands -draft`, it is invisible and only responds to
    351     an `execute-keys` command in the same context.
    352 
    353 *on-key* <command>::
    354     wait for next key from user, then execute <command>, the key is
    355     available through the `key` value, accessible through `$kak_key`
    356     in shells, or `%val{key}` in commands.
    357 
    358     NOTE: The key press must come from the current client context,
    359     so inside a draft context like `evaluate-commands -draft`, it only
    360     responds to an `execute-keys` command in the same context.
    361 
    362 *info* [<switches>] <text>::
    363     display text in an information box with the following *switches*:
    364 
    365     *-anchor* <line>.<column>:::
    366         print the text at the given coordinates
    367 
    368     *-style* <style>:::
    369         set the style and placement of the message box.
    370 
    371         *menu*::::
    372             display the info next to the displayed menu, as documentation
    373             for the currently selected entry.
    374 
    375         *above*::::
    376             display the info above the given anchor
    377 
    378         *below*::::
    379             display the info below the given anchor
    380 
    381          *modal*::::
    382              display the info modally, and do not auto-close the
    383              info or replace it with non modal info boxes. To hide
    384              a modal info box, use `info -style modal` with no
    385              arguments.
    386 
    387     *-title* <text>:::
    388         set the title of the message box
    389 
    390     *-markup*:::
    391         parse markup in both title (if provided) and text. (See
    392         <<faces#markup-strings,`:doc faces markup-strings`>>)
    393 
    394     NOTE: The info box is displayed in the current client context,
    395     so inside a draft context like `eval -draft`, it is invisible.
    396 
    397 *try* <commands> [catch <on_error_commands>]...::
    398     prevent an error in *commands* from aborting the whole command
    399     execution, execute *on_error_commands* instead. If nothing is to be
    400     done on error, the catch part can be omitted. If an error is raised
    401     in the *on_error_commands*, that error is propagated, except if
    402     another *catch* and *on_error_commands* parameter follows, in which
    403     case those commands get executed, and so-on. During error commands,
    404     the description of the last raised error is available as `$kak_error`
    405     in the shell, or `%val{error}` in commands.
    406 
    407 *nop*::
    408     does nothing, but arguments will be evaluated (e.g. shell expansion)
    409 
    410 *fail* <text>::
    411     raise an error, uses <text> as its description
    412 
    413 *set-register* <name> <contents>...::
    414     *alias* reg +
    415     set register *name* to *content*, each content parameter is assigned to
    416     a different string in the register. (See <<registers#,`:doc registers`>>)
    417 
    418 *select* [<switches>] <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>...::
    419     replace the current selections with the ones described in the arguments
    420 
    421     *-timestamp* <timestamp>:::
    422         specify which buffer timestamp those coordinates apply to. Uses current
    423         buffer timestamp if not specified.
    424 
    425     *-codepoint*::
    426         provided columns are to be interpreted as codepoint counts, not byte counts.
    427 
    428     *-display-column*::
    429         provided columns are to be interpreted as display column counts, not byte counts.
    430 
    431     both *-codepoint* and *-display-column* are only valid if *-timestamp*
    432     matches the current buffer timestamp (or is not specified).
    433 
    434 *debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}::
    435     print some debug information in the `\*debug*` buffer
    436 
    437 == Module commands
    438 
    439 In Kakoune, modules are a grouping of stored commands to be executed the first time
    440 they are needed. This allows complex configurations to be evaluated lazily, and allows
    441 plugins to ensure their dependencies have been loaded before they execute. The builtin
    442 filetype handling for Kakoune is implemented via modules.
    443 
    444 *provide-module* [<switches>] <name> <commands>::
    445     declares a module *name* that is defined by *commands*. *commands* will be
    446     evaluated as if by source the first time *require-module <name>* is run.
    447 
    448     *-override*:::
    449         allow the module to replace an existing one with the same name. Fails if
    450         the module has already been evaluated.
    451 
    452 *require-module* <name>::
    453     guarantees the commands associated with *name* have been evaluated before
    454     continuing command execution. Fails if *name* has not been defined by a
    455     *provide-module* command. Does nothing if the associated commands have
    456     already been evaluated.
    457 
    458 == Multiple commands
    459 
    460 Commands (c.f. previous sections) can be chained, by being separated either
    461 by new lines or by semicolons, as such a semicolon must be escaped with a
    462 backslash (\;) to be considered as a literal semicolon argument.
    463 
    464 To avoid trouble while writing `map` or `execute-keys` commands in scripts,
    465 the alternative key namings `<semicolon>` and `<a-semicolon>` can be used.
    466 
    467 == Declaring new commands
    468 
    469 New commands can be defined using the *define-command* command:
    470 
    471 *define-command* [<switches>] <command_name> <commands>::
    472     *commands* is a string containing the commands to execute, and *switches*
    473     can be any combination of the following parameters:
    474 
    475     *-params* <num>:::
    476         the command accepts a *num* parameter, which can be either a number,
    477         or of the form <min>..<max>, with both <min> and <max> omittable
    478 
    479     *-override*:::
    480         allow the new command to replace an existing one with the same name
    481 
    482     *-hidden*:::
    483         do not show the command in command name completions
    484 
    485     *-docstring*:::
    486         define the documentation string for the command
    487 
    488     *-menu*:::
    489     *-file-completion*:::
    490     *-client-completion*:::
    491     *-buffer-completion*:::
    492     *-command-completion*:::
    493     *-shell-completion*:::
    494     *-shell-script-completion*:::
    495     *-shell-script-candidates*:::
    496         old-style command completion specification, function as-if
    497         the switch and its eventual parameter was passed to the
    498         *complete-command* command
    499         (See <<configuring-command-completion,Configuring command completion>>)
    500 
    501         The use of those switches is discouraged in favor of the
    502         *complete-command* command.
    503 
    504 Using shell expansion allows defining complex commands or accessing
    505 Kakoune's state:
    506 
    507 ---------------------------------------------------------------------
    508 # create a directory for current buffer if it does not exist
    509 define-command mkdir %{ nop %sh{ mkdir -p $(dirname $kak_buffile) } }
    510 ---------------------------------------------------------------------
    511 
    512 == Configuring command completion
    513 
    514 Command completion can be configured with the *complete-command* command:
    515 
    516 *complete-command* [<switches>] <command_name> <completion_type> [<parameter>]::
    517     *switches* can be:
    518 
    519     *-menu*:::
    520         the suggestions generated by the completion options are the only
    521         permitted parameters. Kakoune will autoselect the best completion
    522         candidate on command validation.
    523 
    524     *completion_type* can be:
    525 
    526     *file*:::
    527         try file completion on any parameter passed to the command
    528 
    529     *client*:::
    530         try client name completion on any parameter passed to the command
    531 
    532     *buffer*:::
    533         try buffer name completion on any parameter passed to the command
    534 
    535     *command*:::
    536         try command completion on any parameter passed to the command
    537 
    538     *shell*:::
    539         try shell command completion on any parameter passed to the command
    540 
    541     *shell-script*:::
    542         following string is a shell command which takes parameters as
    543         positional params and outputs one completion candidate per line.
    544         The provided shell command will run after each keypress.
    545         During the execution of the shell command, the following env vars are
    546         available:
    547 
    548         *$kak_token_to_complete*::::
    549             Index of the token being completed in the command line.
    550             Note that unlike the Unix `argv` tradition,
    551             0 is the first argument, not the command name itself.
    552 
    553         *$kak_pos_in_token*::::
    554             Position of the cursor inside the token being completed, in bytes
    555             from token start.
    556 
    557     *shell-script-candidates*:::
    558         following string is a shell script which takes parameters as
    559         positional params and outputs one completion candidate per line.
    560         The provided shell script will run once at the beginning of each
    561         completion session, candidates are cached and then used by kakoune
    562         internal fuzzy engine.
    563 
    564         During the execution of the shell script, the following env vars are
    565         available:
    566 
    567         *$kak_token_to_complete*::::
    568             Index of the token being completed in the command line.
    569             Note that unlike the Unix `argv` tradition,
    570             0 is the first argument, not the command name itself.
    571 
    572 == Aliases
    573 
    574 With `:alias`, commands can be given additional names.
    575 As aliases are intended to be used interactively most of the time,
    576 they are often short. For example `:reg` is an alias for `:set-register`.
    577 
    578 They are scoped, so that an alias can refer to one command for a buffer,
    579 and to another for another buffer. For instance `:next` could be an alias
    580 for `grep-next-match` in a `*grep*` buffer while pointing to
    581 `:make-next-error` in a `*make*` buffer.
    582 
    583 The following command defines `<alias>` as an alias for `<command>`:
    584 
    585 --------------------------------
    586 :alias <scope> <alias> <command>
    587 --------------------------------
    588 
    589 `<scope>` can be one of `global`, `buffer` or `window`.
    590 
    591 -------------------------------------
    592 :unalias <scope> <alias> [<expected>]
    593 -------------------------------------
    594 
    595 Will remove the given alias in the given scope. If `<expected>` is specified
    596 the alias will only be removed if its current value is `<expected>`.
    597