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