-
Notifications
You must be signed in to change notification settings - Fork 8
Full-featured command-line shell interface
License
biot/tokenline
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
Tokenline is a simple command-line shell, intended for systems with few resources. 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; int arg_type; struct token *subtokens; char *help; } 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: TARG_INT integer TARG_FLOAT floating-point value TARG_FREQ frequency, as float followed by khz, mhz or ghz TARG_STRING freeform string, should be quoted if it contains spaces TARG_TOKEN one of a set of tokens in the subtokens field TARG_HELP special type for the "help" command, see below - 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 TARG_TOKEN, this table defines a new context - help A freeform string which will be shown when help for this token is requested. 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, TARG_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 TARG_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: > 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 the previously-allocated t_tokenline struct. This pointer represents a single command-line instance, and will be passed to all other API functions. tl_printfunc is the function called when tokenline produces output. user is a pointer which will be passed along to your printfunc. 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 there as well. 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 a 0 (this is why token integers must not be 0). An argument is represented by one of the TARG_* 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> <TARG_INT> 0 <T_FILE> <TARG_STRING> 4 0 With the buf field containing the following: 00 00 00 01 66 6f 6f 20 62 61 72 00 int tl_input(t_tokenline *tl, uint8_t c) Feed input to the command-line.
About
Full-featured command-line shell interface
Resources
License
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published