.

What is Clink?

Clink combines the native Windows shell cmd.exe with the powerful command line editing features of the GNU Readline library, which provides rich completion, history, and line-editing capabilities. Readline is best known for its use in the Unix shell Bash, the standard shell for Mac OS X and many Linux distributions.

.

Features

Here are some highlights of what Clink provides:

• The same line editing as Bash (from the GNU Readline library version 8.1).
• History persistence between sessions.
• Context sensitive completion;
  • Executables (and aliases).
  • Directory commands.
  • Environment variables.
• Context sensitive colored input text.
• Automatic suggestions from history and completions.
• New keyboard shortcuts;
  • Interactive completion list (Ctrl-Space).
  • Incremental history search (Ctrl-R and Ctrl-S).
  • Powerful completion (Tab).
  • Undo (Ctrl-Z).
  • Environment variable expansion (Ctrl-Alt-E).
  • Doskey alias expansion (Ctrl-Alt-F).
  • Scroll the screen buffer (Alt-Up, etc).
  • Shift-Arrow keys to select text, typing replaces selected text, etc.
  • (press Alt-H for many more...)
• Directory shortcuts;
  • Typing a directory name followed by a path separator is a shortcut for cd /d to that directory.
  • Typing .. or ... is a shortcut for cd .. or cd ..\.. (each additional . adds another \..).
  • Typing - or cd - changes to the previous current working directory.
• Scriptable autosuggest with Lua.
• Scriptable completion with Lua.
• Scriptable key bindings with Lua.
• Colored and scriptable prompt.
• Auto-answering of the "Terminate batch job?" prompt.

By default Clink binds Alt-H to display the current key bindings.

.

Usage

There are several ways to start Clink.

1. If you installed the auto-run, just start cmd.exe. Run clink autorun --help for more info.
2. To manually start, run the Clink shortcut from the Start menu (or the clink.bat located in the install directory).
3. To establish Clink to an existing cmd.exe process, use <install_dir>\clink inject.

Starting Clink injects it into a cmd.exe process, where it intercepts a handful of Windows API functions so that it can replace the prompt and input line editing with its own Readline-powered enhancements.

.

Getting Started

You can use Clink right away without configuring anything:

• Searchable command history will be saved between sessions.
• Tab and Ctrl-Space will do match completion two different ways.
• Press Alt-H to see a list of the current key bindings.
• Press Alt-Shift-/ followed by another key to see what command is bound to the key.

There are three main ways of customizing Clink to your preferences: the Readline init file (the .inputrc file), the Clink settings (the clink set command), and Lua scripts.

.

How Completion Works

Clink can offer possible completions for the word at the cursor, and can insert them for you. Clink can complete file names, directories, environment variables, and commands. It also allows you to provide custom completion generators using Lua scripts that execute inside Clink (see Extending Clink With Lua).

By default, pressing Tab performs completion the same way that bash does on Unix and Linux. When you press Tab, Clink finds matches for how to complete the word at the cursor. It automatically inserts the longest common prefix shared by the possible completions. If you press Tab again, it also lists the possible completions.

If you install Clink with "Use enhanced defaults" or if you set clink.default_bindings to use "windows" defaults, then pressing Tab cycles through the possible completions, replacing the word with the next possible completion each time.

Pressing Ctrl-Space shows an interactive list of possible completions. You can use the arrow keys to choose which completion to insert, and you can type to filter the list. Enter inserts the selected completion, or Space inserts the selected completion and makes sure a space follows it to allow typing a next argument.

The first word of each command line is the command or program to execute, or a file to open. By default, Clink provides completions for the first word based on all executable programs on the system PATH and the current directory, but not non-executable files. You can turn off executable completion by running clink set exec.enable false, or you can adjust its behavior by changing the various exec.* settings (see Clink Settings for more information about them).

See Completion Commands and Clink Commands for more available completion commands.

.

Common Configuration

The following sections describe some ways to begin customizing Clink to your taste.

.

Enhanced default settings

Clink can be installed with plain defaults, or it can be installed with enhanced default settings that enable more of Clink's enhancements by default.

If you install Clink with the setup program and "Use enhanced default settings" is checked, then the enhanced defaults are activated, and then in some places where this documentation refers to default settings the stated default may have been overridden.

If you install Clink from the .zip file then enhanced default settings are activated when the default_settings and default_inputrc files are present in the binaries directory or in the profile directory. The .zip file comes with the files, but their names have a _ prefix so that enhanced defaults won't automatically take effect. You can activate the enhanced default settings by renaming the files to remove the _ prefix.

Here are some of the enhanced defaults. Review the default_settings and default_inputrc files for the full list.

• Automatic suggestions are enabled.
• Many color settings have colorful defaults.
• Uses Windows key bindings by default.
• The command history's default limit is increased to 25,000 entries.
• Completion expands environment variables (the match.expand_envvars setting).
• If no completions are found with a prefix search, then a substring search is used (the match.substring setting).
• Ctrl-D does not exit CMD (the cmd.ctrld_exits setting).
• History saves and shows time stamps.

.

Create a .inputrc file

First you'll want to create a .inputrc file, and a good place is in your Windows user profile directory.

This file is used for some configuration, such as key bindings and colored completions.

Create the file by running this command at a CMD prompt:

notepad %userprofile%\.inputrc

You may want to copy/paste the following sample text into the file as a starting point, and then press Ctrl-S to save the file.

# Some common Readline config settings.

set colored-stats                 on   # Turn on completion colors.
set colored-completion-prefix     on   # Color the typed completion prefix.

# Some config settings that only work in Clink.

$if clink
set search-ignore-case            on   # Case insensitive history searches.
set completion-auto-query-items   on   # Prompt before showing completions if they'll exceed half the screen.
$endif

# Add your keybindings here...

See Init File for more information on Readline init files.

.

Bash vs Windows

The default Clink key bindings are the same as in the "bash" shell for Unix/Linux. That makes some keys like Ctrl-A, Ctrl-F, and Ctrl-M behave differently than you might be used to in CMD.

To instead use the familiar Windows default key bindings you can run clink set clink.default_bindings windows.

Or, if you use the setup program with "Use enhanced default settings" checked then "windows" key bindings are the default, and you can run clink set clink.default_bindings bash to use the bash default key bindings.

Clink comes with many default key bindings. Use Alt-H to see all of the active key bindings, or use Alt-Shift-? to check what is bound to a specific key. See Key Bindings to get started configuring your own key bindings.

Here are the differences between the Windows defaults and the bash defaults:

.

Auto-suggest

Clink can suggest commands as you type, based on command history and completions.

To turn on automatic suggestions, run clink set autosuggest.enable true. When the cursor is at the end of the input line, a suggestion may appear in a muted color. If the suggestion isn't what you want, just ignore it. Or accept the whole suggestion with the Right arrow or End key, accept the next word of the suggestion with Ctrl-Right, or accept the next full word of the suggestion up to a space with Shift-Right.

The autosuggest.strategy setting determines how a suggestion is chosen.

Or, if you use the setup program with "Use enhanced default settings" checked then automatic suggestions are enabled by default.

.

Colors

Clink has many configurable colors for match completions, input line coloring, popup lists, and more.

If you use the setup program with "Use enhanced default settings" checked then many of the color settings have more colorful default values.

.

For completion

When performing completion (e.g. Tab or Ctrl-Space) Clink can add color to the possible completions.

To turn on colored completions, put a line set colored-stats on in the .inputrc file (if you copy/pasted the sample text, it's already there).

See the Completion Colors section for how to configure the colors for match completions.

.

Other colors

Clink adds color to the input line by highlighting arguments, flags, doskey macros, and more. If you don't want input line colors, you can turn it off by running clink set clink.colorize_input false.

There are also colors for popup lists, and some other things.

To configure a color, run clink set colorname colorvalue.

Match completions make it easy to change Clink settings: type clink set color. and then use completion (e.g. Tab or Ctrl-Space) to see the available color settings, and to fill in a color value.

Here are some colors you may want to set up right away:

See the Clink Settings, Color Settings, and Coloring the Input Text sections for more information on Clink color settings.

.

Key Bindings

You can customize your key bindings (keyboard shortcuts) by assigning key bindings in the .inputrc file. See Customizing Key Bindings for more information.

Clink comes with many pre-configured key bindings that invoke named commands. Here are a few that you might find especially handy:

For a full list of commands available for key bindings, see Bindable Commands.

.

Mouse Input

Clink can optionally respond to mouse input, instead of letting the terminal respond to mouse input (e.g. to select text on the screen). When mouse input is enabled in Clink, you can click in the input line or in popup lists, and the mouse wheel scrolls popup lists.

Use clink set terminal.mouse_input mode with one of the following modes to control whether Clink responds to mouse input:

Use clink set terminal.mouse_modifier modifiers or set CLINK_MOUSE_MODIFIER=modifiers to control which modifier keys must be held for Clink to respond to mouse input.

These select which modifier keys (Alt, Ctrl, Shift) must be held in order for Clink to respond to mouse input when mouse input is enabled by the terminal.mouse_input setting. modifiers is a text string that can list one or more modifier keys: "alt", "ctrl", and "shift". For example, setting it to "alt shift" causes Clink to only respond to mouse input when both Alt and Shift are held (and not Ctrl). If the %CLINK_MOUSE_MODIFIER% environment variable is set then its value supersedes the terminal.mouse_modifier setting. In Windows Terminal many modifier keys do special things with mouse clicks, so the modifier key combination that interferes least with built in Windows Terminal behaviors is Ctrl-Alt.

When mouse input is enabled in Clink, then mouse input works a little differently:

• You can bypass Clink mouse input and use the normal terminal mouse input by holding a different combination of modifier keys than listed in terminal.mouse_modifier or %CLINK_MOUSE_MODIFIER%.
• Windows Terminal treats Shift-RightClick specially and turns off line ending detection when copying the selected text to the clipboard. Hold Ctrl or Alt when right clicking to do the normal copy with line ending detection.
• In ConEmu, the mouse wheel always scrolls the terminal; Clink cannot use it to scroll popup lists.
• In the default Conhost terminal when Quick Edit mode is turned off then Clink will also respond to mouse input when no modifier keys are held.

.

Startup Cmd Script

When Clink is injected, it looks for a clink_start.cmd script in the binaries directory and profile directory. Clink automatically runs the script(s), if present, when the first CMD prompt is shown after Clink is injected. You can set the clink.autostart setting to run a different command, or set it to "nul" to run no command at all.

.

Custom Prompt

If you want a customizable prompt with a bunch of styles and an easy-to-use configuration wizard, check out clink-flex-prompt. Also, if you've been disappointed by git making the prompt slow in other shells, try this prompt -- it makes the prompt appear instantly by running git commands in the background and refreshing the prompt once the background commands complete.

Other popular configurable prompts are oh-my-posh and starship.

See Customizing the Prompt for information on how to use Lua to customize the prompt.

.

Upgrading from Clink v0.4.9

The new Clink tries to be as backward compatible with Clink v0.4.9 as possible. However, in some cases upgrading may require a little bit of configuration work.

• Some key binding sequences have changed; see Customizing Key Bindings for more information.
• Match coloring works differently now and can do much more; see Completion Colors for more information.
• Old settings and history migrate automatically if you use the same profile directory when upgrading. If you use a different profile directory, then you can still migrate the old settings and history by copying certain files. See below for details.
• Script compatibility should be very good, but some scripts may still encounter problems. If you do encounter a compatibility problem you can look for an updated version of the script, update the script yourself, or visit the clink repo and open an issue describing details about the compatibility problem.
• Some match generator scripts might need adjustments to become fully compatible with the autosuggest.enable setting.
• Some settings have changed slightly, and there are many new settings. See Configuring Clink for more information.

.

Migrating between different profile directories

All versions of Clink use the same default profile directory location. If you haven't overridden the profile directory, then your settings and history will automatically migrate when upgrading to newer versions of Clink.

If you choose to use a different profile directory, then you can still make migration happen by copying certain files:

1. When using Clink v0.4.9 you can use clink set to find the settings file path.
2. When using newer versions of Clink you can use clink info to find the profile directory.
3. Copy the settings and .history files from the old directory into the new directory.
4. If you already have a clink_settings or clink_history file in your new profile directory, then you'll need to rename them in order for migration to happen (e.g. add .txt to the names).
5. Close the Clink session(s) and open new ones.

.

Configuring Clink

Clink has two configuration systems, which is a result of using the Readline library to provide command history and key bindings.

The following sections describe how to configure Clink itself. To learn about the Readline configuration and key bindings, instead see Configuring Readline.

.

Clink Settings

The easiest way to configure Clink is to use the clink set command. This can list, query, and set Clink's settings. Run clink set --help from a Clink-installed cmd.exe process to learn more both about how to use it and to get descriptions for Clink's various options.

The following table describes the available Clink settings:

* Some settings have alternative default values when Clink is installed with "Use enhanced default settings" checked in the setup program. This enables more of Clink's enhancements by default.

Compatibility Notes:

• The esc_clears_line setting has been replaced by a clink-reset-line command that is by default bound to the Escape key. See Customizing Key Bindings for more information.
• The match_colour setting has been removed, and Clink now supports Readline's completion coloring. See Completion Colors for more information.

.

Color Settings

.

Friendly Color Names

The Clink color settings are the ones whose names begin with color.. Color settings use the following syntax:

[attributes] [foreground_color] [on [background_color]]

Optional attributes (can be abbreviated to 3 letters):

• bold or nobold adds or removes boldface (usually represented by forcing the color to use high intensity if it doesn't already).
• underline or nounderline adds or removes an underline.

Optional colors for foreground_color and background_color (can be abbreviated to 3 letters):

• default or normal uses the default color as defined by the current color theme in the console window.
• black, red, green, yellow, blue, cyan, magenta, white are the basic colors names.
• bright can be combined with any of the other color names to make them bright (high intensity).

Examples (specific results may depend on the console host program):

• bri yel for bright yellow foreground on default background color.
• bold for bright default foreground on default background color.
• underline bright black on white for dark gray (bright black) foreground on light gray (white) background.
• default on blue for default foreground color on blue background.

.

Alternative SGR Syntax

It's also possible to set any ANSI SGR escape code using sgr SGR_parameters (for example sgr 7 is the code for reverse video, which swaps the foreground and background colors).

Be careful, since some escape code sequences might behave strangely.

.

File Locations

Settings and history are persisted to disk from session to session. By default Clink uses the current user's non-roaming application data directory. This user directory is usually found in one of the following locations;

• Windows XP: c:\Documents and Settings\<username>\Local Settings\Application Data\clink
• Windows Vista onwards: c:\Users\<username>\AppData\Local\clink

All of the above locations can be overridden using the --profile path command line option which is specified when injecting Clink into cmd.exe using clink inject. Or with the %CLINK_PROFILE% environment variable if it is already present when Clink is injected (this envvar takes precedence over any other mechanism of specifying a profile directory, if more than one was used).

You can use clink info to find the directories and configuration files for the current Clink session.

Notes:

• Clink performs tilde expansion on the %CLINK_PROFILE% environment variable value. If the path begins with ~\ then it is replaced with the current user's home directory (%HOMEDRIVE%%HOMEPATH% or %USERPROFILE%).
• The --profile flag has a quirk for backward compatibility with older versions of Clink: ~\ in --profile is expanded to %LOCALAPPDATA% instead.

.

Overriding the profile directory when installed for Autorun

If you've installed Clink using the setup program with the "Autorun when cmd.exe starts" box checked, then the profile directory has been explicitly set to %LOCALAPPDATA%\clink. That will take precedence over any other stored configuration.

You can override it via set CLINK_PROFILE=path after starting cmd.exe.

Or you can use clink autorun install -- --profile path to change which profile directory is specified (see clink autorun --help and clink autorun show).

Or if you want to use Autorun but also override the profile directory any of the usual ways, then run clink autorun uninstall and then clink autorun install. That will remove the explicit profile directory specification that was applied by the setup program.

.

Files

.

Command Line Options

Note: If the --profile path begins with ~\ then it is replaced with the current user's home directory (%HOMEDRIVE%%HOMEPATH% or %USERPROFILE%).

.

Automatic Updates

By default, Clink periodically and automatically checks for new versions. When an update is available, Clink prints a message on startup. To apply an update, run clink update when convenient to do so.

You can control the frequency of update checks with clink set clink.update_interval days, where days is the minimum number of days between checking for updates.

You can turn update checks off with clink set clink.autoupdate false, or turn them on with clink set clink.autoupdate true.

Notes:

• The auto-updater settings are stored in the profile, so different profiles can be configured differently for automatic updates.
• The updater does nothing if the Clink program files are readonly.
• The updater requires PowerShell, which is present by default in Windows 7 and higher.

.

Portable Configuration

Sometimes it's useful to run Clink from a flash drive or from a network share, especially if you want to use Clink on someone else's computer.

Here's how you can set up a portable configuration for Clink:

1. Put your Lua scripts and other tools in the same directory as the Clink executable files. For example fzf.exe, z.cmd, oh-my-posh.exe, starship.exe etc can all go in the same directory on a flash drive or network share.
2. Make a batch file such as portable.bat that injects Clink using a specific profile directory.
   • On a flash drive, you can have a portable profile in a subdirectory under the Clink directory.
   • On a network share, you'll want to copy some initial settings into a local profile directory (a profile directory on a network share will be slow).
3. In any cmd.exe window on any computer, you can then run the portable.bat script to inject Clink and have all your favorite settings and key bindings work.

Here are some sample scripts:

.

portable.bat (on a flash drive)

This sample script assumes the portable.bat script is in the Clink directory, and it uses a clink_portable profile directory under the Clink directory.

@echo off
rem -- Do any other desired configuration here, such as loading a doskey macro file.
call "%~dp0clink.bat" inject --profile "%~dp0clink_portable" %1 %2 %3 %4 %5 %6 %7 %8 %9

.

portable.bat (on a network share)

This sample script assumes the portable.bat script is in the Clink directory, and that there is a file portable_clink_settings with the settings you want to copy to the local profile directory.

@echo off
if not exist "%TEMP%\clink_portable" md "%TEMP%\clink_portable" >nul
if not exist "%TEMP%\clink_portable\clink_settings" copy "%~dp0portable_clink_settings" "%TEMP%\clink_portable\clink_settings" >nul
rem -- Do any other desired configuration here, such as loading a doskey macro file.
call "%~dp0clink.bat" inject --profile "%TEMP%\clink_portable" %1 %2 %3 %4 %5 %6 %7 %8 %9

.

Configuring Readline

Clink uses the GNU Readline library to provide line editing functionality, which can be configured to add custom keybindings and macros by creating a Readline init file. The Clink documentation includes an updated and tailored copy of the Readline documentation, below.

.

The Basics

.

Bare Essentials

To enter characters into the line, simply type them. The typed character appears where the cursor was, and then the cursor moves one space to the right. If you mistype a character, you can use Backspace to back up and delete the mistyped character.

Sometimes you may mistype a character, and not notice the error until you have typed several other characters. In that case, you can type Left (the left arrow key) to move the cursor to the left, and then correct your mistake. Afterwards, you can move the cursor to the right with Right (the right arrow key).

When you add text in the middle of a line, you will notice that characters to the right of the cursor are "pushed over" to make room for the text that you have inserted. Likewise, when you delete text behind the cursor, characters to the right of the cursor are "pulled back" to fill in the blank space created by the removal of the text. A list of the bare essentials for editing the text of an input line follows.

.

Killing and Yanking

Killing text means to delete the text from the line, but to save it away for later use, usually by yanking (re-inserting) it back into the line. ("Cut" and "paste" are more recent jargon for "kill" and "yank", but killing and yanking do not affect the system's clipboard.)

If the description for a command says that it "kills" text, then you can be sure that you can get the text back in a different (or the same) place later.

When you use a kill command, the text is saved in a kill-ring. Any number of consecutive kills save all of the killed text together, so that when you yank it back, you get it all. The kill ring is not line specific; the text that you killed on a previously typed line is available to be yanked back later, when you are typing another line.

Here are some basic commands for killing text.

Here is how to yank the text back into the line. Yanking means to copy the most-recently-killed text from the kill buffer.

.

Readline Arguments

You can pass numeric arguments to Readline commands. Sometimes the argument acts as a repeat count, other times it is the sign of the argument that is significant. If you pass a negative argument to a command which normally acts in a forward direction, that command will act in a backward direction. For example, to kill text back to the start of the line, you might type Alt-- Ctrl-k.

The general way to pass numeric arguments to a command is to type meta digits before the command. If the first "digit" typed is a minus sign (-), then the sign of the argument will be negative. Once you have typed one meta digit to get the argument started, you can type the remainder of the digits, and then the command. For example, to give the Del command an argument of 10, you could type Alt-1 0 Del, which will delete the next ten characters on the input line.

.

Searching for Commands in the History

Readline provides commands for searching through the command history for lines containing a specified string. There are two search modes: incremental and non-incremental.

Incremental searches begin before the user has finished typing the search string. As each character of the search string is typed, Readline displays the next entry from the history matching the string typed so far. An incremental search requires only as many characters as needed to find the desired history entry. To search backward in the history for a particular string, type Ctrl-r. Typing Ctrl-s searches forward through the history. The characters present in the value of the isearch-terminators variable are used to terminate an incremental search. If that variable has not been assigned a value, then Esc or Ctrl-j will terminate an incremental search. Ctrl-g will abort an incremental search and restore the original line. When the search is terminated, the history entry containing the search string becomes the current line.

To find other matching entries in the history list, type Ctrl-r or Ctrl-s as appropriate. This will search backward or forward in the history for the next entry matching the search string typed so far. Any other key sequence bound to a Readline command will terminate the search and execute that command. For instance, Enter will terminate the search and accept the line, thereby executing the command from the history list. A movement command will terminate the search, make the last line found the current line, and begin editing.

Readline remembers the last incremental search string. If two Ctrl-r's are typed without any intervening characters defining a new search string, any remembered search string is used.

Non-incremental searches read the entire search string before starting to search for matching history lines. The search string may be typed by the user or be part of the contents of the current line. Type Alt-p or Alt-n to start a non-incremental search backwards or forwards.

To search backward in the history for a line starting with the text before the cursor, type PgUp. Or search forward by typing PgDn.

See Saved Command History for more information on how history works.

.

Init File

You can customize key bindings and configuration variables by using an init file.

"Configuration variables" are customized in the init file, but "Clink settings" are customized with the clink set command.

.

Init File Location

The Readline init file is named .inputrc or _inputrc. Clink searches the directories referenced by the following environment variables in the order listed here, and loads the first .inputrc or _inputrc file it finds:

• %CLINK_INPUTRC%
• The Clink profile directory (see the "state" line from clink info; by default this is the same as %USERPROFILE% but it can be overridden by the clink inject command).
• %USERPROFILE%
• %LOCALAPPDATA%
• %APPDATA%
• %HOME%

Other software that also uses the Readline library will also look for the .inputrc file (and possibly the _inputrc file too). To set macros and keybindings intended only for Clink, one can use the Readline init file conditional construct like this; $if clink [...] $endif.

You can use clink info to find the directories and configuration file for the current Clink session.

Compatibility Notes:

• The clink_inputrc_base file from v0.4.8 is no longer used.
• For backward compatibility, clink_inputrc is also loaded from the above locations, but it has been deprecated and may be removed in the future.
• Clink v1.0.0a0 through Clink v1.2.27 accidentally loaded up to one Readline init file from each of the searched directories. That was incorrect behavior for loading Readline init files and has been fixed. If similar behavior is still desired, consider using the $include directive in the Readline init file, to load additional files.

.

Init File Syntax

There are only a few basic constructs allowed in the Readline init file:

• Blank lines are ignored.
• Lines beginning with a # are comments.
• Lines beginning with a $ indicate conditional init constructs.
• Other lines denote Readline configuration variables and Readline key bindings.

.

Readline configuration variables

You can modify the behavior of Readline by altering the values of configuration variables in Readline using the set command within the init file. The syntax is simple:

set variable value

Here, for example, is how to change from the default Emacs-like key binding to use vi line editing commands:

set editing-mode vi

Variable names and values, where appropriate, are recognized without regard to case. Unrecognized variable names are ignored.

Boolean variables (those that can be set to on or off) are set to on if the value is null or empty, on (case-insensitive), or 1. Any other value results in the variable being set to off.

Clink adds some new configuration variables for Readline:

Some configuration variables are deprecated in Clink:

.

Readline key bindings

The syntax for controlling key bindings in the init file is simple. First you need to find the name of the command that you want to change. The following sections contain tables of the command name, the default keybinding, if any, and a short description of what the command does (see Bindable Commands).

Once you know the name of the command, simply place on a line in the init file the name of the key you wish to bind the command to, a colon, and then the name of the command. There can be no space between the key name and the colon (any space will be interpreted as part of the key name). The name of the key can be expressed in different ways, depending on what you find most comfortable.

In addition to command names, Readline allows keys to be bound to a string that is inserted when the key is pressed (a macro).

Names can be used to refer to simple keys like Space, Return, Tab, letters and digits (A, b, 1, ...), and most punctuation (!, @, ., _, ...). Names can also include modifier prefixes C- or Control- for the Ctrl key, or M- or Meta- for the Meta or Alt key. However, modifier prefixes don't work with simple key names; you can't use C-Space, instead a sequence is needed for special keys like that.

Sequences are surrounded by double quotes, and specify an entire sequence of input characters. Some special escape codes can be used:

Here are some examples to illustrate the differences between names and sequences:

Special keys like Up are represented by VT220 escape codes such as"\e[A". See Discovering Clink key sequences and Binding special keys for how to find the keyname for the key you want to bind.

• blah-blah binds to a function named "blah-blah".
• "blah-blah" is a macro that inserts the literal text "blah-blah" into the line.

When entering the text of a macro, single or double quotes must be used to indicate a macro definition. Unquoted text is assumed to be a function name. In the macro body, the backslash escapes described above are expanded. Backslash will quote any other character in the macro text, including " and '. For example, the following binding will make pressing Ctrl-x \ insert a single \ into the line:

"\C-x\\": "\\"

# Using key names.
C-u: universal-argument         # Bind Ctrl-u to invoke the universal-argument command.
C-o: "> output"                 # Bind Ctrl-o to insert the text "> output" into the line.

# Using key sequences.
"\C-u": universal-argument      # Bind Ctrl-u to invoke the universal-argument command.
"\C-x\C-r": clink-reload        # Bind Ctrl-x,Ctrl-r to reload the configuration and Lua scripts for Clink.
"\eOP": clink-popup-show-help   # Bind F1 to invoke the clink-popup-show-help command.

See Customizing Key Bindings for more information about binding keys in Clink.

.

Conditional init constructs

Readline implements a facility similar in spirit to the conditional compilation features of the C preprocessor which allows key bindings and variable settings to be performed as the result of tests. There are four parser directives used.

$if mode == emacs
set show-mode-in-prompt on
$endif

$if version >= 7.0
set show-mode-in-prompt on
$endif

$if clink
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif

$if editing-mode == emacs
set show-mode-in-prompt on
$endif

$include c:\dir\inputrc

.

Sample .inputrc file

Here is a sample .inputrc file with some of the variables and key bindings that I use:

$if clink           # begin clink-only section

set colored-completion-prefix                       on
set colored-stats                                   on
set mark-symlinked-directories                      on
set visible-stats                                   off
set completion-auto-query-items                     on
set history-point-at-end-of-anchored-search         on
set menu-complete-wraparound                        off
set search-ignore-case                              on

# The following key bindings are for emacs mode.
set keymap emacs

"\e[27;8;72~":      clink-popup-show-help           # Alt-Ctrl-Shift-H

# Completion key bindings.
"\t":               old-menu-complete               # Tab
"\e[Z":             old-menu-complete-backward      # Shift-Tab
"\e[27;5;32~":      clink-select-complete           # Ctrl-Space

# Some key bindings I got used to from 4Dos/4NT/Take Command.
C-b:                                                # Ctrl-B (cleared because I redefined Ctrl-F)
C-d:                remove-history                  # Ctrl-D (replaces `delete-char`)
C-f:                clink-expand-doskey-alias       # Ctrl-F (replaces `forward-char`)
C-k:                add-history                     # Ctrl-K (replaces `kill-line`)
"\e[A":             history-search-backward         # Up (replaces `previous-history`)
"\e[B":             history-search-forward          # Down (replaces `next-history`)
"\e[5~":            clink-popup-history             # PgUp (replaces `history-search-backward`)
"\e[6~":                                            # PgDn (cleared because I redefined PgUp)
"\e[1;5F":          end-of-line                     # Ctrl-End (replaces `kill-line`)
"\e[1;5H":          beginning-of-line               # Ctrl-Home (replaces `backward-kill-line`)

# Some key bindings handy in default (conhost) console windows.
M-b:                                                # Alt-B (cleared because I redefined Alt-F)
M-f:                clink-find-conhost              # Alt-F for "Find..." from the console's system menu
M-m:                clink-mark-conhost              # Alt-M for "Mark" from the console's system menu

# Some key bindings for interrogating the Readline configuration.
"\C-x\C-f":         dump-functions                  # Ctrl-X, Ctrl-F
"\C-x\C-m":         dump-macros                     # Ctrl-X, Ctrl-M
"\C-x\C-v":         dump-variables                  # Ctrl-X, Ctrl-V

# Misc other key bindings.
"\e[27;2;32~":      clink-magic-suggest-space       # Shift-Space
"\e[5;6~":          clink-popup-directories         # Ctrl-Shift-PgUp
C-_:                kill-line                       # Ctrl-- (replaces `undo`)

$endif              # end clink-only section

.

Bindable Commands

.

Commands For Moving

.

Commands For Manipulating The History

.

Commands For Changing Text

.

Killing And Yanking

.

Specifying Numeric Arguments

.

Completion Commands

.

Keyboard Macros

.

Some Miscellaneous Commands

.

Readline vi Mode

While the Readline library does not have a full set of vi editing functions, it does contain enough to allow simple editing of the line. The Readline vi mode behaves as specified in the POSIX standard.

In order to switch interactively between emacs and vi editing modes, use the command Alt-Ctrl-j (bound to emacs-editing-mode when in vi mode and to vi-editing-mode in emacs mode). The Readline default is emacs mode.

When you enter a line in vi mode, you are already placed in "insertion" mode, as if you had typed an "i". Pressing Esc switches you into "command" mode, where you can edit the text of the line with the standard vi movement keys, move to previous history lines with "k" and subsequent lines with "j", and so forth.

.

Other Readline Commands

These other commands are not very useful in Clink, but exist nevertheless.

.

Clink Commands

Clink also adds some new commands, beyond what's normally provided by Readline.

.

Completion Colors

The %LS_COLORS% environment variable provides color definitions as a series of color definitions separated by colons (:). Each definition is a either a two character type id or a file extension, followed by an equals sign and then the SGR parameters for an ANSI escape code. The two character type ids are listed below.

When the colored-completion-prefix Readline setting is configured to on, then the "so" color from %LS_COLORS% is used to color the common prefix when displaying possible completions. The default for "so" is magenta, but for example set LS_COLORS=so=90 sets the color to bright black (which shows up as a dark gray).

When colored-stats is configured to on, then the color definitions from %LS_COLORS% are used to color file completions according to their file type or extension. Multiple definitions are separated by colons. Also, since %LS_COLORS% doesn't cover readonly files, hidden files, doskey aliases, or shell commands the color.readonly, color.hidden, color.doskey, and color.cmd Clink settings exist to cover those.

Here is an example where %LS_COLORS% defines colors for various types.

set LS_COLORS=so=90:fi=97:di=93:ex=92:*.pdf=30;105:*.md=4

• so=90 uses bright black (dark gray) for the common prefix for possible completions.
• fi=97 uses bright white for files.
• di=93 uses bright yellow for directories.
• ex=92 uses bright green for executable files.
• *.pdf=30;105 uses black on bright magenta for .pdf files.
• *.md=4 uses underline for .md files.

.

Popup Windows

Some commands show a searchable popup window that lists the available completions, directory history, or command history.

For example, win-history-list (F7) and clink-popup-directories (Ctrl-Alt-PgUp) show popup windows.

Here's how the popup windows work:

Most of the popup windows also have incremental search:

The win-history-list command has a different search feature. Typing digits 0-9 jumps to the numbered history entry, or typing a letter jumps to the preceding history entry that begins with the typed letter. This is for compatibility with the F7 behavior built into Windows console prompts. Use the clink-popup-history command instead if you prefer for typing to do an incremental search.

.

Extending Clink With Lua

Clink can be extended with Lua scripts to customize startup actions, create completion matches, customize the prompt, and more. The following sections describe these in more detail and show some examples.

.

Location of Lua Scripts

Clink loads all Lua scripts it finds in these directories:

1. All directories listed in the clink.path setting, separated by semicolons.
2. If clink.path is not set, then the DLL directory and the profile directory are used (see File Locations for info about the profile directory).
3. All directories listed in the %CLINK_PATH% environment variable, separated by semicolons.
4. All directories registered by the clink installscripts command.

Lua scripts are loaded once and are only reloaded if forced because the scripts locations change, the clink-reload command is invoked (Ctrl-X,Ctrl-R), or the lua.reload_scripts setting changes (or is True).

Run clink info to see the script paths for the current session.

Notes:

• "completions" is a special reserved directory name: a "completions" directory under any of the Lua script directories listed in clink info has special meaning, and should not contain scripts unless they are specially written to be put in a "completions" directory. See Completion directories for more information.
• Clink performs tilde expansion on the Lua script directory names. If the path begins with ~\ then it is replaced with the current user's home directory (%HOMEDRIVE%%HOMEPATH% or %USERPROFILE%).

.

Completion directories

You may optionally put Lua completion scripts in a completions directory. That prevents them from being loaded when Clink starts, and instead they are only loaded when needed. That can make Clink load faster if you have a large quantity of Lua scripts that define argmatchers.

When a command name is typed, if a corresponding argmatcher is not already loaded then the completions directories are searched for a Lua script by the same name. If found, then the Lua script is loaded. This is similar to how completion scripts work in shells like bash, zsh, and fish.

For example, if you type xyz and an argmatcher for xyz is not yet loaded, then if xyz.lua exists in one of the completions directories it will be loaded.

Clink looks for completion scripts in these directories:

1. Any directories listed in the %CLINK_COMPLETIONS_DIR% environment variable (multiple directories may be separated by semicolons).
2. A completions subdirectory under each scripts directory listed by clink info (see Location of Lua Scripts).

Note: If you download scripts, then don't put them in a "completions" directory unless they specifically say they can be put there.

If a script defines more than an argmatcher, then putting it in a completions directory may cause its other functionality to not work until a command is typed with the same name as the script. For example, if a script in a completions directory defines an argmatcher and also a prompt filter, the prompt filter won't be loaded until the corresponding command name is typed. Whether that is desirable depends on the script and on your preference.

For example, the scripts from the clink-completions project belong in a normal script directory, because they have other functionality besides just completions, and they won't work correctly in a "completions" directory.

.

Tips for starting to write Lua scripts

• Loading a Lua script executes it; so when Clink loads Lua scripts from the locations above, it executes the scripts.
• Code not inside a function is executed immediately when the script is loaded.
• Usually scripts will register functions to customize various behaviors:
  • Generate completion matches.
  • Apply color to input text.
  • Customize the prompt.
  • Perform actions before or after the user gets to edit each input line.
  • Provide new custom commands that can be bound to keys via the luafunc: key macro syntax.
• Often scripts will also define some functions and variables for use by itself and/or other scripts.

The following sections describe these in more detail and show some examples.

.

Match Generators

These are Lua functions that are called as part of Readline's completion process (for example when pressing Tab).

.

The Basics

First create a match generator object:

local my_generator = clink.generator(priority)

The priority argument is a number that influences when the generator gets called, with lower numbers going before higher numbers.

.

The :generate() Function

Next define a match generator function on the object, taking the following form:

function my_generator:generate(line_state, match_builder)
    -- Use the line_state object to examine the current line and create matches.
    -- Submit matches to Clink using the match_builder object.
    -- Return true or false.
end

line_state is a line_state object that has information about the current line.

match_builder is a builder object to which matches can be added.

If no further match generators need to be called then the function should return true. Returning false or nil continues letting other match generators get called.

Here is an example script that supplies git branch names as matches for git checkout. This example doesn't handle git aliases, but that could be added with additional script code.

local git_branch_autocomplete = clink.generator(1)

local function starts_with(str, start)
    return string.sub(str, 1, string.len(start)) == start
end

local function is_checkout_ac(text)
    if starts_with(text, "git checkout") then
        return true
    end
    return false
end

local function get_branches()
    -- Run git command to get branches.
    local handle = io.popen("git branch -a 2>&1")
    local result = handle:read("*a")
    handle:close()
    -- Parse the branches from the output.
    local branches = {}
    if starts_with(result, "fatal") == false then
        for branch in string.gmatch(result, "  %S+") do
            branch = string.gsub(branch, "  ", "")
            if branch ~= "HEAD" then
                table.insert(branches, branch)
            end
        end
    end
    return branches
end

function git_branch_autocomplete:generate(line_state, match_builder)
    -- Check if it's a checkout command.
    if not is_checkout_ac(line_state:getline()) then
        return false
    end
    -- Get branches and add them (does nothing if not in a git repo).
    local matchCount = 0
    for _, branch in ipairs(get_branches()) do
        match_builder:addmatch(branch)
        matchCount = matchCount + 1
    end
    -- If we found branches, then stop other match generators.
    return matchCount > 0
end

.

The :getwordbreakinfo() Function

If needed, a generator can optionally influence word breaking for the end word by defining a :getwordbreakinfo() function.

The function takes a line_state line_state object that has information about the current line. If it returns nil or 0, the end word is truncated to 0 length. This is the normal behavior, which allows Clink to collect and cache all matches and then filter them based on typing. Or it can return two numbers: word break length and an optional end word length. The end word is split at the word break length: one word contains the first word break length characters from the end word (if 0 length then it's discarded), and the next word contains the rest of the end word truncated to the optional word length (0 if omitted).

A good example to look at is Clink's own built-in environment variable match generator. It has a :getwordbreakinfo() function that understands the % syntax of environment variables and produces word break info accordingly.

When the environment variable match generator's :getwordbreakinfo() function sees the end word is abc%USER it returns 3,1 so that the last two words become "abc" and "%" so that its generator knows it can do environment variable matching. But when it sees abc%FOO%def it returns 8,0 so that the last two words become "abc%FOO%" and "" so that its generator won't do environment variable matching, and also so other generators can produce matches for what follows, since "%FOO%" is an already-completed environment variable and therefore should behave like a word break. In other words, it breaks the end word differently depending on whether the number of percent signs is odd or even, to account for environent variable syntax rules.

And when an argmatcher sees the end word begins with a flag character it returns 0,1 so the end word contains only the flag character in order to switch from argument matching to flag matching.

Note: The :getwordbreakinfo() function is called very often, so it needs to be very fast or it can cause responsiveness problems while typing.

local envvar_generator = clink.generator(10)

function envvar_generator:generate(line_state, match_builder)
    -- Does the word end with a percent sign?
    local word = line_state:getendword()
    if word:sub(-1) ~= "%" then
        return false
    end

    -- Add env vars as matches.
    for _, i in ipairs(os.getenvnames()) do
        match_builder:addmatch("%"..i.."%", "word")
    end

    match_builder:setsuppressappend()   -- Don't append a space character.
    match_builder:setsuppressquoting()  -- Don't quote envvars.
    return true
end

function envvar_generator:getwordbreakinfo(line_state)
    local word = line_state:getendword()
    local in_out = false
    local index = nil

    -- Paired percent signs denote already-completed environment variables.
    -- So use envvar completion for abc%foo%def%USER but not for abc%foo%USER.
    for i = 1, #word do
        if word:sub(i, i) == "%" then
            in_out = not in_out
            if in_out then
                index = i - 1
            else
                index = i
            end
        end
    end

    -- If there were any percent signs, return word break info to influence the
    -- match generators.
    if index then
        return index, (in_out and 1) or 0
    end
end

.

More Advanced Stuff

.

Filtering Match Completions

A match generator or luafunc: key binding can use clink.onfiltermatches() to register a function that will be called after matches are generated but before they are displayed or inserted.

The function receives a table argument containing the matches to be displayed, a string argument indicating the completion type, and a boolean argument indicating whether filename completion is desired. The table argument has a match string field and a type string field; these are the same as in builder:addmatch().

The possible completion types are:

The return value is a table with the input matches filtered as desired. The match filter function can remove matches, but cannot add matches (use a match generator instead). If only one match remains after filtering, then many commands will insert the match without displaying it. This makes it possible to spawn a process (such as fzf) to perform enhanced completion by interactively filtering the matches and keeping only one selected match.

settings.add("fzf.height", "40%", "Height to use for the --height flag")
settings.add("fzf.exe_location", "", "Location of fzf.exe if not on the PATH")

-- Build a command line to launch fzf.
local function get_fzf()
    local height = settings.get("fzf.height")
    local command = settings.get("fzf.exe_location")
    if not command or command == "" then
        command = "fzf.exe"
    else
        command = os.getshortname(command)
    end
    if height and height ~= "" then
        command = command..' --height '..height
    end
    return command
end

local fzf_complete_intercept = false

-- Sample key binding in .inputrc:
--      M-C-x: "luafunc:fzf_complete"
function fzf_complete(rl_buffer)
    fzf_complete_intercept = true
    rl.invokecommand("complete")
    if fzf_complete_intercept then
        rl_buffer:ding()
    end
    fzf_complete_intercept = false
    rl_buffer:refreshline()
end

local function filter_matches(matches, completion_type, filename_completion_desired)
    if not fzf_complete_intercept then
        return
    end
    -- Start fzf.
    local r,w = io.popenrw(get_fzf()..' --layout=reverse-list')
    if not r or not w then
        return
    end
    -- Write matches to the write pipe.
    for _,m in ipairs(matches) do
        w:write(m.match.."\n")
    end
    w:close()
    -- Read filtered matches.
    local ret = {}
    while (true) do
        local line = r:read('*line')
        if not line then
            break
        end
        for _,m in ipairs(matches) do
            if m.match == line then
                table.insert(ret, m)
            end
        end
    end
    r:close()
    -- Yay, successful; clear it to not ding.
    fzf_complete_intercept = false
    return ret
end

local interceptor = clink.generator(0)
function interceptor:generate(line_state, match_builder)
    -- Only intercept when the specific command was used.
    if fzf_complete_intercept then
        clink.onfiltermatches(filter_matches)
    end
    return false
end

.

Filtering the Match Display

In some instances it may be preferable to display different text when listing potential matches versus when inserting a match in the input line, or to display a description next to a match. For example, it might be desirable to display a * next to some matches, or to show additional information about some matches.

The simplest way to do that is just include the display and/or description fields when using builder:addmatch(). Refer to that function's documentation for usage details.

However, older versions of Clink don't support those fields. And in some cases it may be desirable to display a list of possible completions that includes extra matches, or omits some matches (but that's discouraged because it can be confusing to users).

A match generator can alternatively use clink.ondisplaymatches() to register a function that will be called before matches are displayed (this is reset every time match generation is invoked).

The function receives a table argument containing the matches to be displayed, and a boolean argument indicating whether they'll be displayed in a popup window. The table argument has a match string field and a type string field; these are the same as in builder:addmatch(). The return value is a table with the input matches filtered as required by the match generator.

The returned table can also optionally include a display string field and a description string field. When present, display will be displayed instead of the match field, and description will be displayed next to the match. Putting the description in a separate field enables Clink to align the descriptions in a column.

Filtering the match display can affect completing matches: the match field is what gets inserted. It can also affect displaying matches: the display field is displayed if present, otherwise the match field is displayed.

If a match's type is "none" or its match field is different from its display field then the match is displayed using the color specified by the color.filtered Clink setting, otherwise normal completion coloring is applied. The display and description fields can include ANSI escape codes to apply other colors if desired.

local function my_filter(matches, popup)
    local new_matches = {}
    local magenta = "\x1b[35m"
    local filtered = settings.get("color.filtered")
    for _,m in ipairs(matches) do
        if m.match:find("[0-9]") then
            -- Ignore matches with one or more digits.
        else
            -- Keep the match, and also add a magenta * prefix to directory matches.
            if m.type:find("^dir") then
                m.display = magenta.."*"..filtered..m.match
            end
            table.insert(new_matches, m)
        end
    end
    return new_matches
end

function my_match_generator:generate(line_state, match_builder)
    ...
    clink.ondisplaymatches(my_filter)
end

Note: In v1.3.1 and higher, the table received by the registered ondisplaymatches function includes all the match fields (such as display, description, appendchar, etc), and the returned table can also include any of these fields. In other words, in v1.3.1 and higher match filtering supports all the same fields as builder:addmatch().

.

Argument Completion

Clink provides a framework for writing complex argument match generators in Lua. It works by creating a parser object that describes a command's arguments and flags and associating the parser with one or more commands. When Clink detects a parser is associated with the command being edited, it uses the parser to generate matches.

.

The Basics

Here is an example of a simple parser for the command foobar;

clink.argmatcher("foobar")
:addarg({ "hello", "hi" })               -- Completions for arg #1.
:addarg({ "world", "wombles", "xyzzy" }) -- Completions for arg #2.
:addflags("-foo", "-bar")                -- Flags.

This parser describes a command that has two arguments, and some flags.

Arguments are positional. Each :addarg() adds a new argument position and defines the possible completions for that argument position.

Flags are position independent. Any :addflags() add to the set of possible flag completions. Any word that begins with the flag prefix character (in this example -) is considered to be a flag, even if it is not listed as a possible completion. The flags may be input at any position; before arguments, between arguments, and after arguments.

On the command line completion would look something like this, if Alt-= were pressed at the end of each input line below:

C:\>foobar -
-bar  -foo
C:\>foobar -bar hello
wombles  world  xyzzy
C:\>foobar -bar hello wo
wombles  world
C:\>foobar -bar hello wombles -
-bar -foo
C:\>foobar -bar hello wombles -foo _

When displaying possible completions, flag matches are only shown if the flag character has been input. So foobar and Alt-= would list matches for the first argument position, or foobar some_word and Alt-= would list matches for the second argument position, or foobar - and Alt-= would list only flag matches.

If a command doesn't have an argmatcher but is a doskey macro, Clink automatically expands the doskey macro and looks for an argmatcher for the expanded command. A macro like gco=git checkout $* automatically reuses a git argmatcher and produces completions for its checkout argument. However, it only expands the doskey macro up to the first $, so complex aliases like foo=app 2$gnul text $* or foo=$2 $1 might behave strangely.

Also see clink.argmatcher(), :addflags() and :addarg().

.

Automatic Filename Completion

A fresh, empty argmatcher provides no completions.

clink.argmatcher("foobar")               -- The "foobar" command provides no completions.

Once any flags or argument positions have been added to an argmatcher, then the argmatcher will provide completions.

clink.argmatcher("foobar")
:addarg({ "hello", "hi" })               -- Completions for arg #1.
:addarg({ "world", "wombles", "xyzzy" }) -- Completions for arg #2.
:addflags("-foo", "-bar")                -- Flags.

When completing a word that doesn't have a corresponding argument position the argmatcher will automatically use filename completion. For example, the foobar argmatcher has two argument positions, and completing a third word uses filename completion.

C:\>foobar hello world pro
Program Files\  Program Files(x86)\  ProgramData\
C:\>foobar hello world pro_

Use _argmatcher:nofiles() if you want to disable the automatic filename completion and "dead end" an argmatcher for extra words. This stops all further parsing for the command.

clink.argmatcher("foobar")
:addarg({ "hello", "hi" })               -- Completions for arg #1
:addarg({ "world", "wombles", "xyzzy" }) -- Completions for arg #2
:addflags("-foo", "-bar")                -- Flags
:nofiles()                               -- Using :nofiles() prevents further completions.

.

Descriptions for Flags and Arguments

Flags and arguments may optionally have descriptions associated with them. The descriptions, if any, are displayed when listing possible completions.

Use _argmatcher:adddescriptions() to add descriptions for flags and/or arguments. Refer to its documentation for further details about how to use it, including how to also show arguments that a flag accepts.

For example, with the following matcher, typing foo -Alt-= will list all of the flags, plus descriptions for each.

clink.argmatcher("foo")
:addflags("-?", "-h", "-n", "-v", "--help", "--nothing", "--verbose")
:addarg("print", "delete")
:addarg(clink.filematches)
:nofiles()
:adddescriptions(
    { "-n", "--nothing",    description = "Do nothing; show what would happen without doing it" },
    { "-v", "--verbose",    description = "Verbose output" },
    { "-h", "--help", "-?", description = "Show help text" },
    { "print",              description = "Print the specified file" },
    { "delete",             description = "Delete the specified file" },
)

.

More Advanced Stuff

.

Linking Parsers

There are often situations where the parsing of a command's arguments is dependent on the previous words (git merge ... compared to git log ... for example). For these scenarios Clink allows you to link parsers to arguments' words using Lua's concatenation operator.

local a_parser = clink.argmatcher():addarg({ "foo", "bar" })
local b_parser = clink.argmatcher():addarg({ "abc", "123" })
local c_parser = clink.argmatcher()
c_parser:addarg({ "foobar" .. a_parser })   -- Arg #1 is "foobar", which has args "foo" or "bar".
c_parser:addarg({ b_parser })               -- Arg #2 is "abc" or "123".

As the example above shows, it is also possible to use a parser without concatenating it to a word.

When Clink follows a link to a parser it will only return to the previous parser when the linked parser runs out of arguments. Using :nofiles() prevents returning to the previous parser.

.

Flags With Arguments

Parsers can be concatenated with flags, too.

Here's an example of a flag that takes an argument:

clink.argmatcher("git")
:addarg({
    "merge"..clink.argmatcher():addflags({
        "--strategy"..clink.argmatcher():addarg({
            "resolve",
            "recursive",
            "ours",
            "octopus",
            "subtree",
        })
    })
})

A : or = at the end of a flag indicates the flag takes an argument but requires no space between the flag and its argument. If such a flag is not linked to a parser, then it automatically gets linked to a parser to match files. Here's an example with a few flags that take arguments without a space in between:

clink.argmatcher("findstr")
:addflags({
    "/b", "/e", "/l", "/r", "/s", "/i", "/x", "/v", "/n", "/m", "/o", "/p", "/offline",
    "/a:"..clink.argmatcher():addarg( "attr" ),
    "/f:"..clink.argmatcher():addarg( clink.filematches ),
    "/c:"..clink.argmatcher():addarg( "search_string" ),
    "/g:", -- This is the same as linking with clink.argmatcher():addarg(clink.filematches).
    "/d:"..clink.argmatcher():addarg( clink.dirmatches )
})

.

Functions As Argument Options

Argument options are not limited solely to strings. Clink also accepts functions too so more context aware argument options can be used.

The function is called each time matches are generated for the argument position.

local function rainbow_function(word)
    return { "red", "white", "blue" }
end

local the_parser = clink.argmatcher()
the_parser:addarg({ "zippy", "bungle", "george" })
the_parser:addarg({ rainbow_function, "yellow", "green" })

The functions are passed five arguments, and should return a table of potential matches (strings). The table may optionally also contain tables that describe the matches; the format is the same as in builder:addmatches().

• word is a partial string for the word under the cursor, corresponding to the argument for which matches are being generated: it is an empty string, or if a filename is being entered then it will be the path portion (e.g. for "dir1\dir2\pre" word will be "dir1\dir2").
• word_index is the word index in line_state, corresponding to the argument for which matches are being generated.
• line_state is a line_state object that contains the words for the associated command line.
• match_builder is a builder object (but for adding matches the function should return them in a table).
• user_data is a table that the argmatcher can use to help it parse the input line. See Responding to Arguments in Argmatchers for more information about the user_data table.

Compatibility Note: When a function argument uses the old v0.4.9 clink.match_display_filter approach, then the word argument will be the full word under the cursor, for compatibility with the v0.4.9 API.

Some built-in matcher functions are available:

.

Generate Matches From History

An argument position can collect matches from the history file. When an argument table contains fromhistory=true then additional matches are generated by parsing the history file to find values for that argument slot from commands in the history file.

This example generates matches for arguments to a --host flag by parsing the history file for host names used in the past, and also includes the current computer name.

local host_parser = clink.argmatcher():addarg({ fromhistory=true, os.getenv("COMPUTERNAME") })
clink.argmatcher("program"):addflags({ "--host"..host_parser })

.

Disable Sorting Matches

Match completions are normally listed in sorted order. In some cases it may be desirable to disable sorting and list match completions in a specific order. To disable sorting, include nosort=true in the argument table. When sorting is disabled, matches are listed in the order they were added.

local the_parser = clink.argmatcher()
the_parser:addarg({ nosort=true, "red", "orange", "yellow", "green", "blue", "indigo", "violet" })

.

Fully Qualified Pathnames

Sometimes there may be more than one program installed with the same name. For example, there might be multiple versions of grep installed.

In Clink v1.3.38 and higher, you can define argmatchers using fully qualified pathnames. For example, this makes it possible to define one argmatcher for c:\EmployerTools\grep.exe and another for d:\PersonalTools\grep.exe, and the corresponding argmatcher will be used when appropriate.

In the example above, you could define an argmatcher for c:\EmployerTools\grep.exe, and also define an argmatcher for grep (or have a grep.lua file in a completions directory). The plain grep one would be used whenever the typed grep doesn't resolve to the EmployerTools copy.

.

Delimited Arguments

In some cases an argument for programs may accept a list of values separated by ; or + or etc. Normally ; or + are argument separators (like space), and advance the argmatcher to the next argument slot.

In Clink v1.3.37 and higher, you can make them stay on the current argument slot by including loopchars=";" (or set loopchars= a list of value delimiters).

-- This argmatcher accepts syntax like "foo color filename".
-- Typing "foo red f" and pressing TAB generates completions for files.
-- Typing "foo red;" and pressing TAB generates completions for files.
clink.argmatcher("foo")
:addarg({"red", "green", "blue"})
:addarg(clink.filematches)

-- This argmatcher accepts syntax like "foo color[;color...] filename".
-- Typing "foo red f" and pressing TAB generates completions for files.
-- Typing "foo red;" and pressing TAB generates completions for colors (not files).
clink.argmatcher("foo")
:addarg({loopchars=";", "red", "green", "blue"})
:addarg(clink.filematches)

.

Adaptive Argmatchers

Some argmatchers may need to adapt on the fly. For example, a program may have different features available depending on the current directory, or may want to define its arguments and flags by parsing the --help text from running a program.

An argmatcher can define a "delayed initialization" callback function that gets calls when the argmatcher gets used, allowing it to defer potentially expensive initialization work until it's actually needed. An argmatcher can also define a separate "delayed initialization" function for each argument position.

.

Delayed initialization for the argmatcher

You can use _argmatcher:setdelayinit() to set a function that performs delayed initialization for the argmatcher. The function receives one parameter:

• argmatcher is the argmatcher to be initialized.

If the definition needs to adapt based on the current directory or other criteria, then the callback function should first test whether the definition needs to change. If so, first reset the argmatcher and then initialize it. To reset the argmatcher, use _argmatcher:reset() which resets it back to an empty, freshly created state.

local prev_dir = ""

-- Initialize the argmatcher.
-- v1.3.12 and higher receive a command_word parameter as well, which is the
-- word in the command line that matched this argmatcher.
local function init(argmatcher, command_word)
    local r = io.popen("some_command --help 2>nul")
    for line in r:lines() do
        -- PUT PARSING CODE HERE.
        -- Use the Lua string functions to parse the lines.
        -- Use argmatcher:addflags(), argmatcher:addarg(), etc to initialize the argmatcher.
    end
    r:close()
end

-- This function has the opportunity to reset and (re)initialize the argmatcher.
local function ondelayinit(argmatcher)
    local dir = os.getcwd()
    if prev_dir ~= dir then  -- When current directory has changed,
        prev_dir = dir      -- Remember the new current directory,
        argmatcher:reset()  -- Reset the argmatcher,
        init(argmatcher)    -- And re-initialize it.
    end
end

-- Create the argmatcher and set up delayed initialization.
local m = clink.argmatcher("some_command")
if m.setdelayinit then        -- Can't use setdelayinit before Clink v1.3.10.
    m:setdelayinit(ondelayinit)
end

.

Delayed initialization for an argument position

If the overall flags and meaning of the argument positions don't need to be updated, and only the possible values need to be updated within certain argument positions, then you can include delayinit=function in the argument table.

The function should return a table of matches which will be added to the values for the argument position. The table of matches supports the same syntax as _argmatcher:addarg(). The function receives two parameters:

• argmatcher is the current argmatcher.
• argindex is the argument position in the argmatcher (0 is flags, 1 is the first argument position, 2 is the second argument position, and so on).

The function is called only once, the first time the argument position is used. The only way for the function to be called again for that argmatcher is to use Delayed initialization for the argmatcher and reset the argmatcher and then re-initialize it.

Delayed initialization for an argument position is different from Functions As Argument Options. The delayinit function is called the first time the argmatcher is used, and the results are added to the matches for the rest of the Clink session. But a function as an argument option is called every time matches are generated for the argument position, and it is never called when applying input line coloring.

-- A function to delay-initialize argument values.
-- This function is used to delay-initialize two different argument positions,
-- and so it gets called up to two separate times (once for each position where
-- it is specified).
-- If the function needs to behave slightly differently for different
-- argmatchers or argument positions, it can use the two parameters it receives
-- to identify the specific context in which it is being called.
local function sc_init_dirs(argmatcher, argindex)
    return {
        path.join(os.getenv("USERPROFILE"), "Documents"),
        path.join(os.getenv("USERPROFILE"), "Pictures")
    }
end

-- A function to delay-initialize flag values.
local function sc_init_flags(argmatcher)
    -- This calls sc_init_dirs() when the '--dir=' flag is used.
    return { "--dir=" .. clink.argmatcher():addarg({ delayinit=sc_init_dirs }) }
end

-- Define an argmatcher with two argument positions, and the second one uses
-- delayed initialization.
local m = clink.argmatcher("some_command")
m:addarg({ "abc", "def", "ghi" })
m:addarg({ delayinit=sc_init_dirs }) -- This sc_init_dirs() when the second arg position is used.

-- You can also use delayinit with flags, but you must set the flag prefix
-- character(s) so that Clink can know when to call the delayinit function.
m:addflags({ delayinit=sc_init_flags })
m:setflagprefix("-")

.

Responding to Arguments in Argmatchers

Argmatchers can be more involved in parsing the command line, if they wish.

An argmatcher can supply an "on arg" function to be called when the argmatcher parses an argument position. The function can influence parsing the rest of the input line. For example, the presence of a flag --only-dirs might change what match completions should be provided somewhere else in the input line.

Supply an "on arg" function by including onarg=function in the argument table with _argmatcher:addarg(). The function is passed five arguments, and it doesn't return anything (the function receives the same arguments as Functions As Argument Options).

• arg_index is the argument index in the argmatcher, corresponding to the argument being parsed. 0 means it is a flag, rather than an argument.
• word is a partial string for the word under the cursor, corresponding to the argument being parsed: it is an empty string, or if a filename is being entered then it will be the path portion (e.g. for "dir1\dir2\pre" word will be "dir1\dir2").
• word_index is the word index in line_state, corresponding to the argument being parsed.
• line_state is a line_state object that contains the words for the associated command line.
• user_data is a table that the argmatcher can use to help it parse the input line.

When parsing begins, the user_data is an empty table. Each time a flag or argument links to another argmatcher, the new argmatcher gets a separate new empty user_data table. Your "on arg" functions can set data from the table, and then can also get data that was set earlier by your "on arg" functions.

An "on arg" function can also use os.chdir() to set the current directory. Generating match completions saves and restores the current directory when finished, so argmatcher "on arg" functions can set the current directory and thus cause match completion later in the input line to complete file names relative to the change directory. For example, the built-in cd and pushd argmatches use an "on arg" function so that pushd \other_dir & program Tab can complete file names from \other_dir instead of the (real) current directory.

local function onarg_pushd(arg_index, word, word_index, line_state, user_data)
    -- Match generation after this is relative to the new directory.
    if word ~= "" then
        os.chdir(word)
    end
end

clink.argmatcher("pushd")
:addarg({
    onarg=onarg_pushd,  -- Chdir to the directory argument.
    clink.dirmatches,   -- Generate directory matches.
})
:nofiles()

.

Shorthand

It is also possible to omit the addarg and addflags function calls and use a more declarative shorthand form:

-- Shorthand form; requires tables.
clink.argmatcher()
    { "one", "won" }                -- Arg #1
    { "two", "too" }                -- Arg #2
    { "-a", "-b", "/?", "/h" }      -- Flags

-- Normal form:
clink.argmatcher()
:addarg({ "one", "won" })           -- Arg #1
:addarg({ "two", "too" })           -- Arg #2
:addflags("-a", "-b", "/?", "/h")   -- Flags

With the shorthand form flags are implied rather than declared. When a shorthand table's first value is a string starting with - or / then the table is interpreted as flags. Note that it's still possible with shorthand form to mix flag prefixes, and even add additional flag prefixes, such as { '-a', '/b', '=c' }.

.

Coloring the Input Text

When the clink.colorize_input setting is disabled, then the entire input line is colored by the color.input setting. When the setting is enabled, then argmatchers automatically apply colors to the input text as they parse it.

.

Coloring the Command Word

The command word is colored based on the command type, in priority order:

1. Commands that have an argmatcher defined use color.argmatcher.
2. Built-in CMD commands use color.cmd.
3. Doskey aliases use color.doskey.
4. Recognized executable files use color.executable if it is set.
5. Unrecognized command words use color.unrecognized if it is set.
6. If none of the above apply, then color.input is used.

Here are examples, using the colors from the Use enhanced defaults installation option:

c:\dir>clink
'clink' has an argmatcher
c:\dir>attrib
'attrib' is a CMD command
c:\dir>myalias
if 'myalias' is a doskey alias
c:\dir>control
'control' is an executable
c:\dir>xyzabc123
unrecognized
c:\dir>whatever
if executable and unrecognized colors are not set

.

Coloring Command Separators and Redirection

Command separators and redirection are colored accordingly:

• Command separators use color.cmdsep.
• Redirection symbols use color.cmdredir.
• Redirected files use color.input.

Here are examples, using the colors from the Use enhanced defaults installation option:

c:\dir>pushd & popd
'&' is the command separator
c:\dir>set >file
redirecting 'set' to 'file'

.

Coloring Other Input Text

Other input words are colored based on how argmatchers parse the input text.

• If an argmatcher isn't defined for a command, then the input text is colored using color.input.
• Flags defined by the command's argmatcher use color.flag.
• Arguments defined by the command's argmatcher use color.arg.
• Text the goes past what the command's argmatcher expects uses color.unexpected.

Here are examples, using the colors from the Use enhanced defaults installation option:

c:\dir>clink --help
'--help' is defined as a flag for 'clink'
c:\dir>clink set
'set' is defined as an argument for 'clink'
c:\dir>clink set color.arg
'color.arg' is defined as an argument for 'clink set'
c:\dir>clink set abc.xyz
'abc.xyz' is not a recognized argument for 'clink set'
c:\dir>findstr /s needle haystack\*
if 'findstr' has no argmatcher, all words use 'color.input'

.

More Advanced Stuff

.

Setting a classifier function in an argmatcher

In cases where an argmatcher isn't able to color the input text in the desired manner, it's possible to supply a classifier function that overrides how the argmatcher colors the input text. An argmatcher's classifier function is called once for each word the argmatcher parses, but it can classify any words (not just the word it was called for). Each argmatcher can have its own classifier function, so when there are linked argmatchers more than one function may be invoked.

Words are colored by classifying the words, and each classification has an associated color. See word_classifications:classifyword() for the available classification codes.

The clink set command has different syntax depending on the setting type, so the argmatcher for clink needs help in order to get everything right. A custom generator function parses the input text to provide appropriate matches, and a custom classifier function applies appropriate coloring.

-- In this example, the argmatcher matches a directory as the first argument and
-- a file as the second argument.  It uses a word classifier function to classify
-- directories (words that end with a path separator) as "unexpected" in the
-- second argument position.

local function classify_handler(arg_index, word, word_index, line_state, classifications)
    -- `arg_index` is the argument position in the argmatcher.
    -- In this example only position 2 needs special treatent.
    if arg_index ~= 2 then
        return
    end

    -- `arg_index` is the argument position in the argmatcher.
    -- `word_index` is the word position in the `line_state`.
    -- Ex1: in `samp dir file` for the word `dir` the argument index is 1 and
    -- the word index is 2.
    -- Ex2: in `samp --help dir file` for the word `dir` the argument index is
    -- still 1, but the word index is 3.

    -- `word` is the word the classifier function was called for and `word_index`
    -- is its position in the line.  Because `line_state` is also provided, the
    -- function can examine any words in the input line.
    if word:sub(-1) == "\\" then
        -- The word appears to be a directory, but this example expects only
        -- files in argument position 2.  Here the word gets classified as "n"
        -- (unexpected) so it gets colored differently.
        classifications:classifyword(word_index, "n")
    end
end

local matcher = clink.argmatcher("samp")
:addflags("--help")
:addarg({ clink.dirmatches })
:addarg({ clink.filematches })
:setclassifier(classify_handler)

.

Setting a classifier function for the whole input line

In some cases it may be desireable to use a custom classifier to apply coloring in an input line.

First create a classifier object:

local my_classifier = clink.classifier(priority)

The priority argument is a number that influences when the classifier gets called, with lower numbers going before higher numbers.

Next define a classify function on the object, taking the following form:

function my_classifier:classify(commands)
    -- See further below for how to use the commands argument.
    -- Returning true stops any further classifiers from being called, or
    -- returning false or nil continues letting other classifiers get called.
end

commands is a table of tables, with the following scheme:

-- commands[n].line_state           [line_state] Contains the words for the Nth command.
-- commands[n].classifications      [word_classifications] Use this to classify the words.

The line_state field is a line_state object that contains the words for the associated command line.

The classifications field is a word_classifications object to use for classifying the words in the associated command line.

-- In this example, a custom classifier applies colors to environment variables
-- in the input line.
local envvar_classifier = clink.classifier(50)
function envvar_classifier:classify(commands)
    -- This example doesn't need to parse words within commands, it just wants
    -- to parse the whole line.
    --
    -- So it can simply use the first command's `classifications` object because
    -- the `classifications:applycolor()` method can apply color anywhere in the
    -- entire input line.
    --
    -- (Note that the `classifications:classifyword()` method can only affect
    -- the words for its corresponding command.)
    if commands[1] then
        local line_state = commands[1].line_state
        local classifications = commands[1].classifications
        local line = line_state:getline()
        local len = #line

        -- Loop through the line looking for environment variables, starting at
        -- the first character of the line.
        local idx = 1
        while (idx <= len) do
            -- Find the next percent sign (idx is walking through the line).
            local pos = line:find('%', idx, true--[[plain]])
            if not pos then
                -- No more?  Then all done.
                break
            end

            -- Find the next percent sign (which would close the possible
            -- environment variable).
            local posend = line:find('%', pos + 1, true--[[plain]])
            if not posend then
                -- No close?  Then all done.
                break
            end

            -- Extract the text between the percent signs and check if there
            -- is an environment variable by that name.
            local name = line:sub(pos + 1, posend - 1)
            if name == '' then
                -- Skip a double percent.  It's an escaped percent sign, not an
                -- environment variable.
                idx = posend + 1
            elseif os.getenv(name) then
                -- Apply a color to the environment variable.
                classifications:applycolor(pos, posend - pos + 1, "95")
                idx = posend + 1
            else
                -- Ignore the percent sign, but continue looking for more.
                idx = idx + 1
            end
        end
    end
end

.

Customizing the Prompt

Before Clink displays the prompt it filters the prompt through Lua so that the prompt can be customized. This happens each and every time that the prompt is shown which allows for context sensitive customizations (such as showing the current branch of a git repository).

.

The Basics

Writing a prompt filter is straightforward:

1. Create a new prompt filter by calling clink.promptfilter() along with a priority id which dictates the order in which filters are called. Lower priority ids are called first.
2. Define a :filter() function on the returned prompt filter.

The filter function takes a string argument that contains the filtered prompt so far. If the filter function returns nil, it has no effect. If the filter function returns a string, that string is used as the new filtered prompt (and may be further modified by other prompt filters with higher priority ids). If the filter function returns a string and a boolean, then if the boolean is false the prompt filtering is done and no further filter functions are called.

local p = clink.promptfilter(30)
function p:filter(prompt)
    return "new prefix "..prompt.." new suffix" -- Add ,false to stop filtering.
end

The following example illustrates setting the prompt, modifying the prompt, using ANSI escape code for colors, running a git command to find the current branch, and stopping any further processing.

local green  = "\x1b[92m"
local yellow = "\x1b[93m"
local cyan   = "\x1b[36m"
local normal = "\x1b[m"

-- A prompt filter that discards any prompt so far and sets the
-- prompt to the current working directory.  An ANSI escape code
-- colors it yellow.
local cwd_prompt = clink.promptfilter(30)
function cwd_prompt:filter(prompt)
    return yellow..os.getcwd()..normal
end

-- A prompt filter that inserts the date at the beginning of the
-- the prompt.  An ANSI escape code colors the date green.
local date_prompt = clink.promptfilter(40)
function date_prompt:filter(prompt)
    return green..os.date("%a %H:%M")..normal.." "..prompt
end

-- A prompt filter that may stop further prompt filtering.
-- This is a silly example, but on Wednesdays, it stops the
-- filtering, which in this example prevents git branch
-- detection and the line feed and angle bracket.
local wednesday_silliness = clink.promptfilter(60)
function wednesday_silliness:filter(prompt)
    if os.date("%a") == "Wed" then
        -- The ,false stops any further filtering.
        return prompt.." HAPPY HUMP DAY! ", false
    end
end

-- A prompt filter that appends the current git branch.
local git_branch_prompt = clink.promptfilter(65)
function git_branch_prompt:filter(prompt)
    local line = io.popen("git branch --show-current 2>nul"):read("*a")
    local branch = line:match("(.+)\n")
    if branch then
        return prompt.." "..cyan.."["..branch.."]"..normal
    end
end

-- A prompt filter that adds a line feed and angle bracket.
local bracket_prompt = clink.promptfilter(150)
function bracket_prompt:filter(prompt)
    return prompt.."\n> "
end

The resulting prompt will look like this:

Wed 12:54 c:\dir [master]
> _

...except on Wednesdays, when it will look like this:

Wed 12:54 c:\dir HAPPY HUMP DAY! _

.

ANSI escape codes in the prompt string

Readline needs to be told which characters in the prompt are unprintable or invisible. To help with that, Clink automatically detects most standard ANSI escape codes (and most of ConEmu's non-standard escape codes) and the BEL character (^G, audible bell) and surrounds them with \001 (^A) and \002 (^B) characters. For any other unprintable characters, the \001 and \002 characters need to be added manually. Otherwise Readline misinterprets the length of the prompt and can display the prompt and input line incorrectly in some cases (especially if the input line wraps onto a second line).

Here are a couple of links with more information about ANSI escape codes:

• Wikipedia - ANSI Escape Code
• Console Virtual Terminal Sequences

.

More Advanced Stuff

.

Right Side Prompt

In addition to the normal prompt filtering, Clink can also show a prompt on the right side of the first line of input. The right side prompt defaults to the value of the %CLINK_RPROMPT% environment variable, if set, otherwise it is blank. This right side prompt is automatically hidden if the input line text reaches it.

Clink expands CMD prompt $ codes in %CLINK_RPROMPT%, with a few exceptions: $+ is not supported, $_ ends the prompt string (it can't be more than one line), and $V is not supported. Additionally, if %CLINK_RPROMPT% ends with $M then trailing spaces are trimmed from the expanded string, to maintain right alignment since $M includes a space if the current drive is a network drive (so e.g. $t $d $m is right-aligned regardless whether the current drive has a remote name).

The right side prompt can be filtered through Lua just like the normal prompt can be. Simply define a :rightfilter() function on the prompt filter returned by a call to clink.promptfilter(). A prompt filter can define both :filter() and :rightfilter(), or can define only :filter().

The :rightfilter() function works the same as the :filter() function, except that it operates on the right side prompt. It takes a string argument that contains the filtered right side prompt so far. If the rightfilter function returns nil, it has no effect. If the rightfilter function returns a string, that string is used as the new filtered right side prompt (and may be further modified by other prompt filters with higher priority ids). If either the rightfilter function or the normal filter function returns a string and a boolean, then if the boolean is false the prompt filtering is done and no further filter functions are called.

This example modifies the right side prompt by prepending the current date:

local p = clink.promptfilter(30)
function p:filter(prompt)
    -- The :filter() function must be defined.  But if the prompt filter is
    -- only interested in modifying the right side prompt, then the :filter()
    -- function may do nothing.
end
function p:rightfilter(prompt)
    local sep = #prompt > 0 and "  " or ""
    return os.date()..sep..prompt
end

Notes:

• If the console font and encoding are mismatched, or if some kinds of emoji are present, then the right side prompt might show up positioned incorrectly. If that happens, try adjusting the font or encoding (e.g. sometimes running chcp utf-8 can resolve positioning issues).
• If the :filter() function returns a string and false to stop filtering, then the :rightfilter() is not called (because no further filter functions are called). If you want to stop filtering but have both a left and right side prompt, then return only a string from :filter() and return a string and false from :rightfilter().

.

Asynchronous Prompt Filtering

Prompt filtering needs to be fast, or it can interfere with using the shell (e.g. git status can be slow in a large repo).

Clink provides a way for prompt filters to do some initial work and set the prompt, continue doing work in the background, and then refresh the prompt again when the background work is finished. This is accomplished by using Lua coroutines, but Clink simplifies and streamlines the process.

A prompt filter can call clink.promptcoroutine(my_func) to run my_func() inside a coroutine. Clink will automatically resume the coroutine repeatedly while input line editing is idle. When my_func() completes, Clink will automatically refresh the prompt by triggering prompt filtering again.

Typically the motivation to use asynchronous prompt filtering is that one or more io.popen("some slow command") calls take too long. They can be replaced with io.popenyield() calls inside the prompt coroutine to let them run in the background.

Global data: If my_func() needs to use any global data, then it's important to use clink.onbeginedit() to register an event handler that can reset the global data for each new input line session. Otherwise the data may accidentally "bleed" across different input line sessions.

Backward compatibility: A prompt filter must handle backward compatibility itself if it needs to run on versions of Clink that don't support asynchronous prompt filtering (v1.2.9 and lower). E.g. you can use if clink.promptcoroutine then to test whether the API exists.

The following example illustrates running git status in the background. It also remembers the status from the previous input line, so that it can reduce flicker by using the color from last time until the background status operation completes.

local prev_dir      -- Most recent git repo visited.
local prev_info     -- Most recent info retrieved by the coroutine.

local function get_git_dir(dir)
    -- Check if the current directory is in a git repo.
    local child
    repeat
        if os.isdir(path.join(dir, ".git")) then
            return dir
        end
        -- Walk up one level to the parent directory.
        dir,child = path.toparent(dir)
        -- If child is empty, we've reached the top.
    until (not child or child == "")
    return nil
end

local function get_git_branch()
    -- Get the current git branch name.
    local file = io.popen("git branch --show-current 2>nul")
    local branch = file:read("*a"):match("(.+)\n")
    file:close()
    return branch
end

local function get_git_status()
    -- The io.popenyield API is like io.popen, but it yields until the output is
    -- ready to be read.
    local file = io.popenyield("git --no-optional-locks status --porcelain 2>nul")
    local status = false
    for line in file:lines() do
        -- If there's any output, the status is not clean.  Since this example
        -- doesn't analyze the details, it can stop once it knows there's any
        -- output at all.
        status = true
        break
    end
    file:close()
    return status
end

local function get_git_conflict()
    -- The io.popenyield API is like io.popen, but it yields until the output is
    -- ready to be read.
    local file = io.popenyield("git diff --name-only --diff-filter=U 2>nul")
    local conflict = false
    for line in file:lines() do
        -- If there's any output, there's a conflict.
        conflict = true
        break
    end
    file:close()
    return conflict
end

local function collect_git_info()
    -- This is run inside the coroutine, which happens while idle while waiting
    -- for keyboard input.
    local info = {}
    info.status = get_git_status()
    info.conflict = get_git_conflict()
    -- Until this returns, the call to clink.promptcoroutine() will keep
    -- returning nil.  After this returns, subsequent calls to
    -- clink.promptcoroutine() will keep returning this return value, until a
    -- new input line begins.
    return info
end

local git_prompt = clink.promptfilter(55)
function git_prompt:filter(prompt)
    -- Do nothing if not a git repo.
    local dir = get_git_dir(os.getcwd())
    if not dir then
        return
    end
    -- Reset the cached status if in a different repo.
    if prev_dir ~= dir then
        prev_info = nil
        prev_dir = dir
    end
    -- Do nothing if git branch not available.  Getting the branch name is fast,
    -- so it can run outside the coroutine.  That way the branch name is visible
    -- even while the coroutine is running.
    local branch = get_git_branch()
    if not branch or branch == "" then
        return
    end
    -- Start a coroutine to collect various git info in the background.  The
    -- clink.promptcoroutine() call returns nil immediately, and the
    -- coroutine runs in the background.  After the coroutine finishes, prompt
    -- filtering is triggered again, and subsequent clink.promptcoroutine()
    -- calls from this prompt filter immediately return whatever the
    -- collect_git_info() function returned when it completed.  When a new input
    -- line begins, the coroutine results are reset to nil to allow new results.
    local info = clink.promptcoroutine(collect_git_info)
    -- If no status yet, use the status from the previous prompt.
    if info == nil then
        info = prev_info or {}
    else
        prev_info = info
    end
    -- Choose color for the git branch name:  green if status is clean, yellow
    -- if status is not clean, red if conflict is present, or default color if
    -- status isn't known yet.
    local sgr = "37;1"
    if info.conflict then
        sgr = "31;1"
    elseif info.status ~= nil then
        sgr = info.status and "33;1" or "32;1"
    end
    -- Prefix the prompt with "[branch]" using the status color.
    return "\x1b["..sgr.."m["..branch.."]\x1b[m  "..prompt
end

.

Transient Prompt

Clink can replace a past prompt with a differently formatted "transient" prompt. For example, if your normal prompt contains many bits of information that don't need to be seen later, then it may be desirable to replace past prompts with a simpler prompt. Or it may be useful to update the timestamp in a prompt to indicate when the prompt was completed, rather than when it was first shown.

The %CLINK_TRANSIENT_PROMPT% environment variable provides the initial prompt string for the transient prompt.

Turn on the transient prompt with clink set prompt.transient always. Or use same_dir instead of always to only use a transient prompt when the current directory is the same as the previous prompt.

The transient prompt can be customized by a prompt filter:

1. Create a new prompt filter by calling clink.promptfilter() along with a priority id which dictates the order in which filters are called. Lower priority ids are called first.
2. Define a :transientfilter() function on the returned prompt filter.

The transient filter function takes a string argument that contains the filtered prompt so far. If the filter function returns nil, it has no effect. If the filter function returns a string, that string is used as the new filtered prompt (and may be further modified by other prompt filters with higher priority ids). If the filter function returns a string and a boolean, then if the boolean is false the prompt filtering is done and no further filter functions are called.

A transient right side prompt is also possible (similar to the usual right side prompt). The %CLINK_TRANSIENT_RPROMPT% environment variable (note the R in _RPROMPT) provides the initial prompt string for the transient right side prompt, which can be customized by a :transientrightfilter() function on a prompt filter.

A prompt filter must have a :filter() function defined on it, and may in addition have any combination of :rightfilter(), :transientfilter(), and :transientrightfilter() functions defined on it.

The next example shows how to make a prompt that shows:

1. The current directory and > on the left, and the date and time on the right.
2. Just > on the left, for past commands.

-- Colors for the prompt strings.
local cwd_color  = "\x1b[0;1;37;44m"
local symbol_color = "\x1b[0;1;34m"
local date_color = "\x1b[0;36m"
local normal = "\x1b[m"

-- Create prompt filter.
local pf = clink.promptfilter(10)

-- Customize the normal prompt.
function pf:filter(prompt)
    -- Don't return false yet; let rightfilter have a chance.
    return cwd_color.." "..os.getcwd().." "..symbol_color.." > "..normal
end

-- Customize the normal right side prompt.
function pf:rightfilter(prompt)
    -- Returns false to stop filtering.
    return date_color..os.date(), false
end

-- Customize the transient prompt.
function pf:transientfilter(prompt)
    -- Don't return false yet; let transientrightfilter have a chance.
    return symbol_color.."> "..normal
end

-- Customize the transient right side prompt.
function pf:transientrightfilter(prompt)
    -- Returns false to stop filtering.
    return "", false
end

-- Show a reminder to turn on the transient prompt, to try out the example.
if settings.get("prompt.transient") == "off" then
    print("Use 'clink set prompt.transient same_dir' to enable the transient prompt.")
end

.

Customizing Suggestions

Clink can offer suggestions how to complete a command as you type, and you can select how it generates suggestions.

Turn on automatic suggestions with clink set autosuggest.enable true. Once enabled, Clink will show suggestions in a muted color after the end of the typed command. Accept the whole suggestion with the Right arrow or End key, accept the next word of the suggestion with Ctrl-Right, or accept the next full word of the suggestion up to a space with Shift-Right. You can ignore the suggestion if it isn't what you want; suggestions have no effect unless you accept them first.

Scripts can provide custom suggestion generators, in addition to the built-in options:

1. Create a new suggestion generator by calling clink.suggester() along with a name that identifies the suggestion generator, and can be added to the autosuggest.strategy setting.
2. Define a :suggest() function on the returned suggestion generator.

The function takes a line_state argument that contains the input line, and a matches argument that contains the possible matches from the completion engine. If the function returns nil, the next generator listed in the strategy is called. If the function returns a string (even an empty string), then the string is used as the suggestion.

The function can optionally return a string and an offset to where the suggestion begins in the input line. This makes it easier to return suggestions in some cases, and also makes it possible to update the capitalization of the whole accepted suggestion (even the part that's already been typed).

This example illustrates how to make a suggestion generator that returns the longest common prefix of the possible matches.

local prefix_suggestor = clink.suggester("completion_prefix")

function prefix_suggestor:suggest(line_state, matches)
    -- If the input line is empty or only spaces, don't suggest anything.
    if not line_state:getline():match("[^ ]") then
        return
    end

    -- If there is no common prefix, don't suggest anything.
    local prefix = matches:getprefix()
    if prefix == "" then
        return
    end

    -- Return the common prefix as the suggestion.
    local info = line_state:getwordinfo(line_state:getwordcount())
    return prefix, info.offset
end

.

Miscellaneous

These sections provide more information about various aspects of Clink:

.

Customizing Key Bindings

Key bindings are defined in .inputrc files.

The clink-show-help command is bound to Alt-H and lists all currently active key bindings. The list displays "friendly" key names, and these names are generally not suitable for use in .inputrc files. For example "Up" is the friendly name for "\e[A", and "A-C-F2" is the friendly name for "\e\e[1;5Q". To see key sequence strings suitable for use in .inputrc files use clink echo as described below.

.

The .inputrc file

You can use clink info to find the directories and configuration files for the current Clink session, including where the .inputrc file is located, or can be located. See the Readline Init File section for detailed information about .inputrc files.

Note: Third party console hosts such as ConEmu may have their own key bindings that supersede Clink. They usually have documentation for how to change or disable their key bindings to allow console programs to handle the keys instead.

.

Discovering Clink key sequences

Clink provides an easy way to find the key sequence for any key combination that Clink supports. Run clink echo and then press key combinations; the associated key binding sequence is printed to the console output and can be used for a key binding in the inputrc file.

A chord can be formed by concatenating multiple key binding sequences. For example, "\C-X" and "\e[H" can be concatenated to form "\C-X\e[H" representing the chord Ctrl-X,Home.

When finished, press Ctrl-C to exit from clink echo.

Note: With non-US keyboard layouts, clink echo is not able to ignore dead key input (accent keys, for example). It prints the key sequence for the dead key itself, which is not useful. You can ignore that and press the next key, and then it prints the correct key sequence to use in key bindings.

.

Binding special keys

Here is a table of the key binding sequences for the special keys. Clink primarily uses VT220 emulation for keyboard input, but also uses some Xterm extended key sequences.

When the terminal.differentiate_keys setting is enabled then the following key bindings are also available:

The terminal.raw_esc setting controls the binding sequence for the Esc key and a couple of other keys:

.

Lua key bindings

You can bind a key to a Lua function by binding it to a macro that begins with "luafunc:". Clink will invoke the named Lua function when the key binding is input. Function names can include periods (such as foo.bar) but cannot include any other punctuation.

The Lua function receives two arguments:

rl_buffer gives it access to the input buffer.

line_state gives it access to the same line state that a match generator receives.

Lua functions can print output, but should first call rl_buffer:beginoutput() so that the output doesn't overwrite the displayed input line.

Notes:

• The line_state is nil if not using Clink v1.2.34 or higher.
• The end word is always empty for generators. So to get the word at the cursor use:

  local info = line_state:getwordinfo(line_state:getwordcount())
  local word_at_cursor = line_state:getline():sub(info.offset, line_state:getcursor())
  

.

Basic example

Example of a Lua function key binding in a .inputrc file:

M-C-y:          "luafunc:insert_date"
M-C-z:          "luafunc:print_date"

Example functions to go with that:

function insert_date(rl_buffer)
    rl_buffer:insert(os.date("%x %X"))
end

function print_date(rl_buffer)
    rl_buffer:beginoutput()
    print(os.date("%A %B %d, %Y   %I:%M %p"))
end

.

Advanced example

Here is an example that makes F7/F8 jump to the previous/next screen line containing "error" or "warn" colored red or yellow, and makes Shift-F7/Shift-F8 jump to the previous/next prompt line.

One way to use these is when reviewing compiler errors after building a project at the command line. Press Shift-F7 to jump to the previous prompt line, and then use F8 repeatedly to jump to each next compiler warning or error listed on the screen.

Example key bindings for the .inputrc file:

"\e[18~":       "luafunc:find_prev_colored_line"
"\e[19~":       "luafunc:find_next_colored_line"
"\e[18;2~":     "luafunc:find_prev_prompt"
"\e[19;2~":     "luafunc:find_next_prompt"

Example functions to go in a Lua script file:

local max_recent_prompts = 10   -- Keep track of up to this many recent prompts.
local min_match_text = 10       -- Minimum length of text to count as a match.

local recent_prompts = {}       -- Queue of recent prompt match strings.
local scroll_stack = {}         -- Stack of found scroll positions.

-- Remember our most recent scroll position, so that if something else scrolls
-- the screen we can reset the find_prev_prompt/find_next_prompt stack.
local was_top

local function add_recent_prompt(text)
    -- Escape characters that have special meaning in regular expressions.
    text = "^"..text:gsub("([!-/:-@[-`{-~])", "\\%1")

    -- Add new entry at the beginning of the queue.
    table.insert(recent_prompts, 1, text)

    -- Discard excess entries from the end of the queue.
    while #recent_prompts > max_recent_prompts do
        table.remove(recent_prompts)
    end
end

local function reset_prompt_scroll_stack()
    was_top = nil
    scroll_stack = {}
end

local function update_recent_prompt_queue()
    -- Offset minus one because onendedit happens after the cursor moves down
    -- past the end of the input area, which skews the info returned from
    -- rl.getpromptinfo().
    local offset = -1
    local info = rl.getpromptinfo()
    local line = info.promptline + offset
    local last_line = console.getnumlines()

    -- Find a long enough string to be considered part of the prompt.
    while line <= last_line do
        local text = console.getlinetext(line)
        text = text:gsub("%s+$", "")
        if #text >= min_match_text then
            add_recent_prompt(text)
            break
        end
        line = line + 1
    end
end

-- Register for events to maintain the scroll stack and recent prompt queue.
clink.onbeginedit(reset_prompt_scroll_stack)
clink.onendedit(update_recent_prompt_queue)

-- Jumps to the previous prompt on the screen (i.e. move upward, searching for
-- preceding recent prompts).
function find_prev_prompt(rl_buffer)
    local height = console.getheight()
    local offset = math.modf((height - 1) / 2)

    local top = console.gettop()
    if was_top and was_top ~= top then
        reset_prompt_scroll_stack()
    end
    if not was_top then
        was_top = top
    end

    if top <= 1 then
        console.scroll("absolute", 1)
        return
    end

    -- Init the stack if it's empty.
    if #scroll_stack == 0 then
        local info = rl.getpromptinfo()
        scroll_stack[1] = info.promptline
    end

    local count = #scroll_stack
    local start = scroll_stack[count] - 1
    local text = recent_prompts[count]

    if not text then
        if count == 1 then
            -- Only ding if there are none; otherwise visual bell will
            -- scroll back to the bottom.
            rl_buffer:ding()
        else
            -- No more recent prompts?  Maintain the scroll position.
            console.scroll("absolute", scroll_stack[count] - offset)
            was_top = console.gettop()
        end
        return
    end

    -- Search upwards for the next most recent prompt.
    local match
    repeat
        match = console.findprevline(start, text, "regex", {})
        if match <= 0 then
            -- Can't find it?  Maintain the scroll position.
            console.scroll("absolute", scroll_stack[count] - offset)
            was_top = console.gettop()
            return
        end
        start = match - 1
    until match - offset < was_top

    -- Add the found prompt to the stack.
    table.insert(scroll_stack, match)

    -- Scroll to the prompt position
    console.scroll("absolute", match - offset)
    was_top = console.gettop()
end

-- Jump to the next prompt on the screen (i.e. move downward, backtracking over
-- the prompts already visited by find_prev_prompt).
function find_next_prompt(rl_buffer)
    local height = console.getheight()
    local offset = math.modf((height - 1) / 2)

    -- Pop the last found prompt.  If the stack is empty, ding.
    if #scroll_stack > 0 then
        table.remove(scroll_stack)
    end
    if #scroll_stack == 0 then
        rl_buffer:ding()
        return
    end

    -- Get the scroll position of the next to last found prompt.
    local top = scroll_stack[#scroll_stack] - offset
    if #scroll_stack == 1 then
        -- If it's the last prompt, pop it to reset the stack.
        top = console.getnumlines()
        table.remove(scroll_stack, #scroll_stack)
    end

    -- Scroll to the prompt position.
    console.scroll("absolute", top)
    was_top = console.gettop()
end

-- Searches upwards for a line containing "warn" or "error"
-- colored red or yellow.
function find_prev_colored_line(rl_buffer)
    local height = console.getheight()
    local cur_top = console.gettop()
    local offset = math.modf((height - 1) / 2) -- For vertically centering the found line.
    local start = cur_top + offset
    local found_index

    -- Only search if there's still room to scroll up.
    if start - offset > 1 then
        local match = console.findprevline(start - 1, "warn|error", "regex", {4,12,14}, "fore")
        if match ~= nil and match > 0 then
            found_index = match
        end
    end

    -- If scrolled up but no more matches, maintain the scroll position.
    if found_index == nil and cur_top <= console.getnumlines() - height then
        found_index = start
    end

    if found_index ~= nil then
        console.scroll("absolute", found_index - offset)
    else
        rl_buffer:ding()
    end
end

-- Searches downwards for a line containing "warn" or "error"
-- colored red or yellow.
function find_next_colored_line(rl_buffer)
    local height = console.getheight()
    local cur_top = console.gettop()
    local bottom = console.getnumlines()
    local offset = math.modf((height - 1) / 2) -- For vertically centering the found line.
    local start = cur_top + offset
    local found_index

    if cur_top > bottom - height then
        rl_buffer:ding()
        return
    end

    -- Only search if there's still room to scroll down.
    if start - offset + height - 1 < bottom then
        local match = console.findnextline(start + 1, "warn|error", "regex", {4,12,14}, "fore")
        if match ~= nil and match > 0 then
            found_index = match
        end
    end

    if found_index ~= nil then
        console.scroll("absolute", found_index - offset)
    else
        rl_buffer:ding()
    end
end

.

I do not have a Meta or Alt key

If you do not have a Meta or Alt key, or another key working as a Meta key, there is another way to generate "metafied" keystrokes such as M-k.

You can configure clink set terminal.raw_esc true to make the Esc work as it does in Unix and Linux, and then you can type Esc followed by k. This is known as "metafying" the k key.

Clink is a Windows program, and so by default it makes the Esc key reset the input state, since that's how Esc generally works on Windows. When you enable the terminal.raw_esc Clink setting, the Esc key changes its behavior, and pressing unbound special keys can land you in all of the same strange "stuck input" situations as in Unix and Linux.

But it might be more convenient to acquire a keyboard that has an Alt key.

.

Saved Command History

Clink has a list of commands from the current session, and it can be saved and loaded across sessions.

A line won't be added to history if either of the following are true:

• The first word in the line matches one of the words in the history.dont_add_to_history_cmds setting.
• The line begins with a space character.

To prevent doskey alias expansion while still adding the line to history, you can start the line with a semicolon.

There are several settings that control how history works. Run clink set history* to see them.

.

The master history file

When the history.save setting is enabled, then the command history is loaded and saved as follows (or when the setting is disabled, then it isn't saved between sessions).

Every time a new input line starts, Clink reloads the master history list and prunes it not to exceed the history.max_lines setting.

For performance reasons, deleting a history line marks the line as deleted without rewriting the history file. When the number of deleted lines gets too large (exceeding the max lines or 200, whichever is larger) then the history file is compacted: the file is rewritten with the deleted lines removed.

You can force the history file to be compacted regardless of the number of deleted lines by running history compact.

.

Shared command history

When the history.shared setting is enabled, then all instances of Clink update the master history file and reload it every time a new input line starts. This gives the effect that all instances of Clink share the same history -- a command entered in one instance will appear in other instances' history the next time they start an input line.

When the setting is disabled, then each instance of Clink loads the master file but doesn't append its own history back to the master file until after it exits, giving the effect that once an instance starts its history is isolated from other instances' history.

.

Multiple master history files

Normally Clink saves a single saved master history list. All instances of Clink load and save the same master history list.

It's also possible to make one or more instances of Clink use a different saved master history list by setting the %CLINK_HISTORY_LABEL% environment variable. This can be up to 32 alphanumeric characters, and is appended to the master history file name. Changing the %CLINK_HISTORY_LABEL% environment variable takes effect at the next input line.

.

History timestamps

History items can optionally save the timestamp when they were added, and the timestamps can be shown in the history command.

Use clink set history.time_stamp off to not save or show timestamps for history items (this is the default). Turning off timestamps doesn't remove existing timestamps.

Use clink set history.time_stamp save to save timestamps for each history item but only show them in the history command when the --show-time flag is used.

Use clink set history.time_stamp show to save timestamps for each history item and show them in the history command unless the --bare flag is used.

Use clink set history.time_format format to specify the format for showing timestamps (the default format is %F %T  ).

The format string may contain regular characters and special format specifiers. Format specifiers begin with a percent sign (%), and are expanded to their corresponding values. For a list of possible format specifiers, refer to the C++ strftime() documentation.

Some common format specifiers are:

.

Using History Expansion

Clink uses Readline's History library to add history expansion capabilities. If these are undesirable, they can be turned off by running clink set history.auto_expand off or clink set history.expand_mode off.

The History library provides a history expansion feature that is similar to the history expansion provided by csh. This section describes the syntax used to manipulate the history information.

History expansions introduce words from the history list into the input stream, making it easy to repeat commands, insert the arguments to a previous command into the current input line, or fix errors in previous commands quickly.

History expansion takes place in two parts. The first is to determine which line from the history list should be used during substitution. The second is to select portions of that line for inclusion into the current one. The line selected from the history is called the "event", and the portions of that line that are acted upon are called "words". Various "modifiers" are available to manipulate the selected words. The line is broken into words in the same fashion that Bash does, so that several words surrounded by quotes are considered one word. History expansions are introduced by the appearance of the history expansion character, which is !.

History expansion implements shell-like quoting conventions: a backslash can be used to remove the special handling for the next character; single quotes enclose verbatim sequences of characters, and can be used to inhibit history expansion; and characters enclosed within double quotes may be subject to history expansion, since backslash can escape the history expansion character, but single quotes may not, since they are not treated specially within double quotes.

.

Event Designators

An event designator is a reference to a command line entry in the history list. Unless the reference is absolute, events are relative to the current position in the history list.

.

Word Designators

Word designators are used to select desired words from the event. A : separates the event specification from the word designator. It may be omitted if the word designator begins with a ^, $, *, -, or %. Words are numbered from the beginning of the line, with the first word being denoted by 0 (zero). Words are inserted into the current line separated by single spaces.

For example,

Here are the word designators:

If a word designator is supplied without an event specification, the previous command is used as the event.

.

Modifiers

After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a :. These modify, or edit, the word or words selected from the history event.

.

Directory Shortcuts

Clink provides some typing savers for changing the current directory.

• Typing a directory name followed by a path separator is a shortcut for cd /d to that directory.
• Typing .. or ... is a shortcut for cd .. or cd ..\.. (each additional . adds another \..).
• Typing - or cd - changes to the previous current working directory.

These shortcuts only work in the interactive command line; they do not work in batch scripts.

.

Popular Scripts

Here are some popular scripts that show off what can be done with Clink.

.

clink-completions

The clink-completions collection of scripts has a bunch of argument matchers and completion generators for things like git, mercurial, npm, and more.

.

clink-flex-prompt

The clink-flex-prompt script is similar to the zsh powerlevel10k theme. It gives Clink a very customizable prompt, with many style options. It's extensible so you can add your own segments.

It also takes advantage of Clink's asynchronous prompt refresh to make prompts show up instantly, even in large git repos, for example.

.

clink-fzf

The clink-fzf script integrates the popular fzf "fuzzy finder" tool with Clink.

.

clink-gizmos

The clink-gizmos collection of scripts has several handy scripts such as:

• Argmatchers for msbuild, findstr, robocopy, xcopy, doskey, premake5, and more.
• Scripts to auto-generate argmatchers for commands by parsing their help text.
• Automatically show a divider line before + after certain commands, to make it easy to see where their output begins and ends, and the elapsed time taken by the command. This is especially handy when invoking compilers and build tools.
• The i.lua script to run a {command} in a {directory} and restore the original current directory afterwards. While typing the {command}, completions are even generated relative to the specified {directory} rather than the current directory.
• The fzf.lua script from clink-fzf for integrating the popular fzf "fuzzy finder" tool with Clink.
• The luaexec.lua script which has various features handy for Clink Lua script authors.
• And more.

.

oh-my-posh

The oh-my-posh program can generate fancy prompts. Refer to its documentation for how to configure it, and for sample themes.

Integrating oh-my-posh with Clink is easy: just save the following text to an oh-my-posh.lua file in your Clink scripts directory (run clink info to find that), and make sure the oh-my-posh.exe program is in a directory listed in the %PATH% environment variable (or edit the script below to provide a fully qualified path to the oh-my-posh.exe program). Replace the config with your own configuration and you're good to go.

-- oh-my-posh.lua
load(io.popen('oh-my-posh.exe --config="C:/Users/me/jandedobbeleer.omp.json" --init --shell cmd'):read("*a"))()

.

starship

The starship program can also generate fancy prompts. Refer to its documentation for how to configure it.

Integrating starship with Clink is just as easy: save the following text to a starship.lua file in your Clink scripts directory (run clink info to find that), and make sure the starship.exe program is in a directory listed in the %PATH% environment variable (or edit the script below to provide a fully qualified path to the starship.exe program). The config file for starship is located at C:\Users\<username>\.config\starship.toml.

-- starship.lua
load(io.popen('starship.exe init cmd'):read("*a"))()

.

z.lua

The z.lua tool is a faster way to navigate directories, and it integrates with Clink.

.

Terminal Support

Windows programs generally don't need to worry about terminal support. But the Readline library used by Clink comes from Unix, where there are many different kinds of terminals, and the library requires certain kinds of terminal support.

Clink's keyboard driver generally produces VT220 style key sequences, but it also includes many extensions from Xterm and other sources. Use clink echo to find key sequences for specific inputs.

Clink's terminal output driver is designed for use with Windows and its console subsystem. Clink can optionally handle output itself instead, and emulate terminal output support when the terminal.emulation setting is emulate, or when auto and Clink is running on an older version of Windows that doesn't support ANSI escape codes. In emulation mode, 8 bit and 24 bit color escape codes are mapped to the nearest 4 bit colors.

By default Clink sets the cursor style to a blinking horizontal partial-height block, or to a blink full-height solid block. Some terminals support escape codes to select alternative cursor styles. Clink provides environment variables where you may optionally provide escape codes to override the cursor style. %CLINK_TERM_VE% selects the style for the normal cursor (insert mode), %CLINK_TERM_VS% selects the style for the enhanced cursor (overwrite mode).

Special codes recognized in the cursor style escape code strings:

Refer to the documentation for individual terminal programs to find what (if any) escape codes they may support. The default console in Windows 10 supports the DECSCUSR escape codes for selecting cursor shape.

This .cmd script sets the normal cursor to a blinking vertical bar, and the enhanced cursor to a non-blinking solid box:

set CLINK_TERM_VE=\e[5 q
set CLINK_TERM_VS=\e[2 q

Or this .cmd script sets the normal cursor to blink, and the enhanced cursor to not blink:

set CLINK_TERM_VE=\e[?12h
set CLINK_TERM_VS=\e[?12l

.

Troubleshooting Tips

If something seems to malfunction, here are some things to try that often help track down what's going wrong:

• Check if anti-malware software blocked Clink from injecting.
  • Consider adding an exclusion for Clink.
  • The contents of the clink.log file often help in determining whether anti-malware software blocked Clink.
  • If it's indeed being blocked by anti-malware software, report the false positive to the publisher of the anti-malware software so they can confirm and update the detection signatures. There's nothing Clink can do about it.
• Check clink info. E.g. does the state dir look right, do the script paths look right, do the inputrc files look right?
• Check clink set. E.g. do the settings look right?
• Check the clink.log file for clues (its location is reported by clink info).

When reporting an issue, please include the following which saves time by answering in advance the usual questions:

• Please describe what was expected to happen.
• Please describe what actually happened.
• Please include the output from clink info and clink set.
• Please include the clink.log file (the location is reported by clink info).

.

Privacy

Clink does not collect user data. Clink writes diagnostic information to its local log file, and does not transmit the log file off the local computer. For the location of the log file, refer to File Locations or run clink info.

.

API groups

local my_parser = clink.argmatcher("make_color_shape")
:addarg("red", "green", "blue")             -- 1st argument is a color
:addarg("circle", "square", "triangle")     -- 2nd argument is a shape

local foo = clink.argmatcher("foo")
foo:addflags("-h", "--help", "--user")
foo:addarg("info", "set")
-- Example using first scheme and one table per description:
foo:adddescriptions(
    { "-h", "--help",   description = "Show help" },
    { "--user",         description = "Specify user name" },
    { "info",           description = "Prints information" },
    { "set",            description = "Show or change settings" },
)
-- Example using second scheme and just one table:
foo:adddescriptions( {
    ["-h"]              = "Show help",
    ["--help"]          = "Show help",
    ["--user"]          = { " name", "Specify user name" },
    ["info"]            = { "Prints information" },
    ["set"]             = { " var[=value]", "Show or change settings" },
} )

-- Helper function to add descriptions, when possible.
local function maybe_adddescriptions(matcher, ...)
    if matcher and matcher.adddescriptions then
        matcher:adddescriptions(...)
    end
end

-- This adds descriptions only if the Clink version being used
-- supports them, otherwise it does nothing.
maybe_adddescriptions(foo, {
    ["-h"] = "Show help",
    -- etc
})

local my_parser = clink.argmatcher("git")
:addarg({ "add", "status", "commit", "checkout" })
:addflags("-a", "-g", "-p", "--help")

clink.argmatcher("program"):addflags("/x", "/y")
clink.argmatcher("cmd"):addflags(
    "/c" .. clink.argmatcher():chaincommand(),
    "/k" .. clink.argmatcher():chaincommand()
):nofiles()
-- Consider the following input:
--    cmd /c program /
-- "cmd" is colored as an argmatcher.
-- "/c" is colored as a flag (by the "cmd" argmatcher).
-- "program" is colored as an argmatcher.
-- "/" generates completions "/x" and "/y".

clink.argmatcher("program"):addflags("-x", "-y")
clink.argmatcher("sometool"):addarg(
    "exec" .. clink.argmatcher()
                :addflags("-a", "-b")
                :addarg("profile1", "profile2")
                :chaincommand()
)
-- Consider the following input:
--    sometool exec profile1 program -
-- "sometool" is colored as an argmatcher.
-- "exec" is colored as an argument (for "sometool").
-- "profile1" is colored as an argument (for "exec").
-- "program" is colored as an argmatcher.
-- "-" generates completions "-x" and "-y".

local dirs = clink.argmatcher():addarg(clink.dirmatches)
local my_parser = clink.argmatcher("mycommand")
:addflags("-a", "--a", "--al", "--all",
          "-d"..dirs, "--d"..dirs, "--di"..dirs, "--dir"..dirs)
:hideflags("--a", "--al", "--all",      -- Only "-a" is displayed.
           "-d", "--d", "--di")         -- Only "--dir" is displayed.

clink.argmatcher("xyzzy")
:addarg("zero", "cero")     -- first arg can be zero or cero
:addarg("one", "uno")       -- second arg can be one or uno
:addarg("two", "dos")       -- third arg can be two or dos
:loop(2)    -- fourth arg loops back to position 2, for one or uno, and so on

local function make_flags()
    return { '-a', '-b', '-c' }
end

clink.argmatcher('some_command')
:addflags(make_flags)   -- Only a function is added, so flag prefix characters cannot be determined automatically.
:setflagprefix('-')     -- Force '-' to be considered as a flag prefix character.

{
    match           = "..."    -- [string] The match text.
    display         = "..."    -- [string] OPTIONAL; alternative text to display when listing possible completions.
    description     = "..."    -- [string] OPTIONAL; a description for the match.
    type            = "..."    -- [string] OPTIONAL; the match type.
    appendchar      = "..."    -- [string] OPTIONAL; character to append after the match.
    suppressappend  = t_or_f   -- [boolean] OPTIONAL; whether to suppress appending a character after the match.
}

builder:addmatch("hello") -- type is "none"
builder:addmatch("some_word", "word")
builder:addmatch("/flag", "arg")
builder:addmatch("abbrev", "alias")
builder:addmatch({ match="foo.cpp", type="file" })
builder:addmatch({ match="bar", type="dir" })
builder:addmatch({ match=".git", type="dir,hidden" })

builder:addmatches({"abc", "def"}) -- Adds two matches of type "none"
builder:addmatches({"abc", "def"}, "file") -- Adds two matches of type "file"
builder:addmatches({
    -- Same table scheme per entry here as in builder:addmatch()
    { match="remote/origin/master", type="word" },
    { match="remote/origin/topic", type="word" }
})

-- Make "cd" generate directory matches (no files).
clink.argmatcher("cd")
:addflags("/d")
:addarg({ clink.dirmatches })

-- Make "foo --file" generate file matches, but other flags and args don't.
-- And the third argument can be a file or $stdin or $stdout.
clink.argmatcher("foo")
:addflags(
    "--help",
    "--file"..clink.argmatcher():addarg({ clink.filematches })
)
:addarg({ "one", "won" })
:addarg({ "two", "too" })
:addarg({ clink.filematches, "$stdin", "$stdout" })