Copyright (C) 2013-2019 Roelof Nico du Toit.

libchars - Command Line Interface (CLI) Framework

Version 0.8.3 (25-Apr-2019)

See LICENSE.txt and all source files for license agreement.

Build instructions
==================
The build steps depend on availability of the cmake tools.  Refer to the
following link for steps to install cmake:
http://www.cmake.org/cmake/help/install.html

- mkdir libchars.build
- cd libchars.build
- cmake path-to-libchars-source
- make

Overview
========
The libchars package is an extensible C++ framework for building a command-line
interface (CLI) in Linux, FreeBSD, or OS/X.  It features a terminal driver, 
line editor, argument validation engine, commands engine and command history.
The code is distributed under the MIT license.

Dependencies
============
One of the design goals was to have as few dependencies as possible.  The only
dependency in the current version is using cmake at compile time to facilitate
building the binaries.  There are no runtime dependencies other than the C/C++
standard libraries.

The code compiles without issues when using the following compilers:
- clang version 4.1 (OS/X)
- gcc version 4.6.3 (Ubuntu 12.04LTS)

The VT100 terminal driver was validated using the following terminal clients:
- xterm
- iTerm (OS/X)
- Terminal (OS/X)
- ssh (OS/X, FreeBSD, Linux)
- Putty (Windows)
- NPort Serial to Ethernet appliance

Features
========
The CLI framework has support for the following features:
- Password entry mode (no echo of characters).
- Multi-line entry mode for large multi-line strings.
- Support editing strings that are larger than the terminal (auto-scroll).
- Override rendering of string in editor, e.g. add color or extra characters.
- Support for different types of parameters (flags, key-value, positional).
- Support for dynamically changing command list after every command.
- Command auto-completion and listing of command alternatives.
- Listing command parameters (if command is known).
- Context sensitive help on commands and parameters.
- Colorized tokens to distinguish invalid, valid, and partial commands.
- Colorized tokens to highlight invalid arguments.
- Colorized tokens to highlight quoted strings.
- Command history, with option to extend how history is made persistent.
- Command history search (up and down) based on partial string.
- Command argument validation, with extensible option types.
- Command prompt can be changed dynamically.
- Re-render line when terminal size changes.
- Support for hidden commands (not in auto-complete or command list)
- Non-interactive command parsing.
- Command sets, which can be used to implement command levels.
- Timeout on command editor; used for housekeeping before editing continues

Known Issues
============
- The command list is currently sorted alphabetically when displaying context-sensitive help, but some applications require displaying the list in the order commands were added.
- There is currently no wide-character / UTF8 support.
- The library is mostly thread-safe, but the caller must currently ensure that only one editor instance at a time is using the terminal driver.

Feature Requests
================
- Support for paging in terminal driver, i.e. pause on full page of output.
- Reference code for full shell implementation.
- Built-in argument validators for common types, e.g. IPv4 address, hostname.
- Support for positional argument groups for lists of arguments of the same type, e.g. lists of names.
- Option to display command list in the order commands were added.

Code Layout
===========
The libchars CLI framework is written in C++, and all classes are in
the libchars namespace.  The source files have names that reflect the
functional building blocks:

terminal.h/cpp     VT100 Terminal Driver
editor.h/cpp       Line editor and key sequence mapper
parameter.h/cpp    Tokens and command parameters
commands.h/cpp     Lexer and command parser
history.h/cpp      Command history, including history search
validation.h/cpp   Command argument validation
debug.h/cpp        Debug helper API; printf() style logs
test_editor.cpp    Sample application to demonstrate editing and rendering
test_commands.cpp  Sample application to demonstrate commands engine

Commands Engine
===============
The CLI framework commands engine supports the following parameter types:
- Key-Value pair, e.g. “name=John”
- Flags, e.g. “disable-color”
- Positional arguments, which are values indexed by position

The command parser supports entering the parameters in any order, apart from
positional arguments which should still be in order relative to each other,
but flags and key-value pairs may be entered anywhere in the command line.
Parameters are optional or mandatory – setting a default value on a key-value
pair or positional argument automatically makes it optional.  Flags are always
optional because the default value of a flag is false.  Parameters may also be
hidden, and default values may be specified.

Commands have unique identifiers:  a name and/or a unique ID.  At least one of
name or ID must be specified. Commands also have an optional 64-bit bitmask
that may be used to filter out certain commands based on an input mask, in
effect dynamically controlling the command list on every command. 

The command string may contain multiple words, e.g. “set color” or
“show attribute list”.  Commands may overlap, e.g. the command1 = “throw ball”
and command2 = “throw balls”.  Another example of overlap:
command1 = “throw ball” and command2 = “throw ball back”.

Commands are validated as you type, and the color of the command string
changes depending on the command status, e.g. partial commands are rendered
in yellow while a full match on a command string renders it in green.
Invalid commands or command parameters are rendered in red.

On return from the commands engine the command arguments may be extracted by
parameter ID, by parameter name, by parameter position, or by walking the
token list chain.