Others

Other types used to construct a completion spec, like Subcommand and Option, are subclasses of Suggestion and inherit its properties. Generators produce a list of Suggestion objects.

Types

TemplateStrings

Templates are generators prebuilt by Fig.

Declaration

type TemplateStrings = "filepaths" | "folders" | "history" | "help";

Discussion

Here are the three templates:

• filepaths: show folders and filepaths. Allow autoexecute on filepaths
• folders: show folders only. Allow autoexecute on folders
• history: show suggestions for all items in history matching this pattern
• help: show subcommands. Only includes the 'siblings' of the nearest 'parent' subcommand

Template

A template which is a single TemplateString or an array of TemplateStrings

Declaration

type Template =
  | ("filepaths" | "folders" | "history" | "help")
  | ("filepaths" | "folders" | "history" | "help")[];

Discussion

Templates are generators prebuilt by Fig. Here are the three templates:

• filepaths: show folders and filepaths. Allow autoexecute on filepaths
• folders: show folders only. Allow autoexecute on folders
• history: show suggestions for all items in history matching this pattern
• help: show subcommands. Only includes the 'siblings' of the nearest 'parent' subcommand

Example

cd uses the "folders" template ls used ["filepaths", "folders"]. Why both? Because if I ls a directory, we want to enable a user to autoexecute on this directory. If we just did "filepaths" they couldn't autoexecute.

SpecLocation

The SpecLocation object defines well... the location of the completion spec we want to load. Specs can be "global" (ie hosted by Fig's cloud) or "local" (ie stored on your local machine)

Declaration

type SpecLocation =
  | {
      type: "local";
      path?: string;
      name: string;
    }
  | {
      type: "global";
      name: string;
    };

Discussion

The SpecLocation Object

The SpecLocation object defines well... the location of the completion spec we want to load. Specs can be "global" (ie hosted by Fig's cloud) or "local" (ie stored on your local machine).

• Global SpecLocation: Load specs hosted in Fig's Cloud. Assume the current working directory is here: https://github.com/withfig/autocomplete/tree/master/src. Now set the value for the "name" prop to the relative location of your spec (without the .js file extension)

// e.g.
{ type: "global", name: "aws/s3" } // Loads up the aws s3 completion spec
{ type: "global", name: "python/http.server" } // Loads up the http.server completion spec

• Local SpecLocation: Load specs saved on your local system / machine. Assume the current working directory is the user's current working directory. The name prop should take the name of the spec (without the .js file extension) e.g. my_cli_tool The path prop should take an absolute path OR a relative path (relative to the user's current working directory). The path should be to the directory that contains the .fig folder. Fig will then assume your spec is located in .fig/autocomplete/build/

// e.g.
{ type: "global", path: "node_modules/cowsay", name: "cowsay_cli" }  // will look for `cwd/node_modules/cowsay/.fig/autocomplete/build/cowsay_cli.js`
{ type: "global", path: "~", name: "my_cli" }  // will look for `~/.fig/autocomplete/build/my_cli.js`

LoadSpec

Dynamically load up another completion spec at runtime.

See loadSpec property in Subcommand Object.

Declaration

type LoadSpec =
  | string
  | ((
      token: string,
      executeShellCommand: (commandToExecute: string) => Promise<string>
    ) => Promise<SpecLocation | SpecLocation[]>);

SuggestionType

The type of a suggestion object.

Declaration

type SuggestionType =
  | "folder"
  | "file"
  | "arg"
  | "subcommand"
  | "option"
  | "special"
  | "shortcut";

Discussion

The type determines:

• the default icon Fig uses (e.g. a file or folder searches for the system icon, a subcommand has a specific icon etc)
• whether we allow users to auto-execute a command

SingleOrArray

A single object of type T or an array of objects of type T.

Declaration

type SingleOrArray<T> = T | T[];

GetVersionCommand

An async function that returns the version of a given CLI tool.

Parameters

Return Value

The version of a CLI tool

Declaration

type GetVersionCommand = (
  executeShellCommand: (commandToExecute: string) => Promise<string>
) => Promise<string>;

Discussion

This is used in completion specs that want to version themselves the same way CLI tools are versioned. See fig.io/docs

Examples

• 1.0.22
• v26

ShellContext

Context about a current shell session.

Declaration

type ShellContext = {
  currentWorkingDirectory: string;
  currentProcess: string;
  sshPrefix: string;
};

Function

A function which can have a T argument and a R result.

Parameters

Return Value

Something of type R

Declaration

type Function<T = void, R = void> = (param?: T) => R;

Modify

A utility type to modify a property type

Declaration

type Modify<T, R> = Omit<T, keyof R> & R;

StringOrFunction

A string OR a function which can have a T argument and a R result.

Parameters

Return Value

Something of type R

Declaration

type StringOrFunction<T = void, R = void> = string | ((param?: T) => R);

Spec

A spec object

Parameters

Return Value

Something of type R

Declaration

type Spec = Subcommand | ((version?: string) => Subcommand);

ExecuteShellCommandFunction

An async function to execute a shell command

Parameters

Return Value

The output of the shell command as a string

Declaration

type ExecuteShellCommandFunction = (
  commandToExecute: string
) => Promise<string>;

Example

ExecuteShellCommandFunction("echo hello world") will return hello world