<commit_before>Writing kak scripts
===================

Interaction with external tools from a Kakoune session is supported
through the use of scripts. Once loaded by the editor (either
automatically or manually), they allow extending the functionalities
provided by default through commands and hooks.

Their implementation should be kept as simple as possible, as they are
not meant to be generic tools themselves but a mere API to actual
software.

---------------------------------------------------
	                                       +------+
	                                  +--> | tmux |
	                                  |    +------+
	                                  |
	+---------+                       |    +------+
	| Kakoune | <------->  scripts  +-+--> | X11  |
	+---------+                       |    +------+
	                                  |
	                                  |    +------+
	                                  +--> | ...  |
	                                       +------+
---------------------------------------------------

Dependencies
------------

The amount of dependencies of a given script should be kept to a minimum
for practicality reasons, and have to be reasonable and expected
considering the purpose of the script itself.

Examples:

* the `clang.kak` script provides with code completion using the `clang`
  compiler

* the `tmux.kak` script provides with terminal splitting using the
  `tmux` multiplexer

* the `ctags.kak` script provides with symbol lookups using the
  `readtags` utility provided by some `ctags` implementations

Naming convention
-----------------

All options and commands declared in a Kakoune script have to be
prefixed with the name of the script, or a one word description of the
purpose of the script.

Examples:

* in `tmux.kak`: command `tmux-new-window`

* in `comment.kak`: option `comment_line`

The following conventions apply as well:

* *options*: if a separator is needed to separate a multiple word option
  name, an underscore should be used to allow shell scopes to use them

* *commands*: if a separator is needed, a hyphen is usually used to
  differentiate a command name from an option's

Documentation
-------------

Non-hidden commands and options should always be declared with a documentation
string, so that their purpose is clearly described whenever completed upon
interactively from the prompt.

POSIX shell
-----------

Shell expansions are a useful tool to interact with an external utility,
and the shell code that they contain should be as portable as possible. As
such, scripts that rely on those expansions have to be implemented with
POSIX in mind, most shells follow this standard nowadays which somewhat
guarantees that the script will be portable across the most common systems.

Common shell patterns
---------------------

Printing variables
~~~~~~~~~~~~~~~~~~

In order to print a string that contains a variable expansion, prefer
`printf` to `echo`, as the latter is implementation defined and may
interpret some characters differently depending on the shell (e.g.
flags, backslashes).

----------------------------------
	printf %s\\n "${var}"
	printf "value: %s\\n" "${var}"
----------------------------------

The following won't cause any issues, as the string to print doesn't
contain ambiguous characters:

-------------------------------------
	echo "set global scrolloff 999,0"
-------------------------------------

Variable base name
~~~~~~~~~~~~~~~~~~

Replace `$(basename "${var}")` with `"${var##*/}"`.

Testing
~~~~~~~<commit_msg>doc writing_scripts: Document `echo` portability issues<commit_after>Writing kak scripts
===================

Interaction with external tools from a Kakoune session is supported
through the use of scripts. Once loaded by the editor (either
automatically or manually), they allow extending the functionalities
provided by default through commands and hooks.

Their implementation should be kept as simple as possible, as they are
not meant to be generic tools themselves but a mere API to actual
software.

---------------------------------------------------
	                                       +------+
	                                  +--> | tmux |
	                                  |    +------+
	                                  |
	+---------+                       |    +------+
	| Kakoune | <------->  scripts  +-+--> | X11  |
	+---------+                       |    +------+
	                                  |
	                                  |    +------+
	                                  +--> | ...  |
	                                       +------+
---------------------------------------------------

Dependencies
------------

The amount of dependencies of a given script should be kept to a minimum
for practicality reasons, and have to be reasonable and expected
considering the purpose of the script itself.

Examples:

* the `clang.kak` script provides with code completion using the `clang`
  compiler

* the `tmux.kak` script provides with terminal splitting using the
  `tmux` multiplexer

* the `ctags.kak` script provides with symbol lookups using the
  `readtags` utility provided by some `ctags` implementations

Naming convention
-----------------

All options and commands declared in a Kakoune script have to be
prefixed with the name of the script, or a one word description of the
purpose of the script.

Examples:

* in `tmux.kak`: command `tmux-new-window`

* in `comment.kak`: option `comment_line`

The following conventions apply as well:

* *options*: if a separator is needed to separate a multiple word option
  name, an underscore should be used to allow shell scopes to use them

* *commands*: if a separator is needed, a hyphen is usually used to
  differentiate a command name from an option's

Documentation
-------------

Non-hidden commands and options should always be declared with a documentation
string, so that their purpose is clearly described whenever completed upon
interactively from the prompt.

POSIX shell
-----------

Shell expansions are a useful tool to interact with an external utility,
and the shell code that they contain should be as portable as possible. As
such, scripts that rely on those expansions have to be implemented with
POSIX in mind, most shells follow this standard nowadays which somewhat
guarantees that the script will be portable across the most common systems.

Common shell patterns
---------------------

Printing variables
~~~~~~~~~~~~~~~~~~

In order to print a string that contains a variable expansion, prefer
`printf` to `echo`, as the latter is implementation defined and may
interpret some characters differently depending on the shell (e.g.
flags, backslashes).

----------------------------------
	printf %s\\n "${var}"
	printf "value: %s\\n" "${var}"
----------------------------------

The following won't cause any issues, as the string to print doesn't
contain ambiguous characters:

-------------------------------------
	echo "set global scrolloff 999,0"
-------------------------------------

For more information about portability issues related to `echo`, refer to https://www.etalabs.net/sh_tricks.html[Rich's sh tricks].

Variable base name
~~~~~~~~~~~~~~~~~~

Replace `$(basename "${var}")` with `"${var##*/}"`.

Testing
~~~~~~~
{'fraction_non_alphanumeric': 0.17229129662522202, 'fraction_numerical': 0.0016395682470282825, 'mean_word_length': 1.886435331230284, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 11, 'https://': 1, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7121863', 'n_tokens_mistral': 1735, 'n_tokens_neox': 1624, 'n_words': 811}