4 * This file is part of BeRTOS.
6 * Bertos is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 * As a special exception, you may use this file as part of a free software
21 * library without restriction. Specifically, if other files instantiate
22 * templates or use macros or inline functions from this file, or you compile
23 * this file and link it with other files to produce an executable, this
24 * file does not by itself cause the resulting executable to be covered by
25 * the GNU General Public License. This exception does not however
26 * invalidate any other reasons why the executable file might be covered by
27 * the GNU General Public License.
29 * Copyright 2003, 2006 Develer S.r.l. (http://www.develer.com/)
30 * All Rights Reserved.
33 * \defgroup parser Simple RPC machinery
37 * \brief Channel protocol parser and commands.
39 * This module provides a simple text based RPC implementation.
40 * Often there is the need to give a command to the device and receive results
41 * back. Each command may have a variable number of input and output
42 * parameters, with variable type, and a return code which indicates if the
43 * command was successfully executed or not; this module provides the machinery
44 * to facilitate the above RPC scenario.
45 * You will need to write the RPC input and reply code as well as
46 * the definition of the commands.
48 * Commands are defined using a CmdTemplate struct containing:
49 * - command name: the string that will be matched by the parser;
50 * - command arguments: a string representing type and number of input
52 * - command output: a string representing type and number of output arguments;
53 * - function callback: function implementing the command.
55 * Once you have declared the commands, you need to register them in the
56 * parser with the function parser_register_cmd().
57 * You are strongly encouraged to use MAKE_CMD() (or alternatively
58 * MAKE_TEMPLATE()) and REGISTER_CMD() to declare and register commands.
60 * A command line can be parsed with the following steps:
61 * - find the corresponding command template with parser_get_cmd_template()
62 * - extract command arguments with parser_get_cmd_arguments()
63 * - execute the command with parser_execute_cmd()
65 * You can also provide interactive command line completion using
70 * // Declare a buzzer command
71 * MAKE_CMD(beep, "d", "",
73 * buz_beep(args[1].l);
77 * // initialize the parser
81 * // parse an input line
83 * // read line from somewhere
85 * // now parse the line
86 * const struct CmdTemplate *templ;
87 * templ = parser_get_cmd_template(buf);
89 * // Take arguments (optionally check errors)
90 * parms args[PARSER_MAX_ARGS];
91 * parser_get_cmd_arguments(buf, templ, args);
93 * if(!parser_execute_cmd(templ, args))
97 * // Now args contain the outputs of the function, you can send it
98 * // back to the caller
103 * <b>Configuration file</b>: cfg_parser.h
105 * \author Bernie Innocenti <bernie@codewiz.org>
106 * \author Stefano Fedrigo <aleph@develer.com>
107 * \author Giovanni Bajo <rasky@develer.com>
109 * $WIZ$ module_name = "parser"
110 * $WIZ$ module_configuration = "bertos/cfg/cfg_parser.h"
111 * $WIZ$ module_depends = "kfile", "hashtable"
115 #ifndef MWARE_PARSER_H
116 #define MWARE_PARSER_H
118 #include "cfg/cfg_parser.h"
120 #include <cpu/types.h>
121 #include <cfg/debug.h>
124 * Error generated by the commands through the return code.
128 RC_ERROR = -1, ///< Reply with error.
129 RC_OK = 0, ///< No reply (ignore reply arguments).
130 RC_REPLY = 1, ///< Reply command arguments.
131 RC_SKIP = 2 ///< Skip following commands
134 /** union that contains parameters passed to and from commands */
135 typedef union { long l; const char *s; } parms;
136 /** pointer to commands */
137 typedef ResultCode (*CmdFuncPtr)(parms args_results[]);
140 * Define a command that can be tokenized by the parser.
142 * The format strings are sequences of characters, one for each
143 * parameter/result. Valid characters are:
145 * d - a long integer, in decimal format
146 * s - a var string (in RAM)
148 * \note To create and fill an instance for this function, it is strongly
149 * advised to use \c DECLARE_CMD_HUNK (cmd_hunk.h).
153 const char *name; ///< Name of command
154 const char *arg_fmt; ///< Format string for the input
155 const char *result_fmt; ///< Format string for the output
156 CmdFuncPtr func; ///< Pointer to the handler function
157 uint16_t flags; ///< Currently unused.
160 #define REGISTER_FUNCTION parser_register_cmd
163 * Utility function to register a command.
165 * \param NAME Command name to register
167 #define REGISTER_CMD(NAME) \
169 if (!REGISTER_FUNCTION(&cmd_ ## NAME ## _template)) \
170 ASSERT2(0, "Error in registering command, no space left"); \
174 * Utility macro to create a command template.
176 * It requires that a callback function with name \a cmd_NAME
177 * is already defined.
178 * \param NAME Command name
179 * \param ARGS Input arguments
180 * \param RES Output arguments
181 * \param FLAGS Command flags
183 #define MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS) \
184 const struct CmdTemplate cmd_ ## NAME ## _template = \
186 #NAME, ARGS, RES, cmd_ ## NAME, FLAGS \
190 * Utility macro to create command templates and callback functions.
192 * Example for a version command:
194 * MAKE_CMD(ver, "", "ddd",
196 * args[1].l = VERS_MAJOR;
197 * args[2].l = VERS_MINOR;
198 * args[3].l = VERS_REV;
203 * Remember that input and output parameters start from index 1, since
204 * args[0] is the command itself.
205 * The last line is the return value of the function.
207 * \param NAME Command name matched by the parser
208 * \param ARGS Input arguments to the command
209 * \param RES Output arguments of the command
210 * \param BODY Command body, expressed with C 'statement expression'
211 * \param FLAGS Command flags
213 #define MAKE_CMD(NAME, ARGS, RES, BODY, FLAGS) \
214 static ResultCode cmd_ ## NAME (parms *args) \
216 return (ResultCode)BODY; \
218 MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS)
221 * Initialize the parser module
223 * \note This function must be called before any other function in this module
225 void parser_init(void);
227 bool parser_register_cmd(const struct CmdTemplate* cmd);
231 * Hook for readline to provide completion support for the commands
232 * registered in the parser.
234 * \note This is meant to be used with mware/readline.c. See the
235 * documentation there for a description of this hook.
237 const char* parser_rl_match(void* dummy, const char* word, int word_len);
239 bool parser_process_line(const char* line);
242 * Execute a command with its arguments, and fetch its results.
244 * The \a args paramenter is value-result: it provides input arguments to
245 * the callback function and it stores output values on return.
247 * \param templ Template of the command to be executed
248 * \param args Arguments for the command, and will contain the results
250 * \return False if the command returned an error, true otherwise
252 INLINE bool parser_execute_cmd(const struct CmdTemplate* templ, parms args[CONFIG_PARSER_MAX_ARGS])
254 return (templ->func(args) == 0);
257 const struct CmdTemplate* parser_get_cmd_template(const char* line);
259 bool parser_get_cmd_arguments(const char* line, const struct CmdTemplate* templ, parms args[CONFIG_PARSER_MAX_ARGS]);
261 #if CONFIG_ENABLE_COMPAT_BEHAVIOUR
263 * Extract the ID from the command text line.
265 * \param line Text line to be processed (ASCIIZ)
266 * \param ID Will contain the ID extracted.
268 * \return True if everything ok, false if there is no ID
271 bool parser_get_cmd_id(const char* line, unsigned long* ID);
275 /** \} */ // defgroup parser
276 #endif /* MWARE_PARSER_H */