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 * \author Bernie Innocenti <bernie@codewiz.org>
34 * \author Stefano Fedrigo <aleph@develer.com>
35 * \author Giovanni Bajo <rasky@develer.com>
37 * \brief Channel protocol parser and commands.
39 * $WIZ$ module_name = "parser"
40 * $WIZ$ module_configuration = "bertos/cfg/cfg_parser.h"
41 * $WIZ$ module_depends = "kfile", "hashtable"
45 #ifndef MWARE_PARSER_H
46 #define MWARE_PARSER_H
48 #include <cpu/types.h>
50 /** Max number of arguments and results for each command */
51 #define PARSER_MAX_ARGS 8
54 * Error generated by the commands through the return code.
58 RC_ERROR = -1, ///< Reply with error.
59 RC_OK = 0, ///< No reply (ignore reply arguments).
60 RC_REPLY = 1, ///< Reply command arguments.
61 RC_SKIP = 2 ///< Skip following commands
64 /** union that contains parameters passed to and from commands */
65 typedef union { long l; const char *s; } parms;
66 /** pointer to commands */
67 typedef ResultCode (*CmdFuncPtr)(parms args_results[]);
70 * Define a command that can be tokenized by the parser.
72 * The format strings are sequences of characters, one for each
73 * parameter/result. Valid characters are:
75 * d - a long integer, in decimal format
76 * s - a var string (in RAM)
78 * \note To create and fill an instance for this function, it is strongly
79 * advised to use \c DECLARE_CMD_HUNK (cmd_hunk.h).
83 const char *name; ///< Name of command
84 const char *arg_fmt; ///< Format string for the input
85 const char *result_fmt; ///< Format string for the output
86 CmdFuncPtr func; ///< Pointer to the handler function
87 uint16_t flags; ///< Currently unused.
91 * Initialize the parser module
93 * \note This function must be called before any other function in this module
95 void parser_init(void);
99 * Register a new command into the parser
101 * \param cmd Command template describing the command
104 void parser_register_cmd(const struct CmdTemplate* cmd);
108 * Hook for readline to provide completion support for the commands
109 * registered in the parser.
111 * \note This is meant to be used with mware/readline.c. See the
112 * documentation there for a description of this hook.
114 const char* parser_rl_match(void* dummy, const char* word, int word_len);
118 * \brief Command input handler.
120 * Process the input, calling the requested command
121 * (if found) and calling printResult() to give out
122 * the result (on device specified with parameter fd).
124 * \param line Text line to be processed (ASCIIZ)
126 * \return true if everything is OK, false in case of errors
128 bool parser_process_line(const char* line);
132 * Execute a command with its arguments, and fetch its results.
134 * \param templ Template of the command to be executed
135 * \param args Arguments for the command, and will contain the results
137 * \return False if the command returned an error, true otherwise
139 INLINE bool parser_execute_cmd(const struct CmdTemplate* templ, parms args[PARSER_MAX_ARGS])
141 return (templ->func(args) == 0);
146 * Find the template for the command contained in the text line.
147 * The template can be used to tokenize the command and interpret
150 * This function can be used to find out which command is contained
151 * in a given text line without parsing all the parameters and
154 * \param line Text line to be processed (ASCIIZ)
156 * \return The command template associated with the command contained
157 * in the line, or NULL if the command is invalid.
159 const struct CmdTemplate* parser_get_cmd_template(const char* line);
163 * Extract the arguments for the command contained in the text line.
165 * \param line Text line to be processed (ASCIIZ)
166 * \param templ Command template for this line
167 * \param args Will contain the extracted parameters
169 * \return True if everything OK, false in case of parsing error.
171 bool parser_get_cmd_arguments(const char* line, const struct CmdTemplate* templ, parms args[PARSER_MAX_ARGS]);
175 * Extract the ID from the command text line.
177 * \param line Text line to be processed (ASCIIZ)
178 * \param ID Will contain the ID extracted.
180 * \return True if everything ok, false if there is no ID
183 bool parser_get_cmd_id(const char* line, unsigned long* ID);
186 #endif /* MWARE_PARSER_H */