'\" t
.\"     Title: kakoune
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/16/2018
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH KAK_EXPANSIONS 1 "" "" "expansions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
expansions \- a
.SH "STRINGS"
.PP
\*(Aqstrings\*(Aq
.RS 4
uninterpreted strings, use a backslash (\e\*(Aq) to escape the separator
.RE
.PP
"strings"
.RS 4
expanded strings, % strings (c\&.f\&. next section) contained are expended, use a backslash (\e\e%) to escape the separator
.RE
.PP
%{strings}
.RS 4
these strings are very useful when entering commands
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the
\fI{\fR
and
\fI}\fR
delimiters are configurable, you can use any non alphanumeric character
.sp
.if n \{\
.RS 4
.\}
.nf
e\&.g\&. %[string], %<string>, %(string), %~string~, %!string!
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if the character following
\fI%\fR
is one of
\fI{[(<\fR, then the closing one is the matching
\fI}])>\fR
and the delimiters are not escapable but are nestable
.sp
.if n \{\
.RS 4
.\}
.nf
e\&.g\&. %{ roger {}; } is a valid string, %{ marcel \e} as well
.fi
.if n \{\
.RE
.\}
.RE
.RE
.SH "TYPED EXPANSIONS"
.PP
\fBsh\fR
.RS 4
shell expansion, similar to posix shell
\fI$(\&...)\fR
construct (c\&.f\&. next section)
.RE
.PP
\fBreg\fR
.RS 4
register expansion, will be replaced by the content of the given register
.RE
.PP
\fBopt\fR
.RS 4
option expansion, will be replaced with the value of the given option
.RE
.PP
\fBval\fR
.RS 4
value expansion, gives access to the environment variable available to the Shell expansion\&. The
\fIkak_\fR
prefix is not used there
.RE
.PP
\fBarg\fR
.RS 4
argument expansion, gives access to the arguments of the current command, the content can be a number, or @ for all arguments
.RE
.SH "SHELL EXPANSIONS"
.sp
The \fI%sh{\&...}\fR expansion replaces its content with the output of the shell commands in it\&. The following environment variables are used to pass information about Kakoune\(cqs state:
.PP
\fBkak_selection\fR
.RS 4
content of the main selection
.RE
.PP
\fBkak_selections\fR
.RS 4
content of the selection separated by colons, colons in the selection contents are escaped with a backslash
.RE
.PP
\fBkak_selection_desc\fR
.RS 4
range of the main selection, represented as anchor,cursor; anchor and cursor are in this format: line\&.column
.RE
.PP
\fBkak_selections_desc\fR
.RS 4
range of the selections separated by colons
.RE
.PP
\fBkak_bufname\fR
.RS 4
name of the current buffer
.RE
.PP
\fBkak_buffile\fR
.RS 4
full path of the file or same as kak_bufname when there\(cqs no associated file
.RE
.PP
\fBkak_buflist\fR
.RS 4
the current buffer list, each buffer separated by a colon
.RE
.PP
\fBkak_timestamp\fR
.RS 4
timestamp of the current buffer, the timestamp is an integer value which is incremented each time the buffer is modified
.RE
.PP
\fBkak_runtime\fR
.RS 4
directory containing the kak binary
.RE
.PP
\fBkak_count\fR
.RS 4
count parameter passed to the command
.RE
.PP
\fBkak_opt_<name>\fR
.RS 4
value of option
\fBname\fR
.RE
.PP
\fBkak_reg_<r>\fR
.RS 4
value of register
\fBr\fR
.RE
.PP
\fBkak_socket\fR
.RS 4
filename of session socket (\fI/tmp/kak\-<session>\fR)
.RE
.PP
\fBkak_session\fR
.RS 4
name of the current session
.RE
.PP
\fBkak_client\fR
.RS 4
name of current client
.RE
.PP
\fBkak_cursor_line\fR
.RS 4
line of the end of the main selection
.RE
.PP
\fBkak_cursor_column\fR
.RS 4
column of the end of the main selection (in byte)
.RE
.PP
\fBkak_cursor_char_column\fR
.RS 4
column of the end of the main selection (in character)
.RE
.PP
\fBkak_window_width\fR
.RS 4
width of the current kakoune window
.RE
.PP
\fBkak_window_height\fR
.RS 4
height of the current kakoune window
.RE
.PP
\fBkak_hook_param\fR
.RS 4
filtering text passed to the currently executing hook
.RE
.PP
\fBkak_client_env_<name>\fR
.RS 4
value of the
\fBname\fR
variable in the client environment (e\&.g\&.
\fB$kak_client_env_SHELL\fR
is the SHELL variable)
.RE
.sp
Note that in order for Kakoune to pass a value in the environment, the variable has to be spelled out within the body of the expansion
.SH "MARKUP STRINGS"
.sp
In certain contexts, Kakoune can take a markup string, which is a string syntax will enable the face facename until another face gets activated, or the end of the string is reached\&.
.sp
Literal \fI{\fR characters shall be written \fI{\fR, and a literal backslash (\fI\e\fR) that precedes a \fI{\fR character shall be escaped as well (\fI\e\e\fR)\&.