writing_scripts.asciidoc (4974B)
1 Writing kak scripts 2 =================== 3 4 Interaction with external tools from a Kakoune session is supported 5 through the use of scripts. Once loaded by the editor (either 6 automatically or manually), they allow extending the functionalities 7 provided by default through commands and hooks. 8 9 Their implementation should be kept as simple as possible, as they are 10 not meant to be generic tools themselves but a mere API to actual 11 software. 12 13 --------------------------------------------------- 14 +------+ 15 +--> | tmux | 16 | +------+ 17 | 18 +---------+ | +------+ 19 | Kakoune | <-------> scripts +-+--> | X11 | 20 +---------+ | +------+ 21 | 22 | +------+ 23 +--> | ... | 24 +------+ 25 --------------------------------------------------- 26 27 Dependencies 28 ------------ 29 30 The amount of dependencies of a given script should be kept to a minimum 31 for practicality reasons, and have to be reasonable and expected 32 considering the purpose of the script itself. 33 34 Examples: 35 36 * the `clang.kak` script provides with code completion using the `clang` 37 compiler 38 39 * the `tmux.kak` script provides with terminal splitting using the 40 `tmux` multiplexer 41 42 * the `ctags.kak` script provides with symbol lookups using the 43 `readtags` utility provided by some `ctags` implementations 44 45 Naming convention 46 ----------------- 47 48 All options and commands declared in a Kakoune script have to be 49 prefixed with the name of the script, or a one word description of the 50 purpose of the script. 51 52 Examples: 53 54 * in `tmux.kak`: command `tmux-new-window` 55 56 * in `comment.kak`: option `comment_line` 57 58 The following conventions apply as well: 59 60 * *options*: if a separator is needed to separate a multiple word option 61 name, an underscore should be used to allow shell scopes to use them 62 63 * *commands*: if a separator is needed, a hyphen is usually used to 64 differentiate a command name from an option's 65 66 Documentation 67 ------------- 68 69 Non-hidden commands and options should always be declared with a documentation 70 string, so that their purpose is clearly described whenever completed upon 71 interactively from the prompt. 72 73 POSIX shell 74 ----------- 75 76 Shell expansions are a useful tool to interact with an external utility, 77 and the shell code that they contain should be as portable as possible. As 78 such, scripts that rely on those expansions have to be implemented with 79 POSIX in mind, most shells follow this standard nowadays which somewhat 80 guarantees that the script will be portable across the most common systems. 81 82 Common shell patterns 83 --------------------- 84 85 Printing variables 86 ~~~~~~~~~~~~~~~~~~ 87 88 In order to print a string that contains a variable expansion, prefer 89 `printf` to `echo`, as the latter is implementation defined and may 90 interpret some characters differently depending on the shell (e.g. 91 flags, backslashes). 92 93 ---------------------------------- 94 printf %s\\n "${var}" 95 printf "value: %s\\n" "${var}" 96 ---------------------------------- 97 98 The following won't cause any issues, as the string to print doesn't 99 contain ambiguous characters: 100 101 ------------------------------------- 102 echo "set global scrolloff 999,0" 103 ------------------------------------- 104 105 For more information about portability issues related to `echo`, refer to https://www.etalabs.net/sh_tricks.html[Rich's sh tricks]. 106 107 Variable base name 108 ~~~~~~~~~~~~~~~~~~ 109 110 Replace `$(basename "${var}")` with `"${var##*/}"`. 111 112 Testing 113 ~~~~~~~ 114 115 The `[[` keyword is provided by `bash`, and should be replaced with `[`. 116 117 Standard error redirection 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 119 120 Redirecting both standard and error streams is simplified in the `bash` 121 shell with the `&>` operator, however this syntax is not portable and 122 has to be replaced with the following: `>/dev/null 2>&1`. 123 124 Regular expression 125 ~~~~~~~~~~~~~~~~~~ 126 127 The `bash` shell provides with a `[[` keyword that supports the `=~` 128 operator to match a regular expression against a variable. This 129 functionality can be implemented with the `expr` utility: 130 131 * `expr "${var}" : '[a-z]*' >/dev/null` returns successfully when the 132 variable is empty or only contains lowercase characters, otherwise a 133 non-zero exit code is returned 134 135 * `expr "${var}" : '\([a-z]*\)'` prints the variable when empty or 136 only contains lowercase characters 137 138 Note that the regular expression matches the whole string, using the `^` 139 and `$` anchors is an undefined behavior. 140 141 Running a process in the background 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 143 144 In order to get a process running in the background without having it 145 quit when the shell scope that spawns it terminates, use the following 146 syntax: 147 148 -------------------------------- 149 { 150 command 151 } </dev/null >/dev/null 2>&1 & 152 --------------------------------