/* cmdParser.c - Command line parser routines. *//* Copyright 2000 Wind River Systems, Inc. *//*Modification history--------------------01f,18sep01,wef  merge from wrs.tor2_0.usb1_1-f for veloce, fixed formatting01e,08aug01,dat  Removing warnings01d,31jul01,wef  fix man page generation errors01c,23nov99,rcb  Make KeywordMatch() function public.01b,16aug99,rcb  Add option in CmdParserHelpFunc to display help only for		 a specific command.01a,01jun99,rcb  First.*//*DESCRIPTIONThis file includes a collection of command-line parsing functions which areuseful in the creation of command line utilities, such as bus exercisers.There are three groups of functions defined by this library.  The first isa collection of general string parser functions, such as functions to eliminatewhite space, functions to strip tokens out of a string, and so forth.  The second set of functions drive the actual parsing process.  In order to use this second set of functions, clients must construct a table of CMD_DESCRstructures which define the commands to be recognized by the parser.  A brief example of such a table is shown below..CSCMD_DESCR Commands [] =    {    {"Help", 4, "Help/?", "Displays list of commands.", CmdParserHelpFunc},    {"?",    1, NULL,	  NULL, 	    CmdParserHelpFunc},    {"Exit", 4, "Exit",   "Exits program.",	CmdParserExitFunc},    {NULL,   0, NULL,	  NULL, 	    NULL}    };.CEThe first field is the keyword for the command.  The second field specifiesthe number of characters of the command which must match - allowing the userto enter only a portion of the keyword as a shortcut.  The third and fourthfields are strings giving the command usage and a brief help string.  A NULLin the Help field indicates that the corresponding keyword is a synonym for another command its usage/help should not be shown.  The final field is a pointer to a function of type CMD_EXEC_FUNC which will be invoked if the parser encounters the corresponding command.The third group of functions provide standard CMD_EXEC_FUNCs for certaincommonly used commands, such as CmdParserHelpFunc and CmdParserExitFunc asshown in the preceding example.The caller may pass a generic (pVOID) parameter to the command line parsingfunctions in the second group.	This function is in turn passed to theCMD_EXEC_FUNCs.  In this way, the caller can specify context informationfor the command execution functions.Commands are executed after the user presses [enter].  Multiple commands may be entered on the same command line separated by semicolons (';').  Each command as if it had been entered on a separate line (unless a command terminates with an error, in which case all remaining commands entered on the same line will be ignored).*//* Include files */#include "stdio.h"#include "stdlib.h"#include "string.h"#include "ctype.h"#include "usb/usbPlatform.h"	    /* Basic definitions */#include "usb/tools/cmdParser.h"    /* Our API *//* Constants */#define PAUSE_DISPLAY	    22	    /* Help display pauses every n lines *//*************************************************************************** PromptAndExecCmd - Prompt for a command and execute it.** Displays <pPrompt> to <fout> and prompts for input from <fin>. Then, * parses/executes the command.	<pCmdTable> points to an array of* CMD_DESCR structures defining the command to be recognized by the* parser, and <Param> is a generic parameter passed down to individual * command execution functions.** RETURNS:  RET_OK for normal termination*	RET_ERROR for program failure.*	RET_CONTINUE if execution should continue.*/UINT16 PromptAndExecCmd    (    pVOID param,	/* Generic parameter for exec funcs */    char *pPrompt,	/* Prompt to display */    FILE *fin,		/* Input stream */    FILE *fout, 	/* Output stream */    CMD_DESCR *pCmdTable    /* CMD_DESCR table */    )    {    char cmd [MAX_CMD_LEN]; /* Buffer for input command */    /* Display prompt */    fprintf (fout, pPrompt);    /* Retrieve input */    if (fgets (cmd, sizeof (cmd), fin) != cmd)        return RET_ERROR;    /* Execute input */    return ExecCmd (param, cmd, fin, fout, pCmdTable);    }/*************************************************************************** KeywordMatch - Compare keywords** Compares <s1> and <s2> up to <len> characters, case insensitive.  * Returns 0 if strings are equal.  ** NOTE: This function is equivalent to strnicmp(), but that function is* not available in all libraries.** RETURNS:  0 if s1 and s2 are the same*	-n if s1 < s2*	+n if s1 > s2*/int KeywordMatch    (    char *s1,		    /* string 1 */    char *s2,		    /* string 2 */    int len		/* max length to compare */    )    {    int n = 0;    for (; len > 0; len--)	{	if ((n = toupper (*s1) - toupper (*s2)) != 0 || *s1 == 0 || *s2 == 0) 	    break;	s1++;	s2++;	}    return n;    }/*************************************************************************** ExecCmd - Execute the command line** Parses and executes the commands in the <pCmd> buffer.  I/O - if any -* will go to <fin>/<fout>.  The <pCmd> may contain any number of commands* separated by CMD_SEPARATOR. <pCmdTable> points to an array of* CMD_DESCR structures defining the command to be recognized by the* parser, and <param> is a generic parameter passed down to individual * command execution functions.** RETURNS:  RET_OK for normal termination.*	RET_ERROR for program failure.*	RET_CONTINUE if execution should continue.*/UINT16 ExecCmd    (    pVOID param,	/* Generic parameter for exec funcs */    char *pCmd, 	/* Cmd buffer to be parsed/executed */    FILE *fin,		/* Stream for input */    FILE *fout, 	/* Stream for output */    CMD_DESCR *pCmdTable    /* CMD_DESCR table */    )    {    UINT16 s = RET_CONTINUE;	    /* Execution status */    char keyword [MAX_KEYWORD_LEN]; /* Bfr for command keyword */     CMD_DESCR *pEntry;		/* Pointer to entry in CmdTable */    /* Parse each command on the command line. */    TruncSpace (pCmd);    do	{		/* Retrieve keyword and match against known keywords. */	pCmd = GetNextToken (pCmd, keyword, sizeof (keyword));	if (strlen (keyword) > 0)	    {	    for (pEntry = pCmdTable; 		 pEntry != NULL && pEntry->keyword != NULL;		 pEntry++)		{		if (KeywordMatch (pEntry->keyword, 				  keyword, 				  max (strlen (keyword), 				       (unsigned)pEntry->minMatch))			       == 0)		    {		    /* 		     * We found a matching keyword.  Execute the CMD_EXEC_FUNC		     * for this command. 		     */		    if (pEntry->execFunc == CmdParserHelpFunc)			s = (*pEntry->execFunc) (pCmdTable, &pCmd, fin, fout);		    else			s = (*pEntry->execFunc) (param, &pCmd, fin, fout);		    break;		    }		}	    if (pEntry == NULL || pEntry->keyword == NULL)		{		fprintf (fout, "Unrecognized command: %s\n", keyword);		break;		}	    }	/* Skip over trailing CMD_SEPARATOR characters. */	if (*pCmd != CMD_SEPARATOR)	    while (*pCmd != CMD_SEPARATOR && *pCmd != 0)		pCmd++;	while (*pCmd == CMD_SEPARATOR)	    pCmd++;	}	while (strlen (pCmd) > 0 && s == RET_CONTINUE);    return s;    }/*************************************************************************** SkipSpace - Skips leading white space in a string** Returns a pointer to the first non-white-space character in <pStr>.** RETURNS: Ptr to first non-white-space character in <pStr>*/#define IS_SPACE(c) (isspace ((int) (c)) || ((c) > 0 && (c) < 32))char *SkipSpace     (    char *pStr		/* Input string */    )    {    while (IS_SPACE (*pStr))	pStr++;    return pStr;    }/*************************************************************************** TruncSpace - Truncates string to eliminate trailing whitespace** Trucates <pStr> to eliminate trailing white space.  Returns count* of characters left in <pStr> upon return.** RETURNS: Number of characters in <pStr> after truncation.*/UINT16 TruncSpace     (    char *pStr		/* Input string */    )    {    UINT16 len;    while ((len = strlen (pStr)) > 0 && IS_SPACE (pStr [len - 1]))	pStr [len - 1] = 0;    return len;    }/*************************************************************************** GetNextToken - Retrieves the next token from an input string** Copies the next token from <pStr> to <pToken>.  White space before the* next token is discarded.  Tokens are delimited by white space and by* the command separator, CMD_SEPARATOR.  No more than <tokenLen> - 1* characters from <pStr> will be copied into <pToken>.	<tokenLen> must be* at least one and <pToken> will be NULL terminated upon return.** RETURNS: Pointer into <pStr> following end of copied <pToken>.*/char *GetNextToken     (    char *pStr, 	/* Input string */    char *pToken,	/* Bfr to receive token */    UINT16 tokenLen	/* Max length of Token bfr */    )    {    UINT16 len; 	/* Temporary length counter */    /* Skip leading white space */    pStr = SkipSpace (pStr);    /* Copy next token into Token bfr */    pToken [0] = 0;    while ((len = strlen (pToken)) < tokenLen && 	   *pStr != 0 && 	   !IS_SPACE (*pStr) && 	   *pStr != CMD_SEPARATOR)	{	pToken [len] = *pStr;	pToken [len+1] = 0;	pStr++;	}    return pStr;    }/*************************************************************************** GetHexToken - Retrieves value of hex token** Retrieves the next token from <pCmd> line, interprets it as a hex * value, and stores the result in <pToken>.  If there are no remaining * tokens, stores <defVal> in <pToken> instead.** RETURNS: Pointer into <pStr> following end of copied <pToken>*/char *GetHexToken    (    char *pStr, 	/* input string */    long *pToken,	/* buffer to receive token value */    long defVal 	/* default value */    )    {    char temp [9];	/* Temp storage for token */    /* Retrieve next token */    pStr = GetNextToken (pStr, temp, sizeof (temp));    /* Evaluate Token value */    if (strlen (temp) == 0 || sscanf (temp, "%lx", pToken) == 0)	*pToken = defVal;    return pStr;    }/*************************************************************************** CmdParserHelpFunc - Displays list of supported commands** Displays the list of commands in the parser command table to <fout>.	* When the parser recognizes that this function is about to be executed, * it substitutes a pointer to the current CMD_DESCR table in <param>. * If this function is called directly, <param> should point to a table* of CMD_DESCR structures.** RETURNS: RET_CONTINUE*/UINT16 CmdParserHelpFunc    (    pVOID param,	    /* Generic parameter passed down */    char **ppCmd,	    /* Ptr to remainder of cmd line */    FILE *fin,		    /* stream for input (if any) */    FILE *fout		    /* stream for output (if any) */    )    {    CMD_DESCR *pCmdTable = (CMD_DESCR *) param;    char keyword [MAX_KEYWORD_LEN];    int lines = 0;    *ppCmd = GetNextToken (*ppCmd, keyword, sizeof (keyword));    if (strlen (keyword) == 0)	fprintf (fout, "\n");    for (; pCmdTable != NULL && pCmdTable->keyword != NULL; pCmdTable++) 	{	if (pCmdTable->help != NULL) 	    {	    /* If a parameter has been entered, display help only for 	     * matching cmds */	    if (strlen (keyword) > 0)		if (KeywordMatch (pCmdTable->keyword, 				  keyword, 				  max (strlen (keyword), 				       (unsigned)pCmdTable->minMatch)) 				 != 0)		    continue;	    /* Pause the display every PAUSE_DISPLAY lines */	    if (lines == PAUSE_DISPLAY) 		{		fprintf (fout,	 "[Press a key to continue]");		fgetc (fin);		fprintf (fout, "\r		\r");		lines = 0;		}	    fprintf (fout, "%*s  %s\n", 		     (strlen (keyword) == 0) ? 22 : 0,		     (pCmdTable->usage == NULL) ? 				pCmdTable->keyword : pCmdTable->usage, 		     pCmdTable->help);	    ++lines;	    }	}    if (strlen (keyword) == 0)	fprintf (fout, "\n\n");    return RET_CONTINUE;    }/*************************************************************************** CmdParserExitFunc - Terminates parser execution** Returns RET_OK, causing the parser to return RET_OK to the caller* signally normal termination of the parser.** RETURNS: RET_OK*/UINT16 CmdParserExitFunc    (    pVOID param,	    /* Generic parameter passed down */    char **ppCmd,	    /* Ptr to remainder of cmd line */    FILE *fin,		    /* stream for input (if any) */    FILE *fout		    /* stream for output (if any) */    )    {    return RET_OK;    }/* End of file. */