kakoune

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

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