A command line editing library. Overview ======== readcmd package contains the next routines: - readcmd::term_set_raw - to switch a terminal to a raw mode - readcmd::term_unset_raw - to switch a terminal to a normal mode - readcmd::term_get_prms - to get terminal parameters - readcmd::term_set_prms - to set terminal parameters - readcmd::read_sync - to read a command line Synopsis ======== readcmd::term_set_raw readcmd::term_unset_raw [PRMS] readcmd::term_get_prms readcmd::term_set_prms [PRMS] readcmd::read_sync [PROMPT] [HISTO] [CMDS] [EXIT_CMD] [TOKEN_REGEXP] [KBINDINGS] Description =========== The main work is done by readcmd::read_sync proc. But before they start, a terminal should be switched in a raw mode. This can be done with readcmd::term_set_raw proc and can be reverted back with readcmd::term_unset_raw proc(or with readcmd::term_set_prms proc). After read_sync proc is started it get a terminal dimensions(rows and columns counts) and a cursor position with help of ascii control sequences; after that it read characters entered by a user. readcmd::read_sync arguments: prompt - a command prompt histo - a list with previously entered commands(first is the oldest command, last is the most recent command) cmds - a dict with available commands, where key is command name and value is a dict with subcommands and so on. If a value dict contain a key " " with "descr" subkey, then it's used as description of a command in a list of possible completions which is showed to a user on tab key(by default). If a value dict contain a key " " with "acl_hdlr" subkey, then, it's used as autocompletion list handler which should return a list of possible completions. exit_cmd - a command which will be returned when a key handler returns 3(by default on ctrl-d press) tok_rex - a regular expression for token matching kbindings - a dict with a key sequence mapping to handlers cmds dict example from ex.tcl: namespace eval mod_version { proc cmd_show_ver {args} { puts "0.2" } } dict set cmds show " " descr "show info" dict set cmds show version " " hdlr ::mod_version::cmd_show_ver dict set cmds show version " " descr "show program version" Keys bindings is a dict where each key represents a character ascii code or ascii codes sequence of a ascii control sequence(for CSI sequence this sequence should include only CSI and final byte without parameter and intermediate bytes - e.g. "\x1b\x5b\x7e" for delete ascii control sequence, where full CSI sequence is "\x1b\x5b\x33\x7e" where \x33 is a parameter byte). See readcmd::kbindings dict in readcmd.tcl. On package loading (i.e. sourcing readcmd.tcl) readcmd try to load a configuration from files specified in readcmd::conf_fname variable. The first existent file will be loaded with help of source command. By default, it contains "$::env(HOME)/.readcmd.conf /etc/readcmd.conf". See example conf in readcmd.conf.example file. Input is read by one character. If we got ascii ESC(\x1b ascii code), then we read the next character. If it is not ascii [ (\x5b ascii code), then we done with an ascii escape sequence; if it is ascii [, then we've read CSI sequence and must read every character until we got a CSI sequence final byte. Autocompletion is automatic for commands names from cmds dict (this is done by readcmd::_acl_gen_from_dict proc). But we can set autocompletion for command parameters. Autocompletion handler is specified with acl_hdlr subkey in " " key of cmd dict. This handler should accept a completed tokens list as a first argument; and an uncompleted token as a second argument. It is not guaranteed that it is uncompleted token, but we think so because a cursor is right after it. This handler must return a list of possible completions that will be shown to a user as is. No processing is applied to it. readcmd lib detect a common prefix of every tokens from the list returned by a handler. Then lib remove an uncompleted token from the start of this detected common prefix(if an uncompleted token is a prefix of a common prefix for the list). Then this string will be a detected completion suffix. Examples ======== see ex.tcl and tclshrc for examples. Sponsors ======== Z-Wave.Me