howl.command

Overview

Functions

Overview

The howl.command module acts as the central registry of commands in Howl, and lets you register new commands, get information about currently available commands and execute commands directly.

A command is a named piece of functionality initiated by the user, such as the open command that opens a file, or the save command that saves the current buffer. The user can invoke commands either explicitly by opening the command line and typing the name of the command, or indirectly via pressing a key binding. The command module keeps track of all available commands in Howl and uses interactions to read user input as necessary.

From an implementation perspective, a command definition is a simple table that provides the name of the command, a description, an optional input function and a handler function. As an example, consider a possible definition of an open command:

howl.command.register
  name: 'open',
  description: 'Open a file'
  input: howl.interact.select_file
  handler: (file) -> howl.app\open_file file

When the user invokes this command, the input function is called first. In this case an interaction called select_file is used as the input function. It displays the command line and a completion list, allowing the user to navigate the file system and select a file. The select_file function returns a File object for the selected file. The handler function is then called and passed the File object as an argument. This invokes the open_file function to open the file.

If an input function returns nil, or raises an error, the handler is not called. The input field is optional and commands that provide it are called interactive commands. If a command does not specify an input, the handler function is called directly with no arguments.

While any function can serve as the input, inputs often use interactions. Using interactions allows easy re-use of common user interaction patterns such as asking the user a yes/no question or getting the user to select a directory.

Commands can be invoked via code by calling howl.command.run or calling the command name directly as a field of command module, for example howl.command.save!, which invokes the “save” command. Command names that contain special characters such as hyphens and spaces can be invoked by an accessible name, in which all special characters are replaced with underscores. For example, the “buffer-reload” command can be invoked via howl.command.buffer_reload!

See also:

The spec for howl.command
The interact module for more information about interactions

Functions

alias (target, name, opts = {})

Creates an alias, name for an existing command, target. The command specified by target is required to exist when calling this function. opts is an optional table of options. Currently it can contain one field:

deprecated: If set to true, the alias is marked as deprecated. This will show in the command completion.

get (name)

Retrieves the command definition for the command with name name, or nil if no such command is present.

names ()

Returns a list of names for the currently available commands.

register (def)

Registers a new command. def is a table containing the following fields:

name: [required] The name of the command.
description: [required] A short description of the command.
handler: [required] A function that is invoked to execute the command. The handler receives arguments returned by the input field, if provided.
input: [optional] A function that is invoked to read user input. If present, this function is invoked before the handler, and all return values are passed to the handler as arguments.

run (cmd_string = nil)

Parses and runs cmd_string, if given. If cmd_string is not provided, then the command line is displayed and the user is prompted for the command to run. If cmd_string refers to an interactive command, the input function is called first, and the results of the input function are passed to the handler function.

Interactive commands can be invoked with a string containing the command name followed by a space and some additional text, which then gets handled by the command’s input function. For example command.run "open path/to/folder" behaves the same as running open and then typing “path/to/folder”.

Here are some examples of invoking commands using the run function:

howl.command.run "save"  -- invokes "save"

howl.command.run "buffer-reload"  -- invokes "buffer_reload"

-- The following invokes the "open" command. Since it is an interactive command,
-- this displays the command line and lets the user select a file to open.
howl.command.run "open"

unregister (name)

Unregisters the command with name name, along with any aliases pointing to the command.

Direct command call

Indexing the command module itself using any command name returns a function that can be used to invoke the command. When invoked this way, arguments may be provided to the function that are passed through directly to the handler. The input function is not run for interactive commands invoked this way.

Commands that have special characters such as hyphens or spaces in their name can be indexed by using an accessible command name, in which all special characters of the original command name are replaced with underscores.

Here are some examples of invoking commands via the direct call:

howl.command.save!  -- invoke "save"

howl.command.buffer_reload!  -- invokes "buffer-reload"

-- The following invokes the "open" command, but does not prompt the user for
-- a file to open. It just opens /path/to/myfile
howl.command.open howl.io.File('/path/to/some_file')