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