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.
• 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 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. More features can also be found in GNU's Readline.

Want some quick but powerful tips to get started?

Ctrl+O	This is operate-and-get-next, which accepts the current input line and gets the next history line. You can search history for a command, then press Ctrl+O to run that command and queue up the next command after it. Repeat it to conveniently rerun a series of commands from the history.
Alt+.	This is yank-last-arg, which inserts the last argument from the previous line. You can use it repeatedly to cycle backwards through the history, inserting the last argument from each line. Learn more by reading up on the "yank" features in the [Readline manual](https://tiswww.cwru.edu/php/chet/readline/rluserman.html).
Ctrl+R	This is reverse-search-history, which incrementally searches the history. Press it, then type, and it does a reverse incremental search while you type. Press Ctrl+R again (and again, etc) to search for other matches of the search text. Learn more by reading up on the "search" and "history" features in the [Readline manual](https://tiswww.cwru.edu/php/chet/readline/rluserman.html).
Ctrl+Alt+D	This is remove-history, which deletes the currently selected history line after using any of the history search or navigation commands.
Ctrl+Alt+K	This is add-history, which adds the current line to the history without executing it, and then clears the input line.
Ctrl+Alt+N	This is clink-menu-complete-numbers, which grabs numbers with 3 or more digits from the current console screen and cycles through inserting them as completions (binary, octal, decimal, hexadecimal). Super handy for quickly inserting a commit hash that was printed as output from a preceding command.
Alt+0 to Alt+9	These are digit-argument, which let you enter a numeric value used by many commands. For example Ctrl+Alt+W copies the current word to the clipboard, but if you first type Alt+2 followed by Ctrl+Alt+W then it copies the 3rd word to the clipboard (the first word is 0, the second is 1, etc). Learn more by reading up on "Readline Arguments" in the [Readline manual](https://tiswww.cwru.edu/php/chet/readline/rluserman.html).
Alt+H	This is clink-show-help, which lists the key bindings and commands. Learn more by visiting Key Bindings.

If you want a customizable prompt with a bunch of styles and an easy-to-use configuration wizard, check out clink-flex-prompt.

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.exe inject.

How Clink Works

When running Clink via the methods above, Clink checks the parent process is supported and injects a DLL into it. The DLL then hooks the WriteConsole() and ReadConsole() Windows functions. The former is so that Clink can capture the current prompt, and the latter hook allows Clink to provide its own Readline-powered command line editing.

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.

Configuring Clink

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 scripts, 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.

Clink Settings

The easiest way to configure Clink is to use Clink's set command line option. 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:

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 Key Bindings and Readline 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 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. The location of these files depends on which distribution of Clink was used. If you installed Clink using the .exe installer then 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.

Command Line Options

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, or 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

The Readline library used by Clink can be configured to add custom keybindings and macros by creating a Readline init file. There is excellent documentation for all the options and commands available to configure Readline in the Readline manual.

Init File

A Readline init file defines key binding customizations and sets Readline configuration variables.

A 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.

Basic Format

The .inputrc file will mostly use these kinds of lines:

See Discovering Clink key sequences for how to find the keyname for the key you want to bind. See Key Bindings for more information about binding keys in Clink.

Refer to the Readline manual for a more thorough explanation of the .inputrc file format, list of available commands, and list of configuration variables and their values.

New Configuration Variables

Clink adds some new configuration variables to Readline, beyond what's described in the Readline manual:

New Commands

Clink adds some new commands to Readline, beyond what's described in the Readline manual:

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 customise startup actions, create completion matches, customise 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.

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 customise various behaviors:
  • Generate completion matches.
  • Apply color to input text.
  • Customise 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).

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 it may in some rare 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

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 then registering the parser with Clink. When Clink detects the command is being entered on the current command line being edited, it uses the parser to generate matches.

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

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

This parser describes a command that has two positional arguments each with two potential options. It also has two flags which the parser considers to be position independent meaning that provided the word being completed starts with a certain prefix the parser with attempt to match the from the set of flags.

On the command line completion would look something like this:

C:>foobar hello -foo wo
wombles  wonder   world
C:>foobar hello -foo wo_

When displaying possible completions, flag matches are only shown if the flag character has been input (so command and Alt+= would list only non-flag matches, or command - 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.

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.

a_parser = clink.argmatcher():addarg({ "foo", "bar" })
b_parser = clink.argmatcher():addarg({ "abc", "123" })
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.

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.

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

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

The functions are passed four arguments, and should return a table of potential matches.

• 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).

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:

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 enabled, argmatcher automatically apply colors to the input text by parsing it.

It's possible for an argmatcher to provide a function to override how its arguments are colored. This function is called once for each of the argmatcher's arguments.

It's also possible to register a classifier function for the whole input line. This function is very similar to a match generator; classifier functions are called in priority order, and a classifier can choose to stop the classification process.

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

Customising the Prompt

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

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).

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() 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 customised 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 customised 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.

-- 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)

-- Customise 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

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

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

-- Customise 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

Miscellaneous

Key bindings

Key bindings are defined in .inputrc files. See the Configuring Readline section for more information.

Here is the quick version:

• A key binding is name: function or name: "literal text".
• Key names are like this:
  • C-a and "\C-a" are both Ctrl+a.
  • M-a and "\M-a" are both Alt+a.
  • M-C-a and "\M-\C-a" are both Alt+Ctrl+a.
  • hello is just h; the ello is a syntax error and is silently discarded by Readline.
  • "hello" is the series of keys h,e,l,l,o.
  • Special keys like Up are represented by VT220 escape codes such as"\e[A" (see Binding Special Keys for more info).
• Key bindings can be either functions or macros (literal text):
  • blah-blah binds to a function named "blah-blah".
  • "blah-blah" inserts the literal text "blah-blah".

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

Here is an example .inputrc file with key bindings that I use myself:

$if clink           # begin clink-only section

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

# Completion key bindings.
"\t":               old-menu-complete               # Tab
"\e[Z":             old-menu-complete-backward      # Shift+Tab
"\e[27;5;9~":       clink-popup-complete            # Ctrl+Tab
"\x1b[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[5;6~":          clink-popup-directories         # Ctrl+Shift+PgUp
C-_:                kill-line                       # Ctrl+- (replaces `undo`)

$endif              # end clink-only section

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.

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 print 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:

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

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.

The master history file

When the history.saved 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.

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.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.

Sample Scripts

Here are a few samples of 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.

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"))()

z.lua

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

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 Key Bindings for more information.
• Match coloring is now done by Readline and is configured differently; see Completion Colors for more information.
• Settings and history should migrate automatically if the new clink_settings and clink_history files don't exist (deleting them will cause migration to happen again). To find the directory that contains these files, run clink info and look for the "state" line.
• 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 settings have changed slightly, and there are many new settings. See Configuring Clink for more information.

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).

API groups

local my_parser = clink.argmatcher("git")
:addarg("add", "status", "commit", "checkout")

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")

local my_parser = clink.argmatcher("cd")
:addflags("/d|Also change current drive")
:addarg(clink.dirmatches):nofiles()

-- This helper function translates flag strings that include
-- descriptions, to make them compatible with older Clink versions.
local function maybe_flag_desc(...)
    if (clink.version_encoded or 0) < 10020038 then
        local recurse
        recurse = function(flags, index)
            local f = flags[index]:gsub("^(([^|]+)|.*)$", "%2")
            if index > #flags then return nil
            elseif index < #flags then return f, recurse(flags, index + 1)
            else return f
            end
        end
        return recurse({...}, 1)
    end
    return ...
end

-- An example of using the helper function:
local my_parser = clink.argmatcher("cd")
:addflags(maybe_flag_desc("/d|Also change current drive"))
:addarg(clink.dirmatches):nofiles()

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

{
    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.
}

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" })

local c = os.getalias("clink")
local r = io.popen(c.." --session "..clink.getsession().." history")

clink.lower("Hello World") -- returns "hello world"

local function my_filter(matches, popup)
    local new_matches = {}
    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 * prefix to directory matches.
            if m.type:find("^dir") then
                m.display = "*"..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

{
    {
        value       = "...",   -- Required; this is returned if the item is chosen.
        display     = "...",   -- Optional; displayed instead of value.
        description = "...",   -- Optional; displayed in a dimmed color in a second column.
    },
    ...
}

clink.print("\x1b[32mgreen\x1b[m \x1b[35mmagenta\x1b[m")
-- Outputs green in green, a space, and magenta in magenta.

local a = "hello"
local world = 73
clink.print("a", a, "world", world)
-- Outputs a       hello   world   73.

clink.print("hello", NONL)
clink.print("world")
-- Outputs helloworld.

local foo_prompt = clink.promptfilter(80)
function foo_prompt:filter(prompt)
    -- Insert the date at the beginning of the prompt.
    return os.date("%a %H:%M").." "..prompt
end

-- This example affects all match generators, by using priority -1 to
-- run first and returning false to let generators continue.
-- To instead affect only one generator, call clink.translateslashes()
-- in its :generate() function and return true.
local force_slashes = clink.generator(-1)
function force_slashes:generate()
    clink.translateslashes(2)  -- Convert to slashes.
    return false               -- Allow generators to continue.
end

clink.upper("Hello World") -- returns "HELLO WORLD"

local matches = console.screengrab(
        "[^%w]*(%w%w[%w]+)",   -- Words with 3 or more letters are candidates.
        "^%x+$")               -- A candidate containing only hexadecimal digits is a match.

local r,w = io.popenrw("fzf.exe --height 40%")

w:write("hello\n")
w:write("world\n")
w:close()

while (true) do
    local line = r:read("*line")
    if not line then
        break
    end
    print(line)
end
r:close()

local file = io.popenyield("git status")

while (true) do
    local line = file:read("*line")
    if not line then
        break
    end
    do_things_with(line)
end
file:close()

-- Given the following line; abc& 123
-- where commands are separated by & symbols.
line_state:getcommandoffset() == 4

-- Given the following line; >x abc
-- the first word is "x" and is an argument to the redirection symbol,
-- and the second word is "abc" and is the command word.
line_state:getcommandwordindex() == 2

line_state:getword(line_state:getwordcount()) == line_state:getendword()

local t = line_state:getwordinfo(word_index)
-- t.offset     [integer] Offset where the word starts in the line_state:getline() string.
-- t.length     [integer] Length of the word (includes embedded quotes).
-- t.quoted     [boolean] Indicates whether the word is quoted.
-- t.delim      [string] The delimiter character, or an empty string.
-- t.alias      [boolean | nil] true if the word is a doskey alias, otherwise nil.
-- t.redir      [boolean | nil] true if the word is a redirection arg, otherwise nil.

clink.debugprint("my variable = "..myvar)

local t = os.getbatterystatus()
-- t.level              [integer] The battery life from 0 to 100, or -1 if error or no battery.
-- t.acpower            [boolean] Whether the device is connected to AC power.
-- t.charging           [boolean] Whether the battery is charging.
-- t.batterysaver       [boolean] Whether Battery Saver mode is active.

local t = os.getenvnames()
-- t[index].name        [string] The environment variable's name.
-- t[index].value       [string] The environment variable's value.

local info = os.getscreeninfo()
-- info.bufwidth        [integer] Width of the screen buffer.
-- info.bufheight       [integer] Height of the screen buffer.
-- info.winwidth        [integer] Width of the visible window.
-- info.winheight       [integer] Height of the visible window.

local t = os.globfiles(pattern, extrainfo)
-- Included when extrainfo is true or >= 1:
--   t[index].name      -- [string] The directory name.
--   t[index].type      -- [string] The match type (see below).
-- Included when extrainfo is 2:
--   t[index].size      -- [number] The file size, in bytes.
--   t[index].atime     -- [number] The access time, compatible with os.time().
--   t[index].mtime     -- [number] The modified time, compatible with os.time().
--   t[index].ctime     -- [number] The creation time, compatible with os.time().

local t = os.globfiles(pattern, extrainfo)
-- Included when extrainfo is true or >= 1:
--   t[index].name      -- [string] The directory name.
--   t[index].type      -- [string] The match type (see below).
-- Included when extrainfo is 2:
--   t[index].size      -- [number] The file size, in bytes.
--   t[index].atime     -- [number] The access time, compatible with os.time().
--   t[index].mtime     -- [number] The modified time, compatible with os.time().
--   t[index].ctime     -- [number] The creation time, compatible with os.time().

path.getbasename("/foo/bar.ext")    -- returns "bar"
path.getbasename("")                -- returns ""
path.getbasename(nil)               -- returns nil

path.getdirectory("foo")                -- returns nil
path.getdirectory("\foo")               -- returns "\"
path.getdirectory("c:foo")              -- returns "c:"
path.getdirectory([[c:\]])              -- returns "c:\"
path.getdirectory("c:\foo")             -- returns "c:\"
path.getdirectory("c:\foo\bar")         -- returns "c:\foo"
path.getdirectory("\\foo\bar")          -- returns "\\foo\bar"
path.getdirectory("\\foo\bar\dir")      -- returns "\\foo\bar"
path.getdirectory("")                   -- returns nil
path.getdirectory(nil)                  -- returns nil

-- These split the path components differently than path.toparent().
path.getdirectory([[c:\foo\bar\]])      -- returns "c:\foo\bar"
path.getdirectory([[\\foo\bar\dir\]])   -- returns "\\foo\bar\dir"

path.getdrive("e:/foo/bar")     -- returns "e:"
path.getdrive("foo/bar")        -- returns nil
path.getdrive("")               -- returns nil
path.getdrive(nil)              -- returns nil

path.getextension("bar.ext")    -- returns ".ext"
path.getextension("bar")        -- returns ""
path.getextension("")           -- returns ""
path.getextension(nil)          -- returns nil

path.getname("/foo/bar.ext")    -- returns "bar.ext"
path.getname("")                -- returns ""
path.getname(nil)               -- returns nil

path.isexecext("program.exe")   -- returns true
path.isexecext("file.doc")      -- returns false
path.isexecext("")              -- returns false
path.isexecext(nil)             -- returns nil

path.join("/foo", "bar")    -- returns "/foo\bar"
path.join("", "bar")        -- returns "bar"
path.join("/foo", "")       -- returns "/foo"
path.join(nil, "bar")       -- returns nil
path.join("/foo", nil)      -- returns nil

path.normalise("a////b/\\/c/")  -- returns "a\b\c\"
path.normalise("")              -- returns ""
path.normalise(nil)             -- returns nil

local parent,child
parent,child = path.toparent("foo")             -- returns "", "foo"
parent,child = path.toparent("\foo")            -- returns "\", "foo"
parent,child = path.toparent("c:foo")           -- returns "c:", "foo"
parent,child = path.toparent([[c:\]])           -- returns "c:\", ""
parent,child = path.toparent("c:\foo")          -- returns "c:\", "foo"
parent,child = path.toparent("c:\foo\bar")      -- returns "c:\foo", "bar"
parent,child = path.toparent("\\foo\bar")       -- returns "\\foo\bar", ""
parent,child = path.toparent("\\foo\bar\dir")   -- returns "\\foo\bar", "dir"
parent,child = path.toparent("")                -- returns "", ""
parent,child = path.toparent(nil)               -- returns nil

-- These split the path components differently than path.getdirectory().
parent,child = path.toparent([[c:\foo\bar\]])   -- returns "c:\foo", "bar"
parent,child = path.toparent([[\\foo\bar\dir\]])-- returns "\\foo\bar", "dir"

rl.collapsetilde("C:\Users\yourusername\Documents")
 
-- The return value depends on the expand-tilde configuration variable:
-- When "on", the function returns "C:\Users\yourusername\Documents".
-- When "off", the function returns "~\Documents".
 
-- Or when force is true, the function returns "~\Documents".

local result, expanded = rl.expandtilde("~\Documents")
-- result is "C:\Users\yourusername\Documents"
-- expanded is true

-- This dir_matches function demonstrates efficient use of rl.expandtilde()
-- and rl.collapsetilde() to generate directory matches from the file system.
function dir_matches(match_word, word_index, line_state)
    -- Expand tilde before scanning file system.
    local word = line_state:getword(word_index)
    local expanded
    word, expanded = rl.expandtilde(word)

    -- Get the directory from 'word', and collapse tilde before generating
    -- matches.  Notice that collapsetilde() only needs to be called once!
    local root = path.getdirectory(word) or ""
    if expanded then
        root = rl.collapsetilde(root)
    end

    local matches = {}
    for _, d in ipairs(os.globdirs(word.."*", true)) do
        -- Join the filename with the input directory (might have a tilde).
        local dir = path.join(root, d.name)
        table.insert(matches, { match = dir, type = d.type })
    end
    return matches
end

local b,t = rl.getbinding([["\e[H"]], "emacs")
if b then
    print("Home is bound to "..b.." ("..t..") in emacs mode.")
else
    print("Home is not bound in emacs mode.")
end

local t = rl.getkeybindings()
-- t[index].key         [string] Key name.
-- t[index].binding     [string] Command or macro bound to the key.
-- t[index].desc        [string] Description of the command.
-- t[index].category    [string] Category of the command.

function luafunc_showkeybindings(rl_buffer)
    local bindings = rl.getkeybindings()
    if #bindings <= 0 then
        rl_buffer:refreshline()
        return
    end

    local items = {}
    for _,kb in ipairs(bindings) do
        table.insert(items, {
            value = kb.binding,     -- Return the binding when selected, so it can be invoked.
            display = kb.key,       -- Display the key name.
            description = kb.binding.."\t"..kb.desc -- Also display the command and description.
        })
    end

    -- Show a popup that lists the items from above.
    local binding, _, index = clink.popuplist("Key Bindings", items)
    rl_buffer:refreshline()
    if binding then
        -- Invoke the selected binding (a command or macro).
        rl.invokecommand(binding)
    end
end

local last_rl_func, last_lua_func = rl.getlastcommand()

local info = rl.getpromptinfo()
-- info.promptprefix              [string] The prompt string, minus the last line of the prompt string.
-- info.promptprefixlinecount     [integer] Number of lines in the promptprefix string.
-- info.prompt                    [string] The last line of the prompt string.
-- info.rprompt                   [string or nil] The right side prompt (or nil if none).
-- info.promptline                [integer] Console line on which the prompt starts.
-- info.inputline                 [integer] Console line on which the input text starts.
-- info.inputlinecount            [integer] Number of lines in the input text.

local old_space = rl.getbinding('" "')
function hijack_space(rl_buffer)
    rl.invokecommand("clink-expand-line")   -- Expand envvars, etc in the line.
    rl.invokecommand(old_space)             -- Then invoke whatever was previously bound to Space.
end
rl.setbinding([[" "]], [["luafunc:hijack_space"]])

-- The [[]] string syntax lets you copy key strings directly from 'clink echo'.
-- [["\e[H"]] is much easier than translating to "\"\\e[H\"", for example.
rl.setbinding([["\e[H"]], [[beginning-of-line]])

local matches = {}
matches["nosort"] = true
rl.setmatches(matches)

M-n:            "luafunc:completenumbers"       # Alt+N

function completenumbers()
    local _,last_luafunc = rl.getlastcommand()
    if last_luafunc ~= "completenumbers" then
        -- Collect numbers from the screen (minimum of three digits).
        -- The numbers can be any base up to hexadecimal (decimal, octal, etc).
        local matches = console.screengrab("[^%w]*(%w%w[%w]+)", "^%x+$")
        -- They're already sorted by distance from the input line.
        matches["nosort"] = true
        rl.setmatches(matches)
    end

    rl.invokecommand("old-menu-complete")
end

settings.add("myscript.myabc", true, "Boolean setting")
settings.add("myscript.mydef", 100, "Number setting")
settings.add("myscript.myghi", "abc", "String setting")
settings.add("myscript.myjkl", {"x","y","z"}, "Enum setting")
settings.add("color.mymno", "bright magenta", "Color setting")

string.matchlen("abx", "a")         -- returns 1
string.matchlen("abx", "aby")       -- returns 2
string.matchlen("abx", "abx")       -- returns -1

-- Deprecated form:
local parser = clink.arg.new_parser(
  { "abc", "def" },       -- arg position 1
  { "ghi", "jkl" },       -- arg position 2
  "--flag1", "--flag2"    -- flags
)

-- Replace with form:
local parser = clink.argmatcher()
:addarg("abc", "def")               -- arg position 1
:addarg("ghi", "jkl")               -- arg position 2
:addflags("--flag1", "--flag2")     -- flags

-- Deprecated form:
local parser1 = clink.arg.new_parser("abc", "def")
local parser2 = clink.arg.new_parser("ghi", "jkl")
clink.arg.register_parser("foo", parser1)
clink.arg.register_parser("foo", parser2)

-- Replace with new form:
clink.argmatcher("foo"):addarg(parser1, parser2)

-- Warning:  Note that the following are NOT the same as above!
-- This replaces parser1 with parser2:
clink.argmatcher("foo"):addarg(parser1)
clink.argmatcher("foo"):addarg(parser2)
-- This uses only parser2 if/when parser1 finishes parsing args:
clink.argmatcher("foo"):addarg(parser1):addarg(parser2)

clink.match_display_filter = function(matches)
  -- Transform matches.
  return matches
end

-- Deprecated form:
function foo_prompt()
  clink.prompt.value = "FOO "..clink.prompt.value.." >>"
  --return true  -- Returning true stops further filtering.
end
clink.prompt.register_filter(foo_prompt, 10)

-- Replace with new form:
local foo_prompt = clink.promptfilter(10)
function foo_prompt:filter(prompt)
  return "FOO "..prompt.." >>" --,false  -- Adding ,false stops further filtering.
end

-- Deprecated form:
local function match_generator_func(text, first, last)
  -- `text` is the word text.
  -- `first` is the index of the beginning of the end word.
  -- `last` is the index of the end of the end word.
  -- `clink.add_match()` is used to add matches.
  -- return true if handled, or false to let another generator try.
end
clink.register_match_generator(match_generator_func, 10)

-- Replace with new form:
local g = clink.generator(10)
function g:generate(line_state, match_builder)
  -- `line_state` is a line_state object.
  -- `match_builder:addmatch()` is used to add matches.
  -- return true if handled, or false to let another generator try.
end

Changes

Releases from chrisant996/clink fork

v1.2.46

• Added a magic-space command that performs history expansion on the text before the cursor point and then inserts a space. Note: this is slightly different than one in bash, which performs history expansion on the whole line and can end up inserting the space in a wrong spot.
• Added rl.getbinding() and rl.setbinding() functions to query or override key bindings.
• Added a clink.refilterprompt() function to invoke prompt filtering on demand.
• The clink-popup-directories command is now bound by default to Ctrl+Alt+PgUp.
• The clink-select-complete command is now bound by default to Ctrl+Space.
• Fixed the clink-popup-history command so incremental search works again (regression introduced in v1.2.36).
• Fixed messages sometimes not being erased when finished, e.g. when using Alt+digits (regression introduced in v1.1.11).
• Fixed potential for prompt to redraw incorrectly after showing help when the prompt.transient setting is enabled.
• Fixed settings defined by Lua scripts so that the Lua scripts can reliably see the current values even while the Lua scripts are being loaded or reloaded.

v1.2.45

• Clarified description of the match.wild Clink setting.
• Fixed #196; installer checkboxes not working properly.

v1.2.44

• Fixed clink.ondisplaymatches() so it receives the right match strings (regression introduced in v1.2.39).
• Fixed #194; argmatcher not found when command name contains a dash (regression introduced in v1.1.5).
• Fixed #176; use current installation dir when upgrading clink. Now the installer remembers the chosen installation directory and defaults to the same place when installing an upgrade (all of the checkbox states are remembered, in fact).
• Fixed #171; have a way to override install directory. Now the installer has a checkbox whether to install to a versioned directory (recommended). Unchecking the box installs program files to a bin subdirectory, instead of the usual versioned subdirectory.

v1.2.43

• Fixed lingering issues with non-ASCII characters in path names in Clink (follows up on the preceding fixes for non-ASCII user name characters).

v1.2.42

• Fixed potential for history file to get corrupted during compacting, if multiple Clink instances are running concurrently.
• Fixed clink inject when the user account name contains non-ASCII characters (regression introduced in v1.0.0).
• Fixed #193; consider removing the 50K history limit: The history.max_lines Clink setting once again supports 0 to mean unlimited. Note that as the history file grows larger, it takes longer to load. If the size becomes a problem, you can use clink history compact <n> to prune the history file to N items as well as compacting it (removing deleted items).
• Fixed #192; completing ~ by itself does nothing: Completing ~ by itself now inserts the %USERPROFILE% directory. This is different than bash, because on Windows it doesn't make sense for ~ by itself to complete other user accounts. This is a convenient way to expand tilde into a path that Windows understands.
• Fixed #191; cd /d - isn't supported: The cd - feature now supports cd /d - as well. It also supports cd - even if there is a doskey macro defined for cd.

v1.2.41

• Fixed #187 differently: doskey.enhanced is true by default again, but if a macro contains $* or $1...$9 tags within quotes then | and & symbols are part of the arguments, not command separators (and expansion stops after that macro).
• Fixed compatibility when doskey.enhanced is false; alias|whatever should not expand alias because there is no space after it.
• Fixed doskey expansion when >& redirection symbol is present; command >& alias should not attempt to expand alias because it's a redirection file name, not a command.

v1.2.40

• Fixed display quirks when an empty display or description string is provided by a match generator.
• Fixed #187; the doskey.enhanced setting interferes with some macros (regression introduced in v1.0.0). The setting is now false by default, because of the incompatibilities it can cause.

v1.2.39

• Fixed regression in match display filtering when listing possible completions (regression introduced in v1.2.38).
• Fixed display quirks in the clink-select-complete command when descriptions are at the bottom.

v1.2.38

• Enhancements for match descriptions (which are displayed when listing possible completions):
  • Argmatchers can provide description strings for flags and/or args (e.g. "Verbose output" for -v, or "Do nothing" for -n, etc).
  • Argmatchers can also provide argument info strings for flags and/or args. These are hint strings, and not part of the completion match itself. E.g. "linenum" for --line, which gets displayed as "--line linenum" when listing possible completions, but only "--line" is inserted.
  • Match generators can provide display and description strings when adding matches (match_builder:addmatch() and match_builder:addmatches()) -- it is no longer necessary to use clink.ondisplaymatches().
  • The clink-select-complete command now shows match descriptions in a single line at the bottom (instead of in a second column) when there are more than 9 matches.
  • Added color.arginfo Clink setting for the arguments for a flag or argument when listing possible completions.
  • Added color.description Clink setting for the default match description color when listing possible completions.
  • Truncate descriptions when a line will wrap (or has wrapped) when listing possible completions.
• Command separators (&, |) and redirection symbols (<, >, >&) are colored in the input line, using colors from the new color.cmdsep and color.cmdredir Clink settings.
• Fixed Backspace in clink-select-complete; it had sometimes missed expanding the set of matches accordingly.
• Fixed the clink-popup-history command to respect the search-ignore-case setting.
• Fixed :nofiles() to dead-end an argmatcher (regression introduced in v1.0.0).
• Fixed clink.ondisplaymatches() and clink.onfiltermatches() when there's only 1 match.
• Fixed incremental find, find next, and find previous in console text popup lists.
• Fixed backward compatibility for the old matching filtering API.
• Fixed several other minor issues with match display filtering.
• Fixed intermittent incorrect match generation for /flag: or /flag= flags.
• Fixed duplicate removal with deprecated match generators.
• Fixed when nested deprecated argmatchers are exhausted (regression introduced in v1.2.36).
• Fixed deprecated match generators to not infer whether matches are filenames, to match the behavior of the v0.4.9 API.
• Fixed how match.wild works with deprecated match generators; e.g. arg completions for z.lua weren't working (regression introduced in v1.1.5).
• Fixed argmatcher for clink --profile so it produces directory matches.
• Fixed %CLINK_RPROMPT% alignment when color.prompt is set.

v1.2.37

• Fixed #180; rl.collapsetilde() behaves erratically.
• Fixed #179; incorrect handling for certain keys on some keyboard layouts.
• Fixed #178; OneDrive folders mistakenly show up as symlinks.
• Fixed #177; be silent about autorun injection into TCC.

v1.2.36

• Added win-history-list command bound to F7 by default. This shows the history list, and executes the selected history entry.
• Changed all of the popup list commands to show popups using console text rather than GUI windows.
  • Added a color.popup Clink setting for the popup colors. If not set, the console's popup colors are used.
  • Added a color.popup_desc Clink setting for the popup colors for the description column(s). If not set, a color is chosen to complement the console's popup colors.
  • Added a clink.gui_popups Clink setting that can be set to use GUI popup windows as before (the color.popup settings have no effect on GUI popup windows).
• Key bindings now support Enter plus combinations of the Ctrl, Shift, or Alt modifier keys.
• Added more backward compatibility shims.
• Fixed the clink-select-complete command when print-completions-horizontally is on (and also minor issues when it is off).
• Fixed the clink-select-complete command when a Lua script has used rl.setmatches() to provide a custom list of matches.
• Fixed the clink-menu-complete-numbers family of commands (regression introduced in v1.2.32).
• Fixed a situation where the scrolling keys could stop working (regression introduced in v1.2.24).
• Fixed flags at the end of a linked parser, and fixed args at the end of two or more nested linked parsers (regression introduced in v1.0.0).
• Fixed #172; add a choice in the installer to not add Start menu shortcuts.
• Fixed #129; Bug completing files with - or _ characters (regression introduced in v1.0.0).

v1.2.35

• Added rl_buffer:getanchor() to get the text selection anchor (there is no set function; use rl.invokecommand() to invoke commands to set/extend the selection if needed).
• Reverted back to using IAT hooking (see issue #169).
• Fixed CUA selection commands invoked by rl.invokecommand().
• Fixed #170; directory symlink completion is truncated when mark-directories is off in the .inputrc file.
• Fixed #169; incompatibility between AutoHotkey, AnsiCon, and Clink when all three are used in CMD's AutoRun regkey (regression introduced in v1.2.33).

v1.2.34

• Changed "luafunc:" macro functions to receive the line_state as a second argument.
• Fixed Right when clink.default_bindings is windows.
• Fixed exec.files setting so completion works when a path is specified (e.g. subdir\foo) (regression introduced in v1.2.33).
• Fixed #158; crash when a keyboard macro contains \015 (regression introduced in v1.0.0).

v1.2.33

• Rewrote how Clink hooks APIs in CMD.EXE; it no longer uses any IAT hooking, and exclusively uses Detours.
• Added clink.default_bindings Clink setting to choose between bash or windows default key bindings. bash key bindings are still the default, for compatibility with existing Clink installations.
• Added exec.aliases, exec.commands, and exec.files Clink settings to further customize how matches are generated for the first word when the exec.enable Clink setting is enabled.
• Small performance optimization in the hooked WriteConsoleW() system API.
• Added logging for rare error case during inject.
• Added default key bindings for F1 through F9 that mimic the default Windows console function key inputs.
• Added clink-selectall-conhost command that mimics the default Windows console Select All command.
• Fixed clink-select-complete to remove duplicate matches if generators try to add duplicate matches.
• Fixed script error when %PATH% is not set and exec.enable and exec.path are both enabled.
• Fixed some quirks when using the quoted-insert command.

v1.2.32

• Added rl_buffer:setargument() function for a "luafunc:" macro to be able to set Readline's numeric argument.
• Added os.getclipboardtext() and os.setclipboardtext() functions.
• Added extra defense against antivirus interference (if it interferes when Clink inspects the target process, but permits Clink to inject into the target process).
• Fixed cooperation between "luafunc:" macros and CUA selection commands (e.g. Shift+End).
• Fixed rl_buffer:getcursor() and the return value from rl_buffer:setcursor(); both returned one less than the actual cursor position.
• Fixed #162; clink completion shows script error (regression introduced in v1.2.31).

v1.2.31

• Added clink uninstallscripts --all to clear all script paths installed by clink installscripts.
• Added os.touch() function to set the access and modified times for a file.
• Added more fields in os.globdir() and os.globfiles() when extrainfo is requested.
• Potential Breaking Change: Fixed os.globdir() and os.globfiles() to only return extra info when actually requested (regression introduced in v1.1.8).
  • This unfortunately changes the scheme and may break some scripts if they requested no extra info, but used the extra info anyway.
• Fixed crash in clink-select-complete when a match display filter returns nil.
• Fixed ondisplaymatches() which was receiving one fewer matches than it should (related to #124).
• Fixed ondisplaymatches() which was not using the word break info correctly (from generators' :getwordbreakinfo() functions).
• Fixed word_classifications:applycolor(); the input line didn't necessarily refresh correctly after a custom classifier applied custom colors.
• Fixed potential stray inaccurate colorations when coloring the input for clink set color.something some_value.
• Fixed #161; clink installscripts garbles previously-installed script paths when installing a new one.
• Fixed #155; settings.set() doesn't update the settings file.

v1.2.30

• Replaced the built-in Lua implementation of os.clock() so it doesn't stop working after the program has been running for more than 24 days (which caused asynchronous prompt filtering to stop working). As a side effect, the new os.clock() has microsecond precision instead of millisecond precision.
• Fixed coroutine throttling. It was meant to prevent running more than once per 5 seconds, but accidentally forced running every 5 seconds, even if the coroutine was registered to run less often.

v1.2.29

• Added prompt.transient Clink setting which can collapse prior prompts to a condensed form. The new %CLINK_TRANSIENT_PROMPT% and %CLINK_TRANSIENT_RPROMPT% environment variables supply the initial prompt strings, and prompt filters can define :transientfilter() and :transientrightfilter() functions to filter the transient prompt.
• Added clink.logo Clink setting to globally control what startup logo is shown (full copyright logo by default, or a short version logo, or no startup logo).
• Added console.readinput() function which waits for one key input, and returns the key sequence string for the key.
• Added clink.reload() function which reloads Lua scripts and the Readline config file at the next prompt.
• Added logging for more possible failure points while injecting Clink into the host process.
• Added default key bindings for Ctrl+Up and Ctrl+Down to scroll the screen one line, like conhost normally does.
• Now clink set cl* lists all settings that begin with cl (the star wildcard is only supported at the end of the string).
• Documentation includes a link to the new clink-flex-prompt.
• Fixed the Lua debugger to support printing UTF8 text, and to escape string variable contents to avoid escape code side effects.
• Fixed #154; crash when `settings.set("some_setting", false) is used.
• Fixed #153; ESC key problem. Clink migrated the old esc_clears_line setting backwards, causing Esc to behave opposite from what was expected.
• Fixed #152; LUA debugger breaks on the wrong line, and fails to execute expressions.

v1.2.28

• Added rl.getpromptinfo() function.
• Fixed loading .inputrc so that only one is loaded (regression introduced in v1.0.0a0 by the fix for mridgers #258). If similar behavior is still desired, consider using the $include directive in the Readline init file, to load additional files.
• Fixed clink-select-complete to respect when mark-directories in .inputrc file is off.
• Fixed crash in console.findline() when no attributes are passed. Callers using v1.2.27 and earlier can work around the crash by passing {} for attributes.
• Fixed an off-by-1 bug in console.scroll("absolute", top). This will fix edge case malfunctions in some callers, but some callers could experience this as a breaking change.

v1.2.27

• The cmd.get_errorlevel Clink setting is now enabled by default.
• Clink now expands $ codes in %CLINK_RPROMPT% before running prompt filters.
• Fixed parsing 2>&1 style redirection symbols, so the & doesn't get treated as a command separator.
• Fixed argmatchers to generate file matches for redirection arguments; app.exe > should generate file matches for the > symbol, not matches for the app argmatcher's first argument.

v1.2.26

• Fixed input line coloring for doskey aliases that don't have an argmatcher (regression introduced in v1.2.16).
• Fixed Space during clink-select-complete when there were already opening and closing quotes present.
• Fixed redrawing multiple lines of input after certain commands such as clink-show-help Alt+H (regression introduced in v1.1.20).
• Fixed the completion-auto-query-items config variable to account for multiple lines of input, if present.
• Fixed potential race condition if multiple Clink instances try to get the last errorlevel at the same time.

v1.2.25

• Added cua-select-all command to select the entire input line.
• Added edit-and-execute-command command to invoke an editor on the current input line and then execute the results (Ctrl+X,Ctrl+E). This attempts to invoke %VISUAL%, %EDITOR%, or notepad.exe as the editor, in that order.
• Added some new expansion commands:
  • clink-expand-history performs history expansion on the current input line (Alt+^).
  • clink-expand-history-and-alias performs history and doskey alias expansion on the current input line.
  • clink-expand-line performs history, doskey alias, and environment variable expansion on the current input line (Ctrl+Alt+E).
• Added some new completion commands:
  • glob-complete-word performs wildcard completion on the text before the cursor point, with a * implicitly appended (Alt+G).
  • glob-expand-word inserts all the wildcard completions that glob-list-expansions would list (Ctrl+X,*).
  • glob-list-expansions lists the possible wildcard completions of the text before the cursor point (Ctrl+X,g).
• Added some command name synonyms for increased .inputrc file portability with bash:
  • alias-expand-line is a synonym for clink-expand-doskey-alias.
  • history-expand-line is a synonym for clink-expand-history.
  • history-and-alias-expand-line is a synonym for clink-expand-history-and-alias.
  • insert-last-argument is a synonym for yank-last-arg.
  • shell-expand-line is a synonym for clink-expand-line.
• Added a match.expand_envvars Clink setting to expand environment variables in a word before performing completion (for mridgers #476).
• Changed the match.wild Clink setting to apply to all completion commands.
• Changed default key binding Ctrl+Alt+E to the clink-expand-line command (not the key binding expands everything, instead of only the env var at the cursor).
• Removed default key binding Alt+Shift+H for the clink-show-help-raw command (it has only niche usefulness).
• Removed unintended VI mode key binding Alt+Ctrl+H.
• Fixed Ctrl+Shift+2 and Ctrl+Shift+6 (regression introduced in v1.1.39).
• Fixed More? continuation prompt when pasting multiple lines.
• Fixed /flag: and /flag= handling quirks, especially when trying to complete an environment variable in /flag:%env.
• Fixed quirks about environment variable expansion in the clink-expand-env-var command and the os.expandenv() function.

v1.2.24

• Added support for %CLINK_RPROMPT% to show a right side prompt, and for prompt filters to define a :rightfilter() function to filter the right side prompt.
• Fixed clink-select-complete to not append a space after a flag that ends with : or = (e.g. /x:).

v1.2.23

• Fixed PgUp and PgDn in the clink-select-complete command, under certain conditions where they don't navigate in the intended manner.
• Cosmetic change: better key names for Enter vs Ctrl+M, and Alt+Bkspc vs Alt+Ctrl+H, depending on the terminal.differentiate_keys setting.

v1.2.22

• Added clink-what-is command bound by default to Alt+?, which shows the key binding for the next key sequence that is input.
• Added rl.getargument() function to get the accumulated Readline numeric argument, if any. For use in "luafunc:" macros.
• The clink-show-help command now categorizes key bindings and shows a description for the commands. Using a numeric argument can control whether categorization and descriptions are used.
• Fixed invoking clink-select-complete while it is already active, so that it doesn't lose quotes around the current match if it has quotes.
• Fixed clink-show-help to list "Enter" instead of "C-m" for the Enter key. Otherwise there's no way to differentiate between Enter and Ctrl+M when the terminal.differentiate_keys setting is enabled.
• Fixed the insert-comment command, which accidentally fell back to inserting # after the first prompt (that's what bash inserts, and shouldn't be used in Clink).
• Fixed the dump-functions command, which accidentally didn't list UTF8 key sequences correctly.

v1.2.21

• Fixed backwards exit codes from clink autorun commands.
• Fixed alert message text on startup when debug.log_terminal is set to true.
• Fixed #143; crash on start when terminal.raw_esc is true (regression introduced in v1.2.19).

v1.2.20

• Added os.debugprint() function to print debug text via the OS OutputDebugString() API.
• Enabled match completion coloring even when using match display filtering.
• Fixed input of slash and backslash in non-directory completions when using the clink-select-complete command.
• Fixed match display filtering in the clink-select-complete command.
• Fixed match display filtering in the clink-popup-complete command.
• Fixed quirk from Readline where it sometimes displays one fewer columns of matches than actually fit on the screen.

v1.2.19

• Added clink-select-complete command which shows an interactive list of possible completions.
• Added terminal emulation for CGI G, CSI s, and CSI u sequences.
• Fixed column alignment for match display filtering when some characters take more than one cell to display.

v1.2.18

• Added completions for clink installscripts and clink uninstallscripts.
• Added support for Readline's coloring and marking of symlinks.
• Fixed clink installscripts --help.
• Fixed clink-popup-directories for directories with spaces.

v1.2.17

• Added clink-popup-show-help command to show popup list with searchable list of key bindings and invoke the selected key binding.
• Added clink.popuplist() function to show a popup list. Only usable from inside a "luafunc:" key binding.
• Incremental search in the popup list window now centers the found item so items above and below it are visible.
• Fixed potential internal error when a doskey alias starts with $ (regression introduced in v1.2.16).
• Fixed potential infinite loop when the cmd.auto_answer setting is enabled but an error occurs while retrieving a language string (might be related to #137).

v1.2.16

• Breaking Change: The clink.onendedit() Lua event has been split into two separate events:
  • clink.onendedit() registers a function to be called when the edit prompt ends.
  • clink.onfilterinput() registers a function to be called after the edit prompt ends (and after the onendedit event is sent), and the function can replace the input text.
• Added rl.getkeybindings() function to get a table containing key bindings. The bindings can be invoked via rl.invokecommand(). For example, a "luafunc:" macro could use this to get key bindings, show an interactive list, and then invoke the selected key binding.
• Fixed #134; print() can stop working. Issue #93 can potentially happen any time redirection is used, so the fix must be applied repeatedly (not just after Clink injection).
• Fixed #119; reuse registered parsers for doskey macros.

v1.2.15

• Fixed #132; multiline prompt gets overwritten when resizing the terminal width (regression introduced in v1.2.14).

v1.2.14

• Automatically runs clink_start.cmd from the binaries directory and/or the profile directory when Clink is injected.
• Clink is able to retrieve the last exit code for use by Lua scripts.
  • The new cmd.get_errorlevel setting is off by default, but when enabled it retrieves the last exit code from CMD before running Lua scripts.
  • The new os.geterrorlevel() function gets the last exit code (or 0 if the setting is off).
  • It works by running a hidden command line between each interactive prompt (as if you typed echo %errorlevel% yourself every second command you type). If you experience problems with this, turn it off.
• Improved refreshing the input line when resizing the terminal window. It's better than before, but there's no way to make it work perfectly because Windows can resize the terminal further while a program is already trying to respond to the terminal having been resized previously.
• Fixed #130; doskey alias completions stop working when there are many aliases.

v1.2.13

• Added support for linking a parser to flags ending with : or =; now completion works for the flag's argument.

v1.2.12

• Improved diagnostic output for coroutines (Ctrl-X,Ctrl+Z), plus more diagnostic info when the lua.debug setting is enabled.
• Fixed potential for a script error when a coroutine gets skipped due to a new prompt starting.

v1.2.11

• Added clink.print() function which behaves like print() but with support for ANSI escape codes (and terminal emulation), and also a NONL special argument that suppresses the usual newline at the end of the output.
• Expanded the sample code for async prompt filtering to clarify some things.
• Fixed #126; allow Esc to input literal escape character.
  • The new terminal.raw_esc setting controls how Esc input works.
  • Added migration for the old esc_clears_line setting.

v1.2.10

• Added asynchronous prompt filtering -- scripts can use this to do work in the background (e.g. git status) and refresh the prompt when finished.
  • Added clink.promptcoroutine() function to allow a prompt filter to do some work in the background.
  • Added io.popenyield() function to allow a coroutine to yield until the command's complete output is ready.
  • Added prompt.async setting that can disable asynchronous prompt filtering if preferred.
• Log error codes for failures during clink inject.
• Clarified help text for clink autorun (per #122).
• Documentation clarifications and reorganization.
• Fixed clink and history aliases getting lost after exiting a nested Clink instance.
• Fixed some input keys accidentally handled by the OS after certain Lua code is run.
• Fixed #124; onfiltermatches() receives one fewer matches than it should.
• Fixed #123; Failed to inject (Host validation failed).
• Fixed #117; Setup causes "System Error".

v1.2.9

• Added detection for possible antivirus interference when injecting Clink.
• Ignore duplicate scripts paths when loading scripts.
• Fixed #118; inputrc is not read from state directory (regression introduced in v1.0.0).

v1.2.8

• Fixed ...\ or .../ to change directories (path separator after several dots).
• Fixed /dirname/ to change directories (forward slashes when a directory is the only thing in the input line).
• Fixed #114; "Clink already loaded in process" error when autorun is installed for both Current User and All Users.
• Fixed #113; forward slash translation didn't work with the cd command.

v1.2.7

• Fixed #113; clink.slash_translation() had been removed (regression introduced in v1.0.0).
  • The new match.translate_slashes setting controls the default behavior for slash translation for completion matches.
  • The new clink.translateslashes() API can override slash translation for completion matches (and clink.slash_translation() is supported for backward compatibility).

v1.2.6

• Fixed tilde expansion for directory by itself; now ~\ can change the working directory to the ~ directory.
• Fixed pagination when displaying completions that take more than 1 line to display.
• Fixed inserting directory match completions when a Lua script didn't include a trailing path separator in the directory match.
• Fixed #111; .. completion is different from bash (regression introduced in v1.0.0).

v1.2.5

• Added os.expandenv() function to expand environment variables in a string.
• Added console.cellcount() function to count the cells a string will use when displayed.
• Added console.plaintext() function to remove ANSI escape codes from a string.
• Clink now sets %=clink.bin% that points to the Clink binaries directory. This can be particularly useful for a portable installation of Clink so that scripts can find the Clink binaries directory and construct relative paths to other nearby files.
• Clean up column alignment in --help texts.
• Fixed history.sticky_search with anchored history search.
• Fixed clink inject --profile to use correct log file name while initially injecting.
• Fixed Clink autorun to be more compatible with Cmder (Cmder #2536).

v1.2.4

• Added support for Shift+Arrows to select text and typing to replace selected text.
• Added optional argument to word_classifications:classifyword() and word_classifications:applycolor() to allow only applying color where another color hasn't yet been applied.
• Fixed first Up after reusing a history line so that it gets the reused history line, rather than getting the previous history line.
• Fixed add-history command to not add blank lines to history.
• Fixed rl.setmatches() (regression introduced in v1.1.26).
• Fixed input coloring for clink set and any color setting name (regression introduced in v1.2).
• Fixed potential crash with clink history --session.
• Fixed Ctrl+D when cmd.ctrld_exits is disabled; it didn't exit, but it did still discard the input line and start a new prompt.
• Fixed #107; autorun reports inject failures (regression introduced in v1.2.3).
• Fixed #106; history missing --bare option (regression introduced in v1.2.3).

v1.2.3

• Added history.sticky_search setting: when enabled, reusing a history line does not add the reused line to the end of the history, and it leaves the history search position on the reused line so next/prev history can continue from there (e.g. replaying commands via Up several times then Enter, Down, Enter, etc).
• Added failure reporting and logging when clink inject fails.
• Added --unique flag for use with clink history compact --unique to remove duplicate entries from the history list.
• The clink-popup-complete command now matches wildcards.
• Restored the Ctrl+Alt+U key binding from v0.4.9 (moves the current working directory up one level).
• Fixed searching for inputrc files to also search in the profile directory (regression introduced in v1.0.0).
• Fixed incremental search in the History popup list to search in reverse order (bottom to top).
• Fixed clink-popup-history to set the history search position like other history search commands do, so that it plays well with the history.sticky_search setting.

v1.2.2

• Added %CLINK_HISTORY_LABEL% environment variable to use a different master history file (fixes #99).

v1.2.1

• Added Troubleshooting Tips section in the documentation.
• Added backward compatibility for clink set with v0.4.9. Old setting names and values are not documented, but are automatically mapped to the appropriate new setting(s). This was done so that suggestions in old web sites and posts can usually continue to work, to reduce confusion and support burden.
• Fixed #97; VS2017 error C2039: 'min': is not a member of 'std'.
• Fixed #96; wrong setting string (the name of a setting was accidentally truncated).
• Fixed some slightly inaccurate/incomplete migration from old settings to new settings.

v1.2

• First official release from chrisant996/clink fork.

v1.1.49

• Added clink.classifier() to enable coloring the input line independently from argmatchers.
• Added word_classifications:applycolor() to apply SGR escape codes anywhere in the input line.
• Removed word_classifications:iswordclassified().
• Fixed the Product Version string in the binary file version resources.

v1.1.48

• Added clink.getansihost() function to get Clink's best guess who will process ANSI escape codes (can be useful for avoiding 256 bit and 24 bit color codes, for example).
• Added detection for being hosted in ConsoleZ.
• Fixed #20; set /p VAR="" shows the normal command prompt text instead of empty prompt text.

v1.1.47

• Added default key binding for Ctrl+Space to invoke old-menu-complete, which is the most similar to CMD's standard Tab behavior.
• Fixed search-ignore-case config variable to be on by default.

v1.1.46

• Added rl.setvariable() to temporarily override the value of a Readline config variable.
• The completion commands now also expand tilde by itself (~), in addition to tilde followed by a path separator (~\etc).
• Fixed #94; setting history.save to False also disables interactive history in subsequent sessions.

v1.1.45

• Fixed #93; stdout is sometimes broken by Cmder init.bat.

v1.1.44

• Added clink.getsession().
• Added %CLINK_NOAUTORUN% which overrides automatic inject when Clink is installed for autorun.
• Fixed #92; clink-popup-history and similar commands not working with ConEmu and Cmder (regression introduced in v1.1.25).

v1.1.43

• Added clink history --diag flag that prints diagnostic information while performing history operations.
• Minor optimization in clink history when printing the full list of history items.
• Fixed clink history compact so it actually performs compaction.

v1.1.42

• Added clink history --bare flag to omit history item numbers.
• Added several Lua functions:
  • io.popenrw() is like io.popen(), but returns both a read file handle and a write file handle (see documentation for important usage warning).
  • os.createtmpfile() creates a unique named temporary file, with control over the prefix and suffix and path.
  • os.getfullpathname() to get the full path name for a file.
  • os.getlongpathname() to get the long path name for a file.
  • os.getshortpathname() to get the 8.3 short path name (if available) for a file.
• Improved argument validation for Clink's Lua APIs. This could expose bugs in existing scripts, so there is also a lua.strict setting that can be disabled to revert back to loose argument validation.
• Updated documentation.
• Fixed clink history compact so that it forces compaction as intended.
• Fixed completion for clink set so that filename completion works in string settings.
• Fixed backwards return value from rl.invokecommand().
• Fixed console input/output modes across "luafunc:" key bindings, in case the Lua functions spawn a process that alters the console mode without restoring it.

v1.1.41

• Added terminal.adjust_cursor_style setting as a workaround to avoid interfering with the Windows 10 Cursor Shape console setting. There are several trade-offs, though.
• Added rl_buffer:refreshline() function to redraw the input line, e.g. in case something has written over it.
• Added os.getpid() function to get the process ID, intended mainly to help salt unique resource names.
• Added clink.onfiltermatches() so scripts can register a callback function to run after Clink generates matches and before it displays them.

v1.1.40

• Added a group of clink-complete-numbers commands that do completion for numbers from the console screen, bound to Ctrl+Alt+N by default.
• Added rl.getlastcommand() function that returns the name of the last command invoked by key bindings.
• Fixed sort order in Alt+H for the newly supported key bindings (that were added in v1.1.39).
• Fixed Ctrl+Space (regression introduced in v1.1.39).
• Fixed various Ctrl+Shift+whatever combinations (regression introduced in v1.1.39).
• Fixed rl.setmatches() when the input line is not empty and clink.colorize_input is enabled.

v1.1.39

• Added support for many more key bindings, such as Ctrl+Shift+Letter keys.
• Added terminal.differentiate_keys setting that when enabled allows binding Ctrl + H or I or M or [ separately from Backspace, Tab, Return, or Escape.
• Removed terminal.modify_other_keys setting and made it always enabled.
• Changed terminal.use_altgr_substitute to be disabled by default so that Ctrl+Alt key bindings can work by default on keyboards with AltGr.
• Changed output from clink echo so it's directly usable in the inputrc files.
• Fixed terminal.use_altgr_substitute to only affect AltGr substitute key combinations (it had always broken the RightAlt key in general on other keyboard layouts).
• Fixed a benign issue with the console input mode in clink echo.

v1.1.38

• Fixed #84; added terminal.use_altgr_substitute setting.
• Fixed #80; clink.log is not deleted when Cmder injects Clink.

v1.1.37

• Fixed copy to clipboard (it never cleared the clipboard!).
• Fixed #82; added two new clink.paste_crlf modes: ampersand replaces newlines with ampersands, and crlf pastes newlines as-is and executes any commands ending in a newline.
• Fixed #69; space in the prompt disappears after enter echo: added support for CJK codepages.

v1.1.36

• Fixed #79; Issue with United States - international keyboard layout (regression introduced in v1.1.0).
• Fixed #78; crash when history file contains a line longer than 8192 characters (regression introduced in v1.1.2-alpha).

v1.1.35

• Fixed when the mark-directories inputrc variable is off (regression introduced in v1.1.1-alpha).
• Fixed Lua reading from stdin, especially in the Lua debugger (regression introduced in v1.1.25).
• Fixed exponential cost performance bug in Readline when removing duplicate matches.

v1.1.34

• Fixed copying to clipboard (CF_UNICODETEXT was put on the clipboard correctly, but CF_TEXT was empty and should have been omitted to let Windows automatically convert it from the Unicode text).

v1.1.33

• Make the "replacing arglink" warning message a little more informative, and write a lua traceback to the Clink log file.
• Fixed #77; with ConsoleZ scrolling does not always work.
• Fixed #76; cannot cd up multiple directories normally.

v1.1.32

• Added support for non-standard escape codes to set the window title or print environment variables. Depending on the terminal.emulation setting, the behavior is slightly different. When emulate Clink processes the escape codes. When native with ConEmu (and Clink) the escape codes are passed to ConEmu, except that Clink processes the environment variable codes in prompt strings. When native with other terminals, Clink preprocesses the title and environment variable escape codes in prompt strings, but passes the escape codes to the terminal outside of prompt strings.
• Fixed #67; AutoRun interferes with Cmder.

v1.1.31

• Fixed #74; clink gets confused by non-standard ConEmu escape codes.
• Fixed #73; exec.space_prefix and other settings defined in Lua scripts don't take effect until second input line (regression introduced in v1.1.4).

v1.1.30

• Fixed history compacting on x86 (regression introduced in v1.1.2-alpha).

v1.1.29

• Added clink installscripts and clink uninstallscripts to make it easy for package managers like Scoop to install/uninstall script packages for use with Clink. The installed script paths are stored in the registry for the current user.
• Fixed bold vs bright colors to more accurately follow generally accepted ANSI escape code conventions:
  • Renamed dim to nobold for clarity (though dim is still recognized for backward compatibility).
  • bold adds intensity to a non-intense color (e.g. cyan which is 36).
  • nobold removes intensity added by bold (e.g. 1;36 becomes 36), but does not remove intensity from an explicit intense color (such as bright cyan which is 96).
• Fixed support for --file= flags in argmatchers.
• Fixed match display filtering on the first try for a word (regression introduced in v1.1.19).
• Fixed the clink --profile flag (regression introduced in v1.1.10).
• Fixed clink info to accurately report the script dirs (it didn't account for the clink.path setting correctly).

v1.1.28

• Renamed the log.rl_terminal setting to debug.log_terminal; it has already been repeatedly very useful in multiple was since it was added, so it stays.
• Fixed #70; ctrl+c not working (regression introduced in v1.1.25).

v1.1.27

• Added color.argmatcher setting which, when set, is used to color a command name if it has an associated argmatcher (this supersedes color.cmd, color.doskey, and color.input). By default it's not set.
• Added log.rl_terminal setting which logs all terminal input and output for Readline (this setting may be renamed or removed in the future).

v1.1.26

• Added rl.invokecommand() which can invoke a Readline command from inside a "luafunc:" key binding.
• Added rl.setmatches() which can override match completions from inside a "luafunc:" key binding.
• Worked around UTF8 key binding problem with Readline which had been causing some meta key bindings (M-x, M-C-x, etc) to sometimes produce garbled key bindings and garbled entries in clink-show-help (Alt+H).
• Fixed crash if "luafunc:" key binding macro refers to a symbol that doesn't exist.

v1.1.25

• Added clink-find-conhost command that, when in a default (conhost) console window, is equivalent to picking "Find..." from the system menu.
• Added clink-mark-conhost command that, when in a default (conhost) console window, is equivalent to picking "Mark" from the system menu.
• clink-copy-word now copies the current word by default, but copies the nth word if a numeric argument is entered (see "Readline Arguments" in the Readline manual).
• Fixed match display filtering to not exceed the screen width (regression introduced in v1.1.12).
• Fixed multi-key sequences; in some cases it could get confused about whether an input key is part of a multi-key binding sequence (regression introduced in v1.1.1-alpha).
• Fixed stray input processing by conhost (holding Ctrl+A or Ctrl+F or etc could accidentally trigger conhost's shortcut keys).
• Fixed popup window location and size when using Windows Terminal.
• Fixed input coloring after operate-and-get-next; also fixes brief flicker of incorrect coloring whenever the input line is modified.

v1.1.24

• auto for terminal.emulation now uses native VT support on Windows 10 build 15063 and higher, unless the HKCU\Console\ForceV2 regkey is 0.
• Special quote handling now enables "dir\"fi to complete to "dir\file". CMD simply strips quotes during completion, and now Clink behaves similarly.
• Breaking Change: line:getword() and line:getendword() now strip quotes from the word. This should generally automagically make existing match generators work even with embedded quotes, but there's a chance that some match generator might need to be updated. This seems like a reasonable compromise, given the general benefit purchased by this breaking change.
• os:globdirs() and os:globfile() strip quotes from the globpattern in order to behave more like CMD. Embedded quotes are nonsensical and the intended interpretation is clear, so the APIs now help out with that.
• Fixed #66; crash when injecting into 32 bit cmd (regression introduced in v1.1.21).
• Fixed #64; wrong cursor position when PROMPT contains BEL character.
• Fixed #62; argmatchers should color -x:"foo" as a flag if -x: is a flag.
• Fixed #61; argmatchers should not handle completion for text immediately following -flag:. Instead it always uses file completion. A custom generator can be used to override that behavior.
• Fixed #60; completion fails with multiple slashes.
• Fixed completion in some circumstances. Readline and Clink didn't always agree on where the word breaks were; now Clink always tells Readline where the word breaks are (so that completion, input colorization, and lua scripts can all work properly and consistently).
• Fixed 256 color ANSI codes.

v1.1.23

• Fixed #57; slashes not normalized in some cases.
• Fixed #45; interaction between history.dupe_mode=erase_prev and history.shared=false.
• Fixed menu-complete-wraparound when off and there's only 1 match.

v1.1.22

• Added menu-complete-wraparound (on by default) that controls whether completion commands wrap around when cycling past an end (affects popup windows as well).
• Fixed match completion getting stuck (regression introduced in v1.1.19).
• Fixed active mark region so it gets deactivated appropriately (it wasn't hooked up fully for Readline's callback mode, which is the mode Clink uses).
• Fixed clink-show-help (Alt+H) so it's able to list C-@ bindings.
• Fixed inconsistent mark color.

v1.1.21

• Added clink.oninject() so scripts can register a callback function to run when Clink is injected into CMD.
• Added console.linehascolor() function that returns whether the specified line contains any of the specified colors.
• Added console.findprevline() and console.findnextline() functions that can search backwards or forwards for text and/or colors in the screen buffer. Regular expressions may be used.
• Fixed doskey alias parsing for match generators and input line coloring (Clink had been using slightly different parsing rules than CMD does).
• Fixed the "-- More --" prompt while listing key bindings; Esc didn't quit, and unexpected keys weren't ignored.

v1.1.20

• Now you can bind Lua functions to keys via "luafunc:" macros! Added new rl_buffer type that gets passed to the Lua function.
• Added a group of console Lua APIs intended mainly for use by Lua function key bindings (e.g. console.scroll()).
• Added string.equalsi() function that performs a case insensitive UTF8 comparison of two strings.
• Added string.matchlen() function that compares two UTF8 strings and returns how many characters match at the beginning, or -1 if the entire strings match. It respects the match.ignore_case and match.ignore_accents settings.
• Added path.toparent() function that adjust the input string by moving up one directory level.
• Added clink.onendedit() so scripts can register a callback function to run when editing finishes (e.g. Enter is pressed). If desired, the function can even change the input text. This is very powerful, and should be used carefully.
• Changed os.getbatterystatus() to return a table with the battery status details, rather than four separate return values.
• Fixed the doskey.enhanced setting to not expand doskey aliases when preceded by a space. However, a doskey alias after a & or | command separator needs to be preceded by two spaces to avoid expanding it. That's so alias & alias expands both, and alias & alias expands neither; while the rules are more complicated to explain, they make more sense visually.
• Fixed environment variable completion (regression introduced in v1.1.19).
• Fixed Cmder startup (regression introduced in v1.1.17). Cmder expects to be able to replace Clink v0.4.9's clink.lua file, but there is no such thing anymore in newer versions of Clink. To be properly backwardly compatible with Clink v0.4.9 requires loading clink.lua (if it exists) from the first script directory listed by clink info, and ignoring clink.lua files in all other script directories.

v1.1.19

• Improved responsiveness while typing: matches are collected only on demand, instead of always while typing. This makes it possible to always support match completion for UNC paths.
• Fixed #50; Alt+H could warn about likely mistakes in key bindings.

v1.1.18

• The input text now has context sensitive coloring based on the argmatchers. It's on by default and can be turned off with clink set clink.colorize_input false.
• Updated the Readline library to 8.1.
• Terminal emulation now supports the audible bell character.
• Fixed #48; menu-complete gets stuck.
• Fixed #47; Alt+D erases history instead of word.
• Fixed #46; typing .. in subdirectory of root doesn't work.
• Fixed restoring color after pager when showing help.
• Fixed clink set match completions for color settings.

v1.1.17

• Added os.getbatterystatus() function that gets battery status information much faster than launching wmic.
• Fixed #44; Path completion doesn't work with cd /d.
• Fixed loading scripts to ignore loading clink.lua, so that loading scripts behaves like Clink v0.4.9.

v1.1.16

• Added match.ignore_accent setting (enabled by default) that ignores Latin alphabet diacriticals when completing matches (e.g. ä matches a, ı matches i, ł matches l, etc).
• Fixed #42; history lines are split on special characters.
• Fixed #41; Enable custom doskey handling of .. and -.
• Fixed Readline bug inserting dir matches; \win_ foo (cursor at _) would become \Windows\\_ foo.
• Fixed the quoted-insert command to insert just \x1b when ESC is pressed.

v1.1.15

• Migrating settings now immediately writes a new settings file, instead of waiting until a setting is changed.
• Added support to detect when running in Windows Terminal and use native terminal support (which enables things like Xterm 256 and 24-bit color support).
• Added terminal emulation support for Xterm 256 and 24-bit color escape codes. Clink maps the specified color to the most similar color in the active 16 color palette (using the CIELAB color space). To get full support for 24-bit color, it's necessary to use ConEmu or Windows Terminal or a similar console host, or to set terminal.emulation to native (which isn't supported on some older Windows OS versions).
• Allow doskey macros named .. or -, and also now doskey macros that resolve to .. or - or a directory name will work (just like if the macro text had been typed at the Clink prompt).
• Fixed compatibility problem with various scripts getting the %HOME% environment variable. Now if it isn't set, then Clink synthesizes %HOME% from %HOMEDRIVE% and %HOMEPATH% or from %USERPROFILE%.
• Fixed saving color settings to behave like other settings: only write a setting's value to the setting file if it differs from the default value.
• Fixed the clink.print() Lua function so it also works during loading scripts and during prompt filtering.
• Fixed the Readline input text display getting garbled if the filtered prompt includes Xterm's OSC window title code (\x1b]0;text\x07). Clink doesn't support that escape code, but at no longer garbles the input text if that escape code is present.

v1.1.14

• Migrate settings and history from an old version of Clink, if present. This only happens if the new-version Clink settings or history files don't exist. (Deleting an existing new-version Clink settings or history file will cause migration to happen again.)
• Added color.prompt setting for backward compatibility with Clink v0.4.x.

v1.1.13

• Fixed clink.arg.register_parser backward compatibility.

v1.1.12

• Added clink.ondisplaymatches() as a replacement for the deprecated clink.match_display_filter. The new API is able to support popup list windows as well.
• Speculative possible fix for #35 Crash when clink on clink.bat.
• Fixed #33; Tab autocomplete, auto-quoting paths doesn't seem to work as in Clink 0.4.9.

v1.1.11

• Changed to load Lua scripts only once per session, unless forced to reload them. This enables backward compatibility for things like z.lua which has certain features that rely on Clink only loading scripts once per session.
• Added clink.onbeginedit() so scripts can register a callback function to run each time the edit prompt is activated.
• Added lua.reload_scripts setting to optionally force reloading Lua scripts each time the edit prompt is activated.
• Added color.message setting for the Readline message area color (e.g. the search prompt message or digit argument prompt message, etc).
• Fixed stray sticky = appended to completions after typing set and then typing a different command.

v1.1.10

• Fixed #32; hooking ReadConsoleW on Windows 7.

v1.1.9

• Added backward compatibility for clink.match_display_filter. The clink-completions/git.lua script uses it a lot, and that should all be working now.
• settings.add adds a color setting when the type is string and the name starts with "color.".
• settings.get now has an extra parameter to request the user friendly color name when getting a color setting.
• Added clink.version_encoded variable with the Clink version number as MMmmmpppp (e.g. v1.1.9 is 10010009) to make it easy for scripts to check for feature availability.
• The clink info command now shows Lua script paths as well.
• Fixed backward compatibility for loading scripts from the profile directory (if clink.path isn't set, then load scripts from the DLL directory and the profile directory).
• Fixed some color.input bleed through to other things (introduced in v1.1.5).
• Fixed scroll commands (regression introduced by input line color in v1.1.5).
• Fixed horizontally sorted match display and re-enabled the performance fix from v1.1.4.
• Fixed wildcard evaluation with non-file and non-directory matches (e.g. a branch name origin/master accidentally didn't match or or *ma because of the /).
• Fixed sort order of foo\ vs foo.bar\ when displaying matches or using the menu-complete family of commands.
• Fixed potentially-missing trailing path separator when menu-complete completes a directory match (regression introduced by wildcard matching in v1.1.5).
• Other obscure minor fixes.

v1.1.8

• Fixed file match completions when an argmatcher only generates flag matches.
• Fixed automatic inferring whether Readline should use filename completion and/or display rules (regression introduced by backward compatibility in v1.1.3-alpha).
• Fixed backward compatibility for clink.find_files() and clink.find_dirs() (regression introduced by performance improvement in v1.1.7).
  • Ignore extra arguments after the first one (the performance improvement in v1.1.7 revealed that some scripts call clink.find_files() with extra invalid arguments; e.g. clink-completions/modules/matchers.lua).
  • Don't append a trailing path separator on directory names returned by these functions (the new os.globfiles() and os.globdirs() functions do, but the old clink.find_files() and clink.find_dirs() functions should not).
• Fixed backward compatibility for coloring matches (regression introduced by backward compatibility changes in v1.1.4).

v1.1.7

• Performance improvement when displaying matches: When enumerating files and dirs, the os.globfiles and os.globdirs functions have all the info about each file. Now they can return that info in a table. This frees the match display function from needing to do any further file system IO. The performance boost is noticeable.
• Rewrote the color settings: the .fg and .bg sub-settings are gone, and the main setting now uses a more natural syntax (e.g. clink set color.input bright yellow or clink set color.modmark bright cyan on blue).
• Added "cmd" match type for shell (CMD.EXE) command completions.
• Added VT emulation for the reverse video SGR parameters.
• Fixed tab completion for clink set setting, and also handle the new color setting syntax.
• Fixed confusing behavior if multiple scripts try to add settings with the same name (now the first one succeeds and the rest report errors).

v1.1.6

• Hooked up tilde completion in the cd, md, and rd command argmatchers.
• Hooked up tilde completion with the exec.enable setting ("~\pro" matches "C:\Users\myusername\program.exe").
• When terminal.emulation is auto, now it also detects ANSI{32|64}.DLL just like Clink 0.4.8 did.

v1.1.5

• The menu-complete family of commands now support matching ? and * wildcards when the match.wild setting is enabled.
• Added colour.input and colour.modmark settings for coloring Readline's input line.
• Added clink.upper() Lua function, and both clink.lower() and clink.upper() are properly UTF8 aware now.
• Added clink-copy-word command that copies the word at the cursor to the clipboard.
• Added clink.promptfilter setting to control whether to filter the prompt with Lua scripts.
• Renamed terminal.emulate setting to terminal.emulation.
• Improved executable file extension logic to consistently use %PATHEXT% (and efficiently).
• Improved file extension logic (e.g. "file.foo bar" has no extension because of the space).
• Updated arg matcher for clink itself (was missing some flags).
• Changed colour.hidden setting to not be set by default.
• Fixed #28; Tab completion for "~" does not work.
• Fixed #25; Unicode surrogate pairs (and emoji) input isn't working -- Microsoft Terminal renders the text correctly, but ConEmu and the default conhost still don't (and that isn't a Clink issue).
• Fixed screen size bug in Readline on Windows.
• Fixed the backwards values in the terminal.emulation setting.
• Fixed .... so it works properly again.
• Fixed case sensitive sorting of matches.
• Fixed script error when %PATHEXT% is empty.
• Fixed the exec.cwd Clink setting to default to true, so that the default behavior is consistent with how v0.4.x behaved.
• Fixed the cd, md, rd, etc argmatchers to only match one argument to be consistent with the actual command syntax.

v1.1.4

• Automatically detect when running inside ConEmu and disable Clink's Virtual Terminal emulation.
• Added search-ignore-case inputrc variable that makes the history search commands case insensitive.
• Suppress adding a space after completing a flag match that ends with : or = (e.g. msbuild -maxCpuCount:).
• Report any errors while loading Lua scripts.
• Report an error if a Lua script tries to add a flag string that begins with a letter.
• Fixed slow printing of possible matches. Readline is inefficient about emitting output, so Clink supplies a custom implementation.
• Fixed some bugs in auto detection of flag prefix characters.
• Fixed backward compatibility for flags, and for args when merging two parsers by calling clink.arg.register_parser('foo') multiple times for the same command string.
• Fixed truncated message when the last line of a prompt exceeds 128 characters.
• Fixed abort (Ctrl+G or Esc) in non-incremental history search mode.
• Fixed saved values for settings added by Lua scripts; now the saved value is available to the script immediately on adding the setting, and saved values are retained even if the setting isn't always added by the script.
• Fixed (and documented) shorthand form for defining an argmatcher.
• Fixed length of colored match prefix after a path separator.
• Fixed normalizing a slash by itself (command / mustn't become command \ since that can interfere with completing flags).
• Fixed the completion-auto-query-items inputrc variable.
• Fixed the key binding list to correctly respect completion-display-width.
• No visible effect yet: internal change that parses the input line to identify colors to use for each word (command, argument, flag, etc), but the colors aren't yet applied to the input line.

v1.1.3-alpha

• Fixed argmatcher lookup to be more strict, like in Clink 0.4.9 (match exact names, or name plus an extension from %PATHEXT%).
• Backward compatibility:
  • Most things should work now.
  • Dropping the new Clink on top of the vendor\clink directory in Cmder seems to work -- but make a backup before you try this at home!
• API changes:
  • Added log.info() function.
  • Added Clink version numbers in clink.version_major, etc.
  • Added _argmatcher:getwordbreakinfo() callback; removed _argmatcher:setprefixincluded() (it was a mess, and it was new to v1.x, so there's no compatibility concern with removing it).
  • Deprecated _argmatcher:setflagprefix(); now it happens automagically when using _argmatcher:addflags().
  • Introduced several deprecated functions to support backward compatibility.
• Improvements to Lua debugger:
  • Added lua.traceback_on_error, lua.break_on_error, and lua.break_on_traceback settings to make debugging script errors easier.
  • Made pause() consistent about pausing in the caller (rather than sometimes inside the pause command itself).
  • The debugger automatically shows the stack trace when entering debug mode, and on every pause.
  • Show 3 lines of source context by default.
  • The help list is sorted now.
  • Fixed the set command in the debugger to behave as documented.

v1.1.2-alpha

• Documentation is mostly updated; just the argmatcher Lua API and Clink command line options are left to be documented.
• Added history.max_lines setting that controls how many lines of command history to save (1 to 50000, default is 2500).
• Added readline.hide_stderr setting that can suppress stderr output from the Readline library.
• For backward compatibility with 0.4.8, clink_inputrc files are loaded as well.
• Lua script API changes:
  • addmatch() in Lua scripts takes an optional match type argument.
  • Removed displayable, aux, and suffix fields in matches.
  • Revert the change to disallow mixing file/directory/symlink with other match types (it broke the tests and certain completion scenarios).
• Fixed issues:
  • #18 alt+digit then alt+ctrl+y isn't working.
  • #17 arrow keys don't exit reverse-search-history like in bash.
  • #16 problems with $T in doskey macros.
  • #13 clink history delete <n> returns a CRT error.
• Other fixes:
  • There should be no more problems running on Windows Insider builds because Clink now uses Detours for hooking APIs.
  • Fixed crash in insert-completions due to heap failure (introduced by the performance changes for displaying matches).
  • Fixed clink and history built-in aliases (solve glitchy path problem).
  • Fixed scrolling to top of screen buffer.
  • Fixed env var and set completions.
  • Fixed tilde-expand for quoted text.
  • Fixed Esc in Readline's digit argument input mode (it doesn't try to cancel the mode, because that's not how Readline is documented to work).
  • Fixed exit code from some clink command line options.
• Set locale to UTF8 much earlier to avoid quirky behavior early in script processing.

v1.1.1-alpha

• Exclusively use Readline's completion implementation. This (with fixes and enhancements in Readline itself) makes the completion experience much nicer and more sophisticated, and removes a lot of code that was added in v1.0.0a0.
• Exclusively use Readline's key binding implementation. This makes it possible to have a single consistent way to set key bindings (inputrc) and for clink-show-help to list all key bindings, and removes a lot of code that was added in v1.0.0a0.
• Converted all of Clink's internal key behaviors to be implemented as commands that can be bound in the inputrc file.
• Rewrote and refactored the pagination routine to be used in multiple places.
• Fixed prompt filtering to correctly use the specified priority order.
• Readline library:
  • Updated the Readline library from v6.2 to v8.0. This picked up lots of bug fixes and new capabilities (for example colored completions).
  • Changed Readline to support backslash as a path separator.
  • The pager prompt in Readline is optionally colored, controlled by the colour.interact Clink setting.
  • Added completion-auto-query-items config variable (on by default) which asks whether to list possible matches when the number of lines listed will fill one screen page.
  • Added history-point-at-end-of-anchored-search config variable in inputrc to make the cursor point behave like 4Dos/4NT/TakeCommand when searching forward and backward through command history.
  • Fixed prev history at top of history.
  • Fixed to get the current values of environment variables when needed, rather than always getting the value from whenever Clink was started.
  • Fixed coloring directory completions.
  • Fixed menu-complete for \dir and . and ...
  • Fixed slow performance when displaying matches. Readline was calling stat() at least once per match (!!). A new match type field enables faster performance, coloring readonly and hidden file matches, applying filename completion rules only to filenames (vs branch names or other text strings), correct match de-duplication, and more. The Lua match APIs can supply the new match type.
  • Fixed inserting a completion to happen as a single undo group.
  • Fixed tilde to map to %USERPROFILE% instead of %APPDATA% on Windows.
• Typing a directory by itself uses cd /d to change to the directory:
  • Typing a directory with a trailing path separator changes to the directory.
  • Typing ..\ changes to the parent directory.
  • Typing ... or .... etc moves up an extra parent directory level for each extra dot (2 dots move up one parent, 3 dots moves up two parents, etc). A trailing path separator is optional when there are more than 2 dots.
  • Typing - or cd - or chdir - changes to the previous directory.
• Commands that are new, enhanced, or fixed:
  • Added add-history and remove-history commands (similar to 4Dos/4NT/TakeCommand).
  • Got the menu-complete, menu-complete-backward, and old-menu-complete commands working (they never worked properly before in Clink).
    • Also added a corresponding old-menu-complete-backward command for reverse order.
    • All of the *-menu-complete-* commands support wildcards (* and ?).
  • Added clink-show-help command (Alt+H). The help now lists all key bindings, and it shows user-friendly key names (like A-Up or C-x,C-r or C-S-PgUp or A-C-S-F3).
  • Added clink-popup-completions command that shows a popup window listing possible completions. Enter inserts the highlighted completion.
  • Added clink-popup-directories command that shows a popup window listing recent directories. Enter changes to the highlighted directory, or Shift+Enter inserts the highlighted directory in the editing line (or Ctrl+Enter).
  • Added clink-popup-history command that shows a popup window listing command history. Enter executes the highlighted command, or Shift+Enter jumps to the highlighted command in the history (or Ctrl+Enter).
  • Added clink-scroll-lineup, clink-scroll-linedown, clink-scroll-page-up, clink-scroll-page-down, clink-scroll-top, and clink-scroll-bottom commands that do what it looks like they'd do and are bound to the keys it looks like they'd be.
  • Added clink-expand-doskey command (Ctrl+Alt+f) that expands the current line according to the current doskey aliases.
  • Added clink-expand-env-var command (Ctrl+Alt+e) that expands the environment variable at the cursor point.
  • Added clink-exit command (Alt+F4) that exits CMD.
• Fixed keyboard input issues:
  • Esc is a bindable key now (\e[27;27~).
  • Added more bindable key combinations (run clink echo then press keys to see the key sequence to use in the inputrc file).
  • Ctrl+@ (NUL) didn't work.
  • Ins toggles insert/overwrite mode.
  • Unbound keys are ignored now, instead of inserting gibberish characters (part of the terminal internal key sequence).
  • Fixed input handling so the quoted-insert command can work properly.
  • Fixed Esc while searching.
  • Fixed vi mode (was working in v0.4.9, but not in v1.0.x).
• Fixed command history issues:
  • The dont_add_to_history_cmds Clink setting is a space-delimited list of commands to not add to history.
  • Fixed bleeding between history banks.
  • Fixed uninitialized variable that made history updates intermittently do nothing or corrupt the other history bank.
  • Fixed output from clink history to convert to UTF16 when writing to the console (but write UTF8 when output is redirected).
• Fixed terminal output issues:
  • Added terminal.emulate Clink setting that controls whether Clink does VT emulation or passes all ANSI escape codes directly to the console host. For example, this lets the prompt and completion coloring take advantage of more sophisticated ANSI escape codes such as XTerm 256 color and 16 bit color support.
  • Added back support for the prefer-visible-bell config variable.
  • Fixed underline support.
  • Fixed handling for UTF8 output from Readline.
  • Fixed invisible cursor point in Lua debugger.
• Completions:
  • Added match.sort_dirs Clink setting that specifies where to sort directories in the list of possible completions: before files, mixed in with files, or after files.
  • Don't attempt completing incomplete UNC paths: at least the \\server\share\ path components are required (for anything shorter the OS APIs are guaranteed to fail, but will fail slowly).
  • Fixed sorting to use Unicode aware locale based sorting (like Windows does) instead of dumb UTF8 byte comparisons.
  • Fixed arbitrary limit on completions (had been limited to 64KB worth of completions).
  • Fixed quoting spaces in completions.
  • Fixed to use the same list as CMD for characters that require quoting.
  • Fixed normalizing UNC paths.
  • Fixed volume relative completions (e.g. x:foo).
  • Disallow mixing file/directory/symlink with other match types. This was to avoid a confusing/malfunctioning case in match display and prefix highlighting.
• Fixed UTF8 encoding in various Lua functions.
• Fixed printing stderr output from Readline, Lua, and Clink.
• Fixed crashes and other failures when starting Clink in 32 bit CMD.
• Fixed some memory leaks that accumulated with each new line of input.
• Fixed prompt filtering API to be backward compatible with v0.4.9 scripts.
• Fixed Lua errors from clink set (it neglected to fully initialize Clink's Lua integration before loading Lua scripts).
• Fixed UTF8 conversion bug that could truncate a string without fully converting it.
• Fixed serious rampant memory corruption bug in v1.0.x (not present in v0.4.9), which had been causing intermittent malfunctions and data corruption and crashes.
• Fixed multi-line doskey macros to show the prompt in between lines, like CMD does.
• Removed the 4096 byte limit on input.
• Renamed the Clink DLL back to what it was in v0.4.x, to fix compile time problems.
• Other fixed issues:
  • mridgers #544 Clink v1.0.0.a1 doesn't support cyrillic characters keyboard input on Windows 10 with console V2.
  • mridgers #543 Not compatible with Windows Insider Build 20150.
  • mridgers #537 Clink breaks the CMDS tool.
  • mridgers #520 Clink 1.0.0.a1 - clink set history_io 1 Error.
  • mridgers #519 Clink v1.0.0.a1 - -s|--scripts [path] command line arg removed?
  • mridgers #516 Doskey $T not handled properly.
  • mridgers #512 Command history missing in .history.
  • mridgers #503 Keyboard shortcut for scrolling.
  • mridgers #501 Ctrl+Backspace works now.
  • mridgers #487 Clink breaks ConEmu-specific Escape codes.
  • mridgers #480 History never saved.
  • mridgers #465 Using LuaJIT (FFI).
  • mridgers #456 Clear-screen not working properly when PROMPT is two lines long.
  • mridgers #453 Wrong cursor position when a line contains non-printable characters.
  • mridgers #442 Unable to paste more than 1024 characters using Ctrl+V.
  • mridgers #422 Problem with filename modifiers.
  • mridgers #420 Use NtSuspendProcess instead of CreateToolhelp32Snapshot to freeze the threads.
  • mridgers #372 Provide a way to select a previous directory.
  • mridgers #365 history-search behavior.
  • mridgers #342 Clink_inputrc not being processed if it the clink_inputrc is a link (created via mklink).
• Fixed many other bugs.

Releases from mridgers/clink original repo

v1.0.0a1 (alpha test release)

• Improve terminal integration with the Readline library.
• Internal improvements to the built-in ecma48 terminal emulator.
• Fixed use after free in Doskey emulation.
• Fixed dash-dash flag completion.
• Search ancestors for a compatible target process (for when cmd.exe starts another process that subsequently starts clink; especially useful during development).
• Use clink/terminal's wcwidth() implementation.
• screen_buffer::set_cursor() should be relative to the visible area.
• Try to adjust the cursor position better when resizing the terminal.
• Some internal Lua functions needed the unquoted clink exe path.
• The origin path now affects the hash in the dll cache, to guard against directory moves.
• More code reorganization.

v1.0.0a0 (alpha test release)

• Extensive code reorganization, refactoring, and rewriting -- multiple times -- almost everything was touched.
• OS integration:
  • Fixed Doskey macros on Win8, and on Win10.
  • Fixed clink_x??.exe startup stall on Windows 10.
  • Removed XP support. It doesn't load DLLs like Clink uses them.
  • Removed Powershell support.
• Readline integration:
  • Search for multiple places for [.|_]inputrc (fixes mridgers #258).
  • Disabled Readline's completion code, and only use the clink alternative code.
  • Removed redundant slash translation and shims to make it happen.
  • Removed control of Readline's suffix appending and disabled it.
• clink commands and flags:
  • Changed --cfgdir to --profile, it's no longer required, and added help about it.
  • Added a --version option to print Clink's version.
  • Added clink info to print information about Clink.
  • Added clink echo command to echo input key sequences to stdout.
  • Added clink history command (fixes mridgers #172).
  • Added history as an alias for clink history.
  • Added internal --list flag to clink set for match generation.
  • Removed --scripts argument (fixes mridgers #206).
  • Updated clink autorun command's help text.
• Lua scripts:
  • Prefer userprofile over other standard environment variables for where to look for lua scripts.
  • New API for argument style completion scripts.
  • Refactored prompt filtering, and introduced new prompt filtering API.
  • Refactored generating matches, and introduced new match generator API.
  • Removed built in completions scripts for git, go, hg, and p4. There's better ones.
  • Renamed many of clink's Lua functions.
  • Moved functions from clink to os in Lua.
  • Removed clink.is_match() in Lua; don't presume anything on anyone's behalf about matches.
  • Added some current dir functions in Lua.
  • Added some env/dir functions in Lua.
  • Exposed path manipulation functions to Lua.
  • Embed the core Lua scripts instead of loading them from files.
• Terminal IO:
  • Added a module for scrolling the screen.
  • Rewrote the terminal emulation module, and all Readline IO goes through it.
  • Use VT220-style control codes for special keys.
  • If Alt is pressed send ESC in the input stream rather than setting meta bit.
  • Replaced wcwidth() with a more complete and correct version.
• Settings:
  • Added clink_path setting for where to look for lua scripts.
  • Added match.ignore_case setting.
  • Added files.unc_paths setting for optional matching from UNC paths.
  • Added a setting to skip adding lines that start with history.
  • Removed esc_clears_line setting.
  • Pasting CRLFs doesn't really make sense.
  • Don't write out settings that are set to default.
• Make sure Ctrl-C doesn't modify history.
• Make a cached copy of Clink's DLL when injecting so as to not lock the master.
• Guard against Readline's writes to stderr.
• Remove clink_inputrc_base file and embed its content (fixes mridgers #257).
• Include more metadata in the Clink's executables.

v0.4.9

• Fixed broken Doskey on Win10 (#438, #451)

v0.4.8

• Environment variable clink_profile overrides Clink's profile path (#390).
• Load a clink_inputrc file from Clink's profile directory (fixes #406).
• Bug fixes;
  • Redraw issues when prompts end in OSC ANSI codes (#387, #384).
  • Fixed clink autorun --help crash.

v0.4.7

• Bug fixes;
  • Sometimes autorun tries to run clink.exe (#374).
  • Autorun would cause cmd.exe to return an error if it wasn't interactive (#373).

v0.4.6

• HOME is only set if it is currently unset.
• Readline can be initialised with .inputrc and _inputrc files too (#258).
• Bug fixes;
  • Executable completion;
    • Paths from PATH were checked twice.
    • Incorrect results were returned for words ending in . or -.
    • Directories . and .. were incorrectly displayed.
  • Fixed a crash if .bat script's stdout is redirected (#366).
  • Occasional crash when injecting Clink (#351).
  • Display errors;
    • When editing near the window's right-hand edge (#347).
    • Double display of multi-line prompts when resizing the terminal (#352).
    • Very rare wrap artefacts when making the terminal window larger.
  • Doskey emulation (#344).
  • Improved clink autorun help (#348).
  • Fixed launching Clink when clink.bat is renamed (#357).

v0.4.5

• Improved clink autorun. It now defaults to the Current User registry hive.
• clink set gives more details for enumeration-type settings.
• Tab completion for p4vc.
• New settings history_expand_mode to control history expansion in quotes (#317).
• Bug fixes;
  • Use full width of the terminal (#337).
  • Fixed MinGW compile error (#335).
  • Autorun now defaults to the current user's hive (#332).
  • Creating clink.html no longer needs Pandoc, plus it looks a bit better (#331).
  • Added settings to control history expansion (#326).
  • Correct fallback when use_altgr_substitute is off (#325).
  • Load history prior to saving it on shutdown (#318).
  • Added Shift-Tab documentation and menu completion example (#190).
  • Added shim for backwards menu completion (#190).
  • Input handling now outputs \e`Z for Shift-Tab (#190).
  • Updated Readme with current Premake info (#310).
  • Guard against there being no buffer to read from (#304).
  • Fixed artefacts when resizing conhost's buffer (#139).
  • Clear remaining characters if scroll window was too small (#301)
  • Escape % characters when expanding aliases (#280).
  • Fixed leaking exception filters.
  • Clearing the screen doesn't leave artefacts behind.

v0.4.4

• Completing .. behaves more like Bash (#277).
• Escape from yes/no question when Ctrl+C is pressed.
• Valid XP executables (#278, #289).
• Fixed n-th argument yank not working as expected (#254).
• Fixed prompt colours sometimes not working (#279, #286).
• Fixed !0 causing Clink to crash.
• Save/restore cursor position in case Readline moves it.

v0.4.3

• Localised Y/N when auto-answering "terminate?" prompt.
• $* would early out if there was no arguments.
• Disable ANSI code support if third party provides it.
• Installer can now set %CLINK_DIR% to install location.
• Improved output from clink set.
• Support for Windows 10 Technical Preview.
• Ctrl-L now scrolls last line to the top of the window rather than clearing.
• New option to control how newline characters are pasted to the line.
• New options to control history;
  • history_file_lines - maximum lines saved to disk.
  • history_ignore_space - ignore lines prefixed with whitespace.
  • history_dupe_mode - how duplicate entries are handled.
  • history_io - load/save history from disk every line.
• Fixed nonfunctional numpad keys.
• Fixed missing WINCH signals if other processes resize the buffer.
• Support Alt codes sent from Conhost.

v0.4.2

• Prompt colouring no longer requires third party ANSI code utility.
• Override settings with environment variables prefixed with 'clink'.
• Ctrl-PgUp goes up a directory.
• Updated Go completions (by matrixik).
• Arguments to clink.arg.new_parser() now initialise parser's flags/args (from vladimir-kotikov).
• New clink.arg.add_flags() and clink.arg.add_arguments() functions.
• Removed footer and Alt-H tip for more succinct stdout output.
• Bug fixes;
  • Windows XP works again.
  • Fixed race condition in lua_execute().

v0.4.1

• Bug fixes;
  • Various Unicode fixes causing corrupt environment variables.
  • Fixed thread resume/suspend causing rare system-wide deadlock.
  • Fixed incorrect translation of suffixed slash when completing flags.
• Add --nolog argument to disable file logging. Fix #187 Fix #154
• Added missing escape sequences from doskey emulation.
• Reinstated unix-kill-line key binding.
• Mapped PgUp/Down to search history using line typed so far.
• Added documentation covering escape codes for special keys.
• Added support for Windows' AltGr substitute Ctrl-Alt.
• Support for Readline's 'menu' style completion (see docs).

v0.4

• New features;
  • Better clink.arg API. Easier, more intuitive, and more powerful.
  • Whitespace prefix skips exec matching.
  • Added a set verb to easily change settings from the command line.
  • Basic support for a shells other than cmd.exe.
  • Completion for Go (contributed by Dobroslaw Zybort).
  • Setting exec_match_style to -1 disables it entirely.
  • Make history persistence optional.
  • Alias/doskey completion.
  • Very basic support for Powershell.
  • View cmd.exe's autorun entry without needing admin rights.
• New key bindings;
  • Ctrl-Alt-C : Copy command line to the clipboard.
  • Ctrl-Alt-E : Expand environment variable under cursor.
  • Ctrl-Alt-U : "up directory" (formerly Shift-Up).
  • Ctrl-U : Adds ..\ to the command line.
  • Alt-H : Shows active keymap's key bindings.
• New Lua functions;
  • clink.execute().
  • clink.get_host_process().
  • clink.match_files().
  • clink.match_words().
  • clink.get_console_aliases().
• Lots of bug fixes, including;
  • Better command extraction.
  • Fixed cmd.exe command paging and Ctrl-C/Ctrl-Break handling.
  • Multiple locale fixes.
  • Use localised text for "Terminate batch job?" prompt.

v0.3

• Automatic answering of cmd.exe's "Terminate batch script?" prompt.
• Coloured prompts (requires ANSICON or ConEmu).
• Added Shift-Up keyboard shortcut to automatically execute cd ..
• Mapped Ctrl-Z to undo, Microsoft style.
• Improved integration of Readline;
  • New input handling code (Ctrl-Alt combos now work).
  • An implementation of the Termcap library.
  • Fully functional Vi-mode support.
  • Support for resizable consoles.
  • Line wrapping now works correctly (issue 50).
• Adjustable executable match style (issue 65).
• Improved environment variable completion.
• Added settings file to customise Clink.
• New Lua features and functions;
  • Matches can now be filtered in Lua before they are display.
  • clink.quote_split().
  • clink.arg.node_merge().
  • clink.get_screen_info() (issue 71).
  • clink.split() (for splitting strings).
  • clink.chdir().
  • clink.get_cwd().
  • Functions to query Clink's settings.
• New command line options;
  • --profile dir to override default profile directory.
  • --nohostcheck disables verification that host is cmd.exe.
  • --pid specifies the process to inject into.
• Update Mercurial completion (issue 73).
• Start menu shortcut starts in USERPROFILE, like cmd.exe
• Zip distribution is now portable.

v0.2.1

• The .history file now merges multiple sessions together.
• Fixed missing y/n, pause, and other prompts.
• Fixed segfault in loader executable.
• Better ConEmu compatibility.

v0.2

• Basic argument completion for git, hg, svn, and p4.
• Traditional Bash clear screen (Ctrl-L) and exit shortcuts (Ctrl-D).
• Scrollable command window using PgUp/PgDown keys.
• Doskey support.
• Automatic quoting of file names with spaces.
• Scriptable custom prompts.
• New argument framework to ease writing context-sensitive match generators.
• History and log file is now saved per-user rather than globally.
• Improved Clink's command line interface (clink --help).
• More reliable handling of cmd.exe's autorun entry.
• General improvements to executable and directory-command completion.
• Symbolic link support.
• Documentation.
• Windows 8 support.
• Improved hooking so Clink can be shared with other thirdparty utilities that also hook cmd.exe (ConEmu, ANSICon, etc.).

v0.1.1

• Fixed AltGr+<key> on international keyboards.
• Fixed broken completion when directories have a - in their name (Mark Hammond)
• The check for single match scenarios now correctly handles case-insensitivity.

v0.1

• Initial release.

License

Clink is distributed under the terms of the GNU General Public License, version 3.

Credits