README

Tokenline is a simple command-line shell interface, intended for systems
with few resources. It is available under the terms of the GNU GPL, version
2 or later.


FEATURES:

- Fully tokenizes input according to defined command hierarchy
- Supports integer, floating-point and string variables
- Uses no dynamic memory allocation
- Automatic context-sensitive help
- Automatic command completion, and partial command parsing
- Bash-like key bindings
- History

To integrate tokenline into your application, only the following source
files are needed:
	tokenline.c
	tokenline.h

The demo/ directory has a sample application that shows how to use
tokenline.


DEFINING A COMMAND HIERARCHY

All commands are defined as tokens (integers). To define a token, your
application should do something like this:

	#define T_SHOW 1

The token integers must be between 1 and 9999. Defining the command keyword
associated with that token is done in a token dictionary:

	t_token_dict dict[] = {
		{ /* Dummy entry */ }
		{ T_SHOW, "show" }
		{ }
	};

This table must be kept in the same order as the token integers, hence
the dummy entry: that skips entry 0.

Also note the { } entry in the table. Every table must be terminated with an
all-zero entry.

The following struct defines a single token:

	typedef struct token {
		int token;
		uint16_t arg_type;
		uint16_t flags;
		struct token *subtokens;
		char *help;
		char *help_full;
	} t_token;

Only the token field is required; all others are optional:
 - arg_type
   If the token takes an argument, The type of that argument should
   be filled in here. The following are available:
     T_ARG_UINT     unsigned integer
     T_ARG_FLOAT    floating-point value
     T_ARG_FREQ     frequency, as float followed by khz, mhz or ghz
     T_ARG_STRING   freeform string, should be quoted if it contains spaces
     T_ARG_TOKEN    one of a set of tokens in the subtokens field
     T_ARG_HELP     special type for the "help" command, see below
 - flags
   Flags to change behavior on this token or its arguments. The currently
   defined flags are:
     T_FLAG_SUFFIX_TOKEN_DELIM_INT
        This allows the token to be suffixed with TL_TOKEN_DELIMITER
        (set to : by default), followed by an integer. If this syntax is
        used, the result will show up on the parsed token list like this:
           <T_ARG_TOKEN_SUFFIX_INT> (integer)
 - subtokens
   A t_token table contains a set of tokens to be used if this token is
   used. For example, The T_SHOW token above might have a set of subtokens
   selecting the thing to show (see example). When not used with T_ARG_TOKEN,
   this table defines a new context.
 - help
   A freeform string which will be shown next to this token on help or
   completion for the table in which this entry is found. It should not be
   longer than 60 characters.
 - help_full
   A freeform string which will be shown when help for this specific token is
   requested. This can be more than one line; it is intended to be a more
   detailed help text than the summary provided by the "help" field.

The T_ARG_UINT type may be specified as a token in the table: this allows
free-standing numbers to be entered on the command line. See the demo
application's 'calc' command for an example.

Here's a complete example implementing a "show" command:

	enum {
		T_SHOW = 1,
		T_HARDWARE,
		T_VERSION,
		T_HELP,
	};
	t_token_dict dict[] = {
		{ /* Dummy entry */ },
		{ T_SHOW, "show" },
		{ T_HARDWARE, "hardware" },
		{ T_VERSION, "version" },
		{ T_HELP, "help" },
		{ }
	};
	t_token tokens_show[] = {
		{ T_HARDWARE, 0, NULL, "Show hardware information" },
		{ T_VERSION, 0, NULL, "Show version" },
		{ }
	};
	t_token tokens[] = {
		{ T_SHOW, 0, tokens_show, "Show information" },
		{ T_HELP, T_ARG_HELP, NULL, "Available commands" },
		{ }
	};

If you define tokens with the command string "history" or "help", these
will be handled internally, not passed on to your callback. The "history"
command simply prints the command history for this session, and the "help"
command provides help for the current context. Define the help command with
the T_ARG_HELP type: this lets you do tab completion on keywords after the
help command.

The above definitions are enough to make this work:

    > help
    Available commands
       show           Show information
       help           Available commands
    > help show
    Show information
       hardware       Show hardware information
       version        Show version
    > help show hardware 
    Show hardware information

This also gets you tab completion of all keywords, and lets you abbreviate
keywords. The following are equivalent, and get your callback the same
tokens:

    > show hardware
    > sh hard


API

Interact with tokenline via the following functions:

typedef void (*tl_printfunc)(void *user, const char *str);
void tl_init(t_tokenline *tl, t_token *tokens, t_token_dict *dict,
		tl_printfunc printfunc, void *user)

  Initializes a previously-allocated t_tokenline struct "tl". This pointer
  represents a single command-line instance, and will be passed to all
  other API functions. "tokens" is the initial token tree for this instance,
  and "printfunc" is the function called when tokenline produces output.
  "user" is a pointer which will be passed along to all your callback
  functions.

void tl_set_prompt(t_tokenline *tl, char *prompt)

  Change the prompt tokenline uses. The pointer is used from then on,
  so dynamic prompt changes can be done on that pointer.

typedef void (*tl_callback)(void *user, t_tokenline_parsed *p);
void tl_set_callback(t_tokenline *tl, tl_callback callback)

  Set the function that will be called when a command is entered. The
  t_tokenline_parsed struct is defined as follows:

	typedef struct tokenline_parsed {
		int tokens[TL_MAX_WORDS];
		char buf[TL_MAX_LINE_LEN];
	} t_tokenline_parsed;

  The list of entered tokens is in the tokens field, terminated by 0 (this
  is why token integers must not be 0). An argument is represented by one
  of the T_ARG_* types (see above), followed by an integer representing an
  offset into the "buf" field where the value lives. This value is simply
  sizeof(int), sizeof(float) or a NULL-terminated string. For example,
  the following command line:

	> show device 1 file "foo bar"

  Would be represented like this in the tokens field:

	<T_SHOW> <T_DEVICE> <T_ARG_UINT> 0 <T_FILE> <T_ARG_STRING> 4 0
                                    ^                         ^
        argument offset in buffer --|                       --|

  With the buf field containing the following:

	00 00 00 01 66 6f 6f 20 62 61 72 00
    ^           ^
    0 (int)     4 (string)

int tl_mode_push(t_tokenline *tl, t_token *tokens)

  Switch to a new mode with its own token tree. The token tree is pushed
  on to a stack.

int tl_mode_pop(t_tokenline *tl)

  Exit the current mode, and return to the previous token tree.

int tl_input(t_tokenline *tl, uint8_t c)

  Feed input to the command-line.