kakoune

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

interfacing.asciidoc (4994B)


      1 Interfacing Kakoune with external programs
      2 ==========================================
      3 
      4 In order to interact with the external world, Kakoune uses the shell, mainly
      5 through the +%sh{ ... }+ string type, and its control socket.
      6 
      7 Basic interaction
      8 -----------------
      9 
     10 For synchronous operations, +%sh{ ... }+ blocks are easy to use, they behave
     11 similarly to +$( ... )+ shell construct.
     12 
     13 For example, one can echo the current time in Kakoune's status line using:
     14 
     15 [source,bash]
     16 ----
     17 :echo %sh{ date }
     18 ----
     19 
     20 For asynchronous operations, the Kakoune Unix stream socket can be used. This
     21 is the same socket that Kakoune clients connect to. It is available through the
     22 +kak_session+ environment variable: the socket is
     23 +/tmp/kakoune/${username}/${kak_session}+
     24 
     25 For example, we can echo a message in Kakoune in 10 seconds with:
     26 
     27 [source,bash]
     28 ----
     29 :nop %sh{ {
     30     sleep 10
     31     echo "eval -client '$kak_client' 'echo sleep ended'" |
     32         kak -p ${kak_session}
     33 } > /dev/null 2>&1 < /dev/null & }
     34 ----
     35 
     36  * The +nop+ command is used so that any eventual output from the
     37    +%sh{ ... }+ is not interpreted by Kakoune
     38  * When writing to the socket, Kakoune has no way to guess in which
     39    client's context the command should be evaluated. A temporary
     40    context is used, which does not have any user interface, so if we want
     41    to interact with the user, we need to use the +eval+ command, with
     42    its +-client+ option to send commands to a specific client.
     43  * For the command to run asynchronously, we wrap it in a sub shell
     44    with braces, redirect its +std{in,err,out}+ to +/dev/null+, and
     45    run it in background with +&+. Using this pattern, the shell does
     46    not wait for this sub shell to finish before quitting.
     47 
     48 Interactive output
     49 ------------------
     50 
     51 It is a frequent interaction mode to run a program and display its output
     52 in a Kakoune buffer.
     53 
     54 The common pattern to do that is to use a fifo buffer:
     55 
     56 [source,bash]
     57 -----
     58 evaluate-commands %sh{
     59      # Create a temporary fifo for communication
     60      output=$(mktemp -d -t kak-temp-XXXXXXXX)/fifo
     61      mkfifo ${output}
     62      # run command detached from the shell
     63      { run command here > ${output} } > /dev/null 2>&1 < /dev/null &
     64      # Open the file in Kakoune and add a hook to remove the fifo
     65      echo "edit! -fifo ${output} *buffer-name*
     66            hook buffer BufClose .* %{ nop %sh{ rm -r $(dirname ${output})} }"
     67 }
     68 -----
     69 
     70 This is a very simple example, most of the time, the echo command will as
     71 well contain
     72 
     73 -----
     74 set buffer filetype <...>
     75 -----
     76 
     77 and some hooks for this filetype will have been written
     78 
     79 Completion candidates
     80 ---------------------
     81 
     82 Filetype specific completion should be provided by external programs.
     83 
     84 External completions are provided using an option to store completion, which
     85 have the following format.
     86 
     87 ----
     88 line.column[+len]@timestamp candidate1|select1|menu1 candidate2|select2|menu2 ...
     89 ----
     90 
     91 the first element of this string list specify where and when this completion
     92 applies, the others are a triplet `<completion text>|<select cmd>|<menu text>`
     93 
     94 The select command is executed whenever this menu item gets selected, and
     95 is usually used to display an item specific documentation with
     96 `info -placement menu '<menu item description>'`
     97 
     98 The menu text is a markup string (see <<faces#markup-strings,`:doc faces
     99 markup-strings`>>), so it can contain `{face}` directives.
    100 
    101 To effectively use that completion option, it should get added to the completers
    102 option.
    103 
    104 ---
    105 set -add buffer completers option=my_option_name
    106 ---
    107 
    108 As a completion program may take some time to compute the candidates, it should
    109 run asynchronously. In order to do that, the following pattern may be used:
    110 
    111 [source,bash]
    112 -----
    113 # Declare the option which will store the temporary filename
    114 decl str plugin_filename
    115 # Declare the completion option
    116 decl completions plugin_completions
    117 # Add plugin_completions to completers for files of good filetype
    118 hook global BufSetOption filetype=my_filetype %{
    119     set -add buffer completers option=plugin_completions
    120 }
    121 evaluate-commands %sh{
    122     # ask Kakoune to write current buffer to temporary file
    123     filename=$(mktemp -t kak-temp.XXXXXXXX)
    124     echo "set buffer plugin_filename '$filename'
    125           write '$filename'"
    126 }
    127 # End the %sh{} so that its output gets executed by Kakoune.
    128 # Use a nop so that any eventual output of this %sh does not get interpreted.
    129 nop %sh{ { # launch a detached shell
    130     buffer="${kak_opt_plugin_filename}"
    131     line="${kak_cursor_line}"
    132     column="${kak_cursor_column}"
    133     # run completer program and format the output in a list of completions
    134     candidates=$(completer $buffer $line $column | completer_filter)
    135     # remove temporary file
    136     rm $buffer
    137     # generate completion option value
    138     completions="$line.$column@$kak_timestamp $candidates"
    139     # write to Kakoune socket for the buffer that triggered the completion
    140     echo "set buffer=${kak_bufname} plugin_completions $completions" |
    141         kak -p ${kak_session}
    142 } > /dev/null 2>&1 < /dev/null & }
    143 -----