PSI sics-cvs-psi_pre-ansto

doc/programmer/splitter.tex

@@ -0,0 +1,40 @@
+\subsection{The Splitter-Tokenizer}
+ SICS needs some command interpretation for its job. In order to  facilitate this a few functions have been devised which decompose a line into its words and figures out if the words are text or  numerical values. The words are than put into an ordered linked list which can be scanned by client programs. The interface:
+
+
+\begin{verbatim}
+typedef enum {eText, eInt, eFloat, eUndefined } eType;
+\end{verbatim}
+ The Types a word can have.
+
+
+\begin{verbatim}
+typedef struct _TokenEntry {
+                            eType Type;
+                            char *text;
+                            long iVal;
+                            float fVal;
+                            struct _TokenEntry *pNext;
+                            struct _TokenEntry *pPrevious;
+                           } TokenList;
+\end{verbatim}
+ This is the  data structure available for each word. This is kept in a doubly  linked list as SICS might require to splice a parameter into a  given command (i.e a pointer to a connection class).
+
+
+ The interface functions:\begin{itemize}
+\item {\bf TokenList *SplitText(char *pLine) }, splits a given text into words. Returns a pointer to the head of the list on success, NULL on failure.
+\item {\bf TokenList *SplitArguments(int argc, char *argv) }, does the same as above for a argc, argv type pairs.
+\item {\bf Text2Arg(char *text, int argc, cahr *argv) } decomposes a text string into argc, argv paisr as used in command invocation.
+\item {\bf void DeleteTokenList(TokenList *pList) }. A client uses this
+to remove the word list when it is done with it. Omission of this call will result in  wasted memory.
+\item {\bf int Text2Arg(char *line, int *argc, char **argv[])} This call
+converts the text in line into an argc, argv[] pair. Suitable space in
+memory will be allocated. It is the callers responsability to free the
+argv[] array after use.
+\item {\bf int Arg2Text(int argc, char *argv[], char *buf, int iBufLen)}
+This call converts an argc, argv[] pair back into a text. Maximum iBufLen
+characters of result will be copied to buf.
+\item {\bf int GetShellLine(FILE *fd, char *buf, int iBufLen);} reads a line
+from file fd. Thereby ignoring lines starting with \verb+#+. 
+\end{itemize}
+