bex

• Index

Contents

• Class context

Modules

• bex.autoload.augroup
• bex.autoload.autocmd
• bex.autoload.command
• bex.bridge
• bex.builtin.map
• bex.cmd
• bex.keymap
• bex.param

Topics

• Manual

Module bex.cmd

Ex command bridge.

Basic Usage

Exposes Ex commands as Lua functions. To use a command as a function, simply index this module, e.g:

local cmd = require('bex.cmd')
cmd.echo("Hello, world!")

Append .bang to a command to access its ! variant:

cmd.normal.bang('gvGG')

This also works:

cmd['normal!']('gvGG')

You can capture output using the .output modifier:

local hello = cmd.echo.output("Hello, world!")

Controlling Behavior

Parameters Handling

How function arguments are formatted can be overridden by setting a list of parameter handlers on a command function. The bex.param module contains a set of useful stock handlers. For example, the echo command has its parameters defined roughly as follows

local param = require('bex.param')

-- Double-quote all parameters
cmd.echo.params = {_ = param.quote}

The Plug command from the popular vim-plug package can be wrapped as follows:

cmd.Plug.params = {param.squote, param.call(vim.fn.string)}
cmd.Plug.separator = ", "

You can write custom parameter handlers as functions that take a command context object and make appropriate method calls to it. A handler can pop remaining function parameters off the stack and add tokens to the formatted command as it sees fit. There is no strict one-to-one correspondence between input parameters and output tokens. The param.cmd handler is a good example of a sophisticated parameter handler:

function param.cmd(bridge_ns)
    return function(ctx)
        it = ctx:pop()
        if bridge_ns and vim.is_callable(it) then
            it = "call v:lua." .. bridge_ns[it] .. "()"
            ctx:raw(it)
        else
            ctx:push(it)
            while ctx:remaining() ~= 0 do
                ctx:raw(ctx:pop())
            end
        end
    end
end

Given a bex.bridge namespace, it returns a handler that can accept either a Lua callable or a series of raw tokens forming the command.

Parameter handlers are invoked sequentially until all parameters have been handled. The _ handler, if present, is invoked repeatedly to handle any trailing parameters. The final command is formed from all tokens interspered with the separator field on the command function (default " "). If fewer parameters were passed than handlers wished to consume, the command is still executed with as many tokens were generated to that point. This allows many Ex commands that take variable arguments to "just work", e.g.:

-- Passing one argument works
cmd.augroup('foo')
cmd.augroup('END')
-- Passing none also works.  This scrapes all defined autocommand groups.
local dump = cmd.augroup.output()

Pre and Post Functions

You can further customize behavior of the command by overriding pre and post functions. The defaults for a given command look like:

-- Receives the command string to be executed, and may return
-- a modified version
function cmd.<cmd>.pre(ctx, cmdstr)
    return cmdstr
end

-- Receives the result from executing the command (nil if not
-- capturing output) and mat return something different
function cmd.<cmd>.post(ctx, result)
    return result
end

Autoloading

When a command function is first accessed, bex will attempt to load bex.autoload.<cmd> (without any trailing !) as a Lua module if it exists. This module should set up any parameter handlers, etc. Modules are provided for several built-in Ex commands.

Bex does not presently understand abbreviations, so you should always use the full name of a command to ensure overrides are loaded for it.

Class context

context:pop ()	Pop next argument.
context:push (arg)	Push argument back on stack.
context:remaining ()	Remaining arguments.
context:raw (arg)	Emit raw token.
context:escape (arg, chars)	Emit escaped token.
context:fname (arg)	Emit filename token.
context:squote (arg)	Emit single-quoted token.
context:quote (arg)	Emit double-quoted token.

Class context

context:pop ()

Pop next argument.

Pops the next function argument for the command off the stack.

Returns:

The argument

context:push (arg)

Push argument back on stack.

Pushes an unwanted argument back on the stack so it can be consumed by the next handler.

Parameters:

• arg The argument

context:remaining ()

Remaining arguments.

Get count of remaining arguments on the stack. by the next handler.

Returns:

The count.

context:raw (arg)

Emit raw token.

Adds a token to the formatted command with no escaping.

Parameters:

• arg The token.

context:escape (arg, chars)

Emit escaped token.

Adds a token to the formatted command with the specified characters escaped with backslashes.

Parameters:

• arg The token.
• chars A string containing characters to escape.

context:fname (arg)

Emit filename token.

Adds a token to the formatted command escaped using the fnameescape Vim function.

Parameters:

• arg The token.

context:squote (arg)

Emit single-quoted token.

Adds a token to the formatted command enclosed in single quotes. It is an error for the argument to contain any single quote character itself.

Parameters:

• arg The token.

context:quote (arg)

Emit double-quoted token.

Adds a token to the formatted command enclosed in double quotes, with any double quotes or backslashes within the token escaped with backslashes.

Parameters:

• arg The token.