cc.shell.completion

A collection of helper methods for working with shell completion.

Most programs may be completed using the build helper method, rather than manually switching on the argument index.

Note, the helper functions within this module do not accept an argument index, and so are not directly usable with the shell.setCompletionFunction. Instead, wrap them using build, or your own custom function.

See also

file(shell, choices)Complete the name of a file relative to the current working directory.
dir(shell, choices)Complete the name of a directory relative to the current working directory.
dirOrFile(shell, choices, previous[, add_space])Complete the name of a file or directory relative to the current working directory.
program(shell, choices)Complete the name of a program.
helpWraps help.completeTopic as a build compatible function.
choiceWraps cc.completion.choice as a build compatible function.
peripheralWraps cc.completion.peripheral as a build compatible function.
sideWraps cc.completion.side as a build compatible function.
settingWraps cc.completion.setting as a build compatible function.
commandWraps cc.completion.command as a build compatible function.
build(...)A helper function for building shell completion arguments.
file(shell, choices)Source

Complete the name of a file relative to the current working directory.

Parameters

  1. shell table The shell we're completing in
  2. choices { string... } The list of choices to complete from.

Returns

  1. { string... } A list of suffixes of matching files.
dir(shell, choices)Source

Complete the name of a directory relative to the current working directory.

Parameters

  1. shell table The shell we're completing in
  2. choices { string... } The list of choices to complete from.

Returns

  1. { string... } A list of suffixes of matching directories.
dirOrFile(shell, choices, previous[, add_space])Source

Complete the name of a file or directory relative to the current working directory.

Parameters

  1. shell table The shell we're completing in
  2. choices { string... } The list of choices to complete from.
  3. previous { string... } The shell arguments before this one.
  4. add_space? boolean Whether to add a space after the completed item.

Returns

  1. { string... } A list of suffixes of matching files and directories.
program(shell, choices)Source

Complete the name of a program.

Parameters

  1. shell table The shell we're completing in
  2. choices { string... } The list of choices to complete from.

Returns

  1. { string... } A list of suffixes of matching programs.

See also

helpSource

Wraps help.completeTopic as a build compatible function.

choiceSource

Wraps cc.completion.choice as a build compatible function.

peripheralSource

Wraps cc.completion.peripheral as a build compatible function.

sideSource

Wraps cc.completion.side as a build compatible function.

settingSource

Wraps cc.completion.setting as a build compatible function.

commandSource

Wraps cc.completion.command as a build compatible function.

build(...)Source

A helper function for building shell completion arguments.

This accepts a series of single-argument completion functions, and combines them into a function suitable for use with shell.setCompletionFunction.

Parameters

  1. ... nil | table | function

    Every argument to build represents an argument to the program you wish to complete. Each argument can be one of three types:

    • nil: This argument will not be completed.
    • A function: This argument will be completed with the given function. It is called with the shell object, the string to complete and the arguments before this one.
    • A table: This acts as a more powerful version of the function case. The table must have a function as the first item - this will be called with the shell, string and preceding arguments as above, but also followed by any additional items in the table. This provides a more convenient interface to pass options to your completion functions.

    If this table is the last argument, it may also set the many key to true, which states this function should be used to complete any remaining arguments.

Usage

  • Prompt for a choice of options, followed by a directory, and then multiple files.

    complete.build(
      { complete.choice, { "get", "put" } },
      complete.dir,
      { complete.file, many = true }
    )