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.

Usage

• Register a completion handler for example.lua which prompts for a choice of options, followed by a directory, and then multiple files.

  local completion = require "cc.shell.completion"
  local complete = completion.build(
    { completion.choice, { "get", "put" } },
    completion.dir,
    { completion.file, many = true }
  )
  shell.setCompletionFunction("example.lua", complete)
  read(nil, nil, shell.complete, "example ")
  

See also

• cc.completion For more general helpers, suitable for use with _G.read.
• shell.setCompletionFunction

Changes

• New in version 1.85.0

file(shell, text)Source

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

Parameters

1. shell table The shell we're completing in.
2. text string Current text to complete.

Returns

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

dir(shell, text)Source

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

Parameters

1. shell table The shell we're completing in.
2. text string Current text to complete.

Returns

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

dirOrFile(shell, text, 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. text string Current text to complete.
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, text)Source

Complete the name of a program.

Parameters

1. shell table The shell we're completing in.
2. text string Current text to complete.

Returns

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

See also

• shell.completeProgram

programWithArgs(shell, text, previous, starting)Source

Complete arguments of a program.

Parameters

1. shell table The shell we're completing in.
2. text string Current text to complete.
3. previous { string... } The shell arguments before this one.
4. starting number Which argument index this program and args start at.

Returns

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

Changes

• New in version 1.97.0

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.