Skip to main content

core.command

Functions to register and handle commands.

local command = require "core.command"

map​

(field) map: { [string]: core.command.command }

core.command.command​

The predicate and its associated function.

perform​

(field) perform: fun(...any)

predicate​

(field) predicate: fun(...any):boolean, ...unknown

A predicate function accepts arguments from command.perform() and evaluates to a boolean. If the function returns true, then the function associated with the command is executed.

The predicate function can also return other values after the boolean, which will be passed into the function associated with the command.

core.command.command_name​

A command is identified by a command name. The command name contains a category and the name itself, separated by a colon (':').

All commands should be in lowercase and should not contain whitespaces; instead they should be replaced by a dash ('-').

core.command.predicate​

A predicate is a string, an Object or a function, that is used to determine whether a command should be executed.

If the predicate is a string, it is resolved into an Object via require() and checked against the active view with Object:extends(). For example, "core.docview" will match any view that inherits from DocView. A ! can be appended to the predicate to strictly match the current view via Object:is(), instead of matching any view that inherits the predicate.

If the predicate is a table, it is checked against the active view with Object:extends(). Strict matching via Object:is() is not available.

If the predicate is a function, it must behave like a predicate function.

core.command.predicate_function​

A predicate function accepts arguments from command.perform() and evaluates to a boolean. If the function returns true, then the function associated with the command is executed.

The predicate function can also return other values after the boolean, which will be passed into the function associated with the command.

add​

function core.command.add(predicate?: string|core.object|fun(...any):boolean, ...unknown, map: { [string]: fun(...any) })

Adds commands to the map.

The function accepts a table containing a list of commands and their functions. If a command already exists, it will be replaced. See:

@param predicate?: string|core.object|fun(...any):boolean, ...unknown — A predicate is a string, an Object or a function, that is used to determine whether a command should be executed.

If the predicate is a string, it is resolved into an Object via require() and checked against the active view with Object:extends(). For example, "core.docview" will match any view that inherits from DocView. A ! can be appended to the predicate to strictly match the current view via Object:is(), instead of matching any view that inherits the predicate.

If the predicate is a table, it is checked against the active view with Object:extends(). Strict matching via Object:is() is not available.

If the predicate is a function, it must behave like a predicate function.

add_defaults​

function core.command.add_defaults()

Inserts the default commands for Pragtical into the map.

generate_predicate​

function core.command.generate_predicate(predicate: string|core.object|fun(...any):boolean, ...unknown|nil)
  -> fun(...any):boolean, ...unknown

This function takes in a predicate and produces a predicate function that is internally used to dispatch and execute commands.

This function should not be called manually. See: core.command.predicate

@param predicate: string|core.object|fun(...any):boolean, ...unknown|nil — If nil, the predicate always evaluates to true.

get_all_valid​

function core.command.get_all_valid()
  -> string[]

Returns all the commands that can be executed (their predicates evaluate to true).

is_valid​

function core.command.is_valid(name: string, ...any)
  -> boolean

Checks whether a command can be executed (its predicate evaluates to true).

@param name: string — A command is identified by a command name. The command name contains a category and the name itself, separated by a colon (':').

All commands should be in lowercase and should not contain whitespaces; instead they should be replaced by a dash ('-').

perform​

function core.command.perform(name: string, ...any)
  -> boolean

Performs a command.

The arguments passed into this function are forwarded to the predicate function. If the predicate function returns more than 1 value, the other values are passed to the command.

Otherwise, the arguments passed into this function are passed directly to the command. See:

@param name: string — A command is identified by a command name. The command name contains a category and the name itself, separated by a colon (':').

All commands should be in lowercase and should not contain whitespaces; instead they should be replaced by a dash ('-').

@return: boolean — true if the command is performed successfully.

prettify_name​

function core.command.prettify_name(name: string)
  -> string

Prettifies the command name.

This function adds a space between the colon and the command name, replaces dashes with spaces and capitalizes the command appropriately. See: core.command.command_name

@param name: string — A command is identified by a command name. The command name contains a category and the name itself, separated by a colon (':').

All commands should be in lowercase and should not contain whitespaces; instead they should be replaced by a dash ('-').