mware/parser.h

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