bertos/mware/parser.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   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.
  10  *
  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.
  15  *
  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
  19  *
  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.
  28  *
  29  * Copyright 2003, 2006 Develer S.r.l. (http://www.develer.com/)
  30  * All Rights Reserved.
  31  * -->
  32  *
  33  * \author Bernie Innocenti <bernie@codewiz.org>
  34  * \author Stefano Fedrigo <aleph@develer.com>
  35  * \author Giovanni Bajo <rasky@develer.com>
  36  *
  37  * \brief Channel protocol parser and commands.
  38  *
  39  * $WIZ$ module_name = "parser"
  40  * $WIZ$ module_configuration = "bertos/cfg/cfg_parser.h"
  41  * $WIZ$ module_depends = "kfile", "hashtable"
  42  */
  43
  44
  45 #ifndef MWARE_PARSER_H
  46 #define MWARE_PARSER_H
  47
  48 #include "cfg/cfg_parser.h"
  49
  50 #include <cpu/types.h>
  51
  52 /**
  53  * Error generated by the commands through the return code.
  54  */
  55 typedef enum
  56 {
  57         RC_ERROR  = -1, ///< Reply with error.
  58         RC_OK     = 0,  ///< No reply (ignore reply arguments).
  59         RC_REPLY  = 1,  ///< Reply command arguments.
  60         RC_SKIP   = 2   ///< Skip following commands
  61 } ResultCode;
  62
  63 /** union that contains parameters passed to and from commands */
  64 typedef union { long l; const char *s; } parms;
  65 /** pointer to commands */
  66 typedef ResultCode (*CmdFuncPtr)(parms args_results[]);
  67
  68 /**
  69  * Define a command that can be tokenized by the parser.
  70  *
  71  * The format strings are sequences of characters, one for each
  72  * parameter/result. Valid characters are:
  73  *
  74  *  d - a long integer, in decimal format
  75  *  s - a var string (in RAM)
  76  *
  77  * \note To create and fill an instance for this function, it is strongly
  78  * advised to use \c DECLARE_CMD_HUNK (cmd_hunk.h).
  79  */
  80 struct CmdTemplate
  81 {
  82         const char *name;          ///< Name of command
  83         const char *arg_fmt;       ///< Format string for the input
  84         const char *result_fmt;    ///< Format string for the output
  85         CmdFuncPtr func;           ///< Pointer to the handler function
  86         uint16_t   flags;          ///< Currently unused.
  87 };
  88
  89 /**
  90  * Initialize the parser module
  91  *
  92  * \note This function must be called before any other function in this module
  93  */
  94 void parser_init(void);
  95
  96
  97 /**
  98  * Register a new command into the parser
  99  *
 100  * \param cmd Command template describing the command
 101  *
 102  */
 103 void parser_register_cmd(const struct CmdTemplate* cmd);
 104
 105
 106 /**
 107  * Hook for readline to provide completion support for the commands
 108  * registered in the parser.
 109  *
 110  * \note This is meant to be used with mware/readline.c. See the
 111  * documentation there for a description of this hook.
 112  */
 113 const char* parser_rl_match(void* dummy, const char* word, int word_len);
 114
 115
 116 /**
 117  * \brief Command input handler.
 118  *
 119  * Process the input, calling the requested command
 120  * (if found) and calling printResult() to give out
 121  * the result (on device specified with parameter fd).
 122  *
 123  * \param line Text line to be processed (ASCIIZ)
 124  *
 125  * \return true if everything is OK, false in case of errors
 126  */
 127 bool parser_process_line(const char* line);
 128
 129
 130 /**
 131  * Execute a command with its arguments, and fetch its results.
 132  *
 133  * \param templ Template of the command to be executed
 134  * \param args Arguments for the command, and will contain the results
 135  *
 136  * \return False if the command returned an error, true otherwise
 137  */
 138 INLINE bool parser_execute_cmd(const struct CmdTemplate* templ, parms args[CONFIG_PARSER_MAX_ARGS])
 139 {
 140         return (templ->func(args) == 0);
 141 }
 142
 143
 144 /**
 145  * Find the template for the command contained in the text line.
 146  * The template can be used to tokenize the command and interpret
 147  * it.
 148  *
 149  * This function can be used to find out which command is contained
 150  * in a given text line without parsing all the parameters and
 151  * executing it.
 152  *
 153  * \param line Text line to be processed (ASCIIZ)
 154  *
 155  * \return The command template associated with the command contained
 156  * in the line, or NULL if the command is invalid.
 157  */
 158 const struct CmdTemplate* parser_get_cmd_template(const char* line);
 159
 160
 161 /**
 162  * Extract the arguments for the command contained in the text line.
 163  *
 164  * \param line Text line to be processed (ASCIIZ)
 165  * \param templ Command template for this line
 166  * \param args Will contain the extracted parameters
 167  *
 168  * \return True if everything OK, false in case of parsing error.
 169  */
 170 bool parser_get_cmd_arguments(const char* line, const struct CmdTemplate* templ, parms args[CONFIG_PARSER_MAX_ARGS]);
 171
 172
 173 #if CONFIG_ENABLE_COMPAT_BEHAVIOUR
 174 /**
 175  * Extract the ID from the command text line.
 176  *
 177  * \param line Text line to be processed (ASCIIZ)
 178  * \param ID Will contain the ID extracted.
 179  *
 180  * \return True if everything ok, false if there is no ID
 181  *
 182  */
 183 bool parser_get_cmd_id(const char* line, unsigned long* ID);
 184 #endif
 185
 186
 187 #endif /* MWARE_PARSER_H */
 188