diff --git a/README.asciidoc b/README.asciidoc index 2b8530b74..bb4a782a6 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1,4 +1,5 @@ = image:{logo}[K,30,30,link="{website}"] Kakoune image:{travis-img}[link="{travis-url}"] image:{irc-img}[link="{irc-url}"] +ifdef::env-github,env-browser[:outfilesuffix: .asciidoc] :logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg :website: http://kakoune.org :travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master @@ -733,126 +734,10 @@ Multiple commands can be separated either by new lines or by semicolons, as such a semicolon must be escaped with `\;` to be considered as a literal semicolon argument. -String syntax -~~~~~~~~~~~~~ +String syntax and expansions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When entering a command, parameters are separated by whitespace (shell like), -if you want to give parameters with spaces, you should quote them. - -Kakoune support three string syntax: - - * `'strings'`: uninterpreted strings, you can use `\'` to escape the separator, - every other char is itself. - - * `"strings"`: expanded strings, % strings (see <>) contained - are expended. Use \% to escape a % inside them, and \\ to escape a slash. - - * `%{strings}`: these strings are very useful when entering commands - - - the `{` and `}` delimiters are configurable: you can use any non - alphanumeric character, e.g. `%[string]`, `%`, `%(string)`, - `%\~string~`, `%!string!`. - - if the character following the % is one of {[(<, then the closing one is - the matching }])> and the delimiters are not escapable but are nestable. - For example `%{ roger {}; }` is a valid string, `%{ marcel \}` as well. - -Expansions -^^^^^^^^^^ - -A special kind of `%{strings}` can be used, with a type between -`%` and the opening delimiter (which cannot be alphanumeric). These -strings are expanded according to their type. - -For example `%opt{autoinfo}` is of type 'opt'. 'opt' expansions are replaced -by the value of the given option (here `autoinfo`). - -Supported types are: - - * `sh`: shell expansion, similar to posix shell $(...) construct, see - <> for more details. - * `reg`: register expansion, will be replaced by the content of the given - register. - * `opt`: option expansion, will be replaced with the value of the given - option - * `val`: value expansion, gives access to the environment variable available - to the Shell expansion. The `kak_` prefix is not used there. - * `arg`: argument expansion, gives access to the arguments of the current - command, the content can be a number, or `@` for all arguments. - -For example, you can display last search pattern with - -------------- -:echo %reg{/} -------------- - -Shell expansion -^^^^^^^^^^^^^^^ - -The `%sh{...}` expansion replaces its content with the output of the shell -commands in it. It is similar to the shell $(...) syntax and is evaluated -only when needed. - -For example: `%sh{ ls }` is replaced with the output of the ls command. - -Some of Kakoune state is available through environment variables: - - * `kak_selection`: content of the main selection - * `kak_selections`: content of the selection separated by colons, colons and backslashes in - the selection contents are escaped with a backslash. - * `kak_selection_desc`: range of the main selection, represented as `anchor,cursor`; - anchor and cursor are in this format: `line.column` - * `kak_selections_desc`: range of the selections separated by colons - * `kak_bufname`: name of the current buffer - * `kak_buffile`: full path of the file or same as `kak_bufname` when - there's no associated file - * `kak_buflist`: the current buffer list, each buffer separated by a colon - * `kak_buf_line_count`: the current buffer line count - * `kak_timestamp`: timestamp of the current buffer, the timestamp is an - integer value which is incremented each time the buffer is modified. - * `kak_history_id`: history id of the current buffer, the history id is an integer value - which is used to reference a specific buffer version in the undo tree - * `kak_runtime`: directory containing the kak binary - * `kak_count`: count parameter passed to the command - * `kak_opt_`: value of option - * `kak_reg_`: value of register - * `kak_session`: name of the current session - * `kak_client`: name of the current client - * `kak_client_pid`: pid of the current client - * `kak_client_list`: list of clients connected to the current session - * `kak_modified`: buffer has modifications not saved - * `kak_source`: path of the file currently getting executed (through the source command) - * `kak_cursor_line`: line of the end of the main selection - * `kak_cursor_column`: column of the end of the main selection (in byte) - * `kak_cursor_char_value`: unicode value of the codepoint under the cursor - * `kak_cursor_char_column`: column of the end of the main selection (in character) - * `kak_cursor_byte_offset`: offset of the main selection from the beginning of the buffer (in byte). - * `kak_window_width`: width of the current kakoune window - * `kak_window_height`: height of the current kakoune window - * `kak_hook_param`: filtering text passed to the currently executing hook - * `kak_hook_param_capture_N`: text captured by the hook filter regex capture N - * `kak_client_env_`: value of the variable in the client environment. - Example: $kak_client_env_SHELL is the SHELL variable - -Note that in order to make only needed information available, Kakoune needs -to find the environment variable reference in the shell script executed. -Hence, `%sh{ ./script.sh }` with `script.sh` referencing an environment -variable will not work. - -For example, you can print informations on the current file in the status -line using: - ------------------------------------- -:echo -- "%sh{ ls -l $kak_bufname }" ------------------------------------- - -Markup strings -^^^^^^^^^^^^^^ - -In certain context, kakoune can take a markup string, which is a string containing -formatting informations. In these strings, syntax `{facename}` will enable the -face _facename_ until another face gets activated (or the end of the string. -Literal `{` shall be written `\{`, and literal `\` that precede a `{` shall -be written `\\` +See <>. Configuration & Autoloading --------------------------- @@ -889,260 +774,21 @@ precedence. Options ------- -For user configuration, Kakoune supports options. +See <>. -Options are typed, their type can be - - * `int`: an integer number - * `bool`: a boolean value, `yes/true` or `no/false` - * `str`: a string, some freeform text - * `coord`: a line,column pair (separated by comma) - * `regex`: as a string but the `set` commands will complain - if the entered text is not a valid regex. - * `{int,str}-list`: a list, elements are separated by a colon (:) - if an element needs to contain a colon, it can be escaped with a - backslash. - * `range-specs`: a `:` separated list of a pair of a buffer range - (`.,.` or - `.+`) and a string (separated by `|`), - except for the first element which is just the timestamp of the buffer. - * `line-flags`: a `:` separated list of a line number and a corresponding - flag (`|`), except for the first element which is just - the timestamp of the buffer. - * `completions`: a `:` separated list of `||` - candidates, except for the first element which follows the - `.[+]@` format to define where the - completion apply in the buffer. Markup can be used in the menu text. - * `enum(value1|value2|...)`: an enum, taking on of the given values - * `flags(value1|value2|...)`: a set of flags, taking a combination - of the given values joined by `|`. - -Options value can be changed using the `set` commands: - ------------------------------------------------------------------------------- -:set [global,buffer,window]