Initial revision

doc/programmer/fupa.tex

@@ -0,0 +1,83 @@
+\subsection{Function Parser}
+   A utility module to take some of the pain from parsing input while
+   writing text wrapper function for SICS.
+   The idea is that you specify an array of function templates.
+   These function templates will contain function names and argument
+   information. This module will than parse the input against this
+   template. It will return -1 if an error occurs and provide error 
+   information.
+   On success  the index of the function found  will be returned. 
+   Arguments will have been updated with their proper values.
+   Invoking functions ist still your job, probably in a switch statement
+   following the call to the evaluation function.
+
+The function parser supports these different argument types:
+\begin{verbatim}
+#define FUPATEXT  0 /* text*/
+#define FUPAINT   1 /* integer */
+#define FUPAFLOAT 2 /* a float */
+#define FUPAOPT   3 /* optional argument, in this case text contains it
+                       and iVal indicates its presence 
+                    */ 
+\end{verbatim}
+
+Each template for a function has these fields:
+\begin{verbatim}   
+   typedef struct {
+                   char *name;
+                   int iArgs;
+                   int pArgs[MAXARG];
+                   } FuncTemplate, *pFuncTemplate;
+\end{verbatim}
+\begin{description}
+\item[name] the name of the function.
+\item[iArgs] The number of arguments to the function.
+\item[pArgs] An array with iArgs entries of the integer argument description
+types stated above.
+\end{description}
+   
+On return the actual values of the arguments will be returned as a field in
+this structure, according to type.
+\begin{verbatim}
+   typedef struct {
+                 char text[80];
+                 int iVal;
+                 float fVal;
+                 } FuPaArg;                
+\end{verbatim}
+
+The whole result is returned in the structure defined below:
+\begin{verbatim}                   
+   typedef struct {
+                    char pError[132];
+                    int iArgs;
+                    FuPaArg  Arg[MAXARG];                 
+                  } FuPaResult;               
+
+\end{verbatim}
+The fields are: \begin{description}
+\item[pError] An error description in case of an error.
+\item[iArgs] the number of arguments actually read.
+\item[Arg] An array of argumnet result structures as defined above.
+\end{description}
+
+Function parsing is done with this function:
+\begin{verbatim}    
+   int EvaluateFuPa(pFuncTemplate pTemplate,int iFunc, int argc, char *argv[],
+                    FuPaResult *pRes);
+\end{verbatim}
+The parameters are:
+\begin{description}
+\item[pTemplate] a parsing template.
+\item[iFunc] The number of functions in the template array.
+\item[argc,argv] The text to parse.
+\item[pRes] A pointer to a retuned result array.                                   
+\end{description}
+The return value is -1 on error, or the number of the template identified on
+success.
+ 
+  
+For more information, look on a usage example in counter.c.
+
+
+