Expansions are text substitutions that happen right before a command is evaluated.
They have the form: `@expansion-name(expansion-args)`.

`expansion-args`'s semantics depend on which expansion is being handled.
If an expansion fails to parse its argument, it will not expand and its text will remain untouched.

Expansions can occur as a standalone argument to a command or inside a quoted (`"..."`, `'...'` or `{...}`) argument.
However, in the quoted case, it's possible to disable expansions altogether by adding a `@` to the quote.
That is: `@"..."`, `@'...'` or `@{...}`.

# expansions

## `arg`
When used inside a command declared using the `command` command, expands to the `<index>`th argument it received whell called.
If instead of a zero-based index, its argument is `!`, it expands to `!` if the command was called with a bang
(that is, `command! ...`) and to ` ` (empty) otherwise.
Also, this expansion's argument can be `*` which will make it expand to all arguments passed to the called command.
In general, `@arg(*)` do not play well inside quoted arguments and are better used when creating command aliases.
That is, something akin to `command my-alias @{ my-alised-command@arg(!) @arg(*) }`.
- usage: `@arg(<index>)` `@arg(!)` `@arg(*)`

## `client-id`
The zero-based id of the current editor client.
Note that a client id of 3, does not imply that there are other 3 clients present (0, 1 and 2)
as they may be no longer active ids.
If there is no such client, it results in an empty expansion.
- usage: `@client-id()`

## `buffer-id`
The zero-based id of the current buffer.
Note that a buffer id of 3, does not imply that there are other 3 buffers present (0, 1 and 2)
as they may be no longer active ids.
If there is no such buffer, it results in an empty expansion.
- usage `@buffer-id()`

## `buffer-path`
The buffer path as it appears in the statusbar of the current buffer or of the buffer with id `<id>`.
If there is no such buffer, it results in an empty expansion.
- usage: `@buffer-path()` `@buffer-path(<id>)`

## `buffer-absolute-path`
The absolute path of the current buffer or of the buffer with id `<id>`.
If there is no such buffer, it results in an empty expansion.
- usage: `@buffer-absolute-path()` `@buffer-absolute-path(<id>)`

## `buffer-content`
All the text content inside the current buffer or of the buffer with id `<id>`.
If there is no such buffer, it results in an empty expansion.
Lines are always separated by `\n`.
- usage: `@buffer-content()` `@buffer-content(<id>)`

## `command-source`
The evaluated source of command `<command-name>`.
Will only work for macro commands and not for builtins.
- usage: `@command-source(<command-name>)`

## `cursor-anchor-column`
The column byte number (one-based) of the anchor of the current cursor or of the cursor of index `<index>`.
If there is no such cursor, it results in an empty expansion.
- usage: `@cursor-anchor-column()` `@cursor-anchor-column(<index>)`

## `cursor-anchor-line`
The line number (one-based) of the anchor of the current cursor or of the cursor of index `<index>`.
If there is no such cursor, it results in an empty expansion.
- usage: `@cursor-anchor-line()` `@cursor-anchor-line(<index>)`

## `cursor-position-column`
The column byte number (one-based) of the position of the of the current cursor or of the cursor of index `<index>`.
If there is no such cursor, it results in an empty expansion.
- usage: `@cursor-position-column()` `@cursor-position-column(<index>)`

## `cursor-position-line`
The line number (one-based) of the position of the current cursor or of the cursor of index `<index>`.
If there is no such cursor, it results in an empty expansion.
- usage: `@cursor-position-line()` `@cursor-position-line(<index>)`

## `cursor-selection`
The text selected by the current cursor or of the cursor of index `<index>`.
If there is no such cursor, it results in an empty expansion.
- usage: `@cursor-selection()` `@cursor-selection(<index>)`

## `picker-entry`
The selected entry by the user when prompted by the `pick` command.
- usage: `@picker-entry()`

## `register`
The text inside the register under the key `<key>`.
Note that there are some registers that contain internal state:
- `a` auto macro register: the keys from the last edit action
- `s` search register: the current search pattern
- `p` prompt register: the current readline and picker prompt text
- `i` input register: the current readline and picker input text
- `c` comment register: the text used to to comment/uncomment lines

- usage: `@register(<key>)`

## `session-name`
The editor session name.
Either the value passed to the `--session` flag when invoking the editor, or a hash of the current directory when invoked.
This is used when connecting servers and clients.
That is, the name of the NamedPipe on windows and the name of the DomainSocket on unix.
- usage: `@session-name()`

## `platform`
The name of the platform the editor is running on.
Can evaluate to one of:
- `windows`
- `linux`
- `bsd`
- `macos`
- `unknown`

- usage: `@platform()`

## `pid`
The process id of the server.
- usage: `@pid()`

## `env`
The environment variable of name `<name>`.
If there is no such environment variable, it results in an empty expansion.
- usage: `@env(<name>)`

## `output`
The stdout of external `<command>` (spawned with stdin closed).
Will result in an emtpy expansion if the command fails.
- usage: `@output(<command>)`