3.3.2 Defining New Built-in Commands

While Eshell can run Lisp functions directly as commands, it may be more convenient to provide a special built-in command for Eshell. Built-in commands are just ordinary Lisp functions designed to be called from Eshell. When defining an Eshell-specific version of an existing function, you can give that function a name starting with eshell/ so that Eshell knows to use it.

Macro: eshell-eval-using-options name macro-args options body… ¶

This macro processes a list of macro-args for the command name using a set of command line options. If the arguments are parsed successfully, it will store the resulting values in local symbols and execute body; any remaining arguments will be available in the locally let-bound variable args. The return value is the value of the last form in body.

If an unknown option was passed in macro-args and an external command was specified (see below), this macro will start a process for that command and throw the tag eshell-external with the new process as its value.

options should be a list beginning with one or more elements of the following form, with each element representing a particular command-line switch:

(short long value symbol help-string)

short

This element, if non-nil, should be a character to be used as a short switch, like -short. At least one of this element and long must be non-nil.

long

This element, if non-nil, should be a string to be used as a long switch, like --long.

value

This element is the value associated with the option. It can be either:

t

The option needs a value to be specified after the switch.

nil

The option is given the value t.

anything else

The option is given the specified value.

symbol

This element is the Lisp symbol that will be bound to value. If symbol is nil, specifying this switch will instead call eshell-show-usage, and so is appropriate for an option like --help.

help-string

This element is a documentation string for the option, which will be displayed when eshell-show-usage is invoked.

After the list of command-line switch elements, options can include additional keyword arguments to control how eshell-eval-using-options behaves. Some of these take arguments, while others don’t. The recognized keywords are:

:external string

Specify string as an external command to run if there are unknown switches in macro-args.

:usage string

Set string as the initial part of the command’s documentation string. It appears before the options are listed.

:post-usage string

Set string to be the (optional) trailing part of the command’s documentation string. It appears after the list of options, but before the final part of the documentation about the associated external command, if there is one.

:show-usage

If present, then show the usage message if the command is called with no arguments.

:preserve-args

Normally, eshell-eval-using-options flattens the list of arguments in macro-args and converts each to a string. If this keyword is present, avoid doing that, instead preserving the original arguments. This is useful for commands which want to accept arbitrary Lisp objects.

:parse-leading-options-only

If present, do not parse dash or switch arguments after the first positional argument. Instead, treat them as positional arguments themselves.

For example, you could handle a subset of the options for the ls command like this:

(eshell-eval-using-options
 "ls" macro-args
 '((?a  nil      nil show-all       "show all files")
   (?I  "ignore" t   ignore-pattern "ignore files matching pattern")
   (nil "help"   nil nil            "show this help message")
 :external "ls"
 :usage "[OPTION]... [FILE]...
  List information about FILEs (the current directory by default).")
 ;; List the files in ARGS somehow...
 )