From: Michal Sojka <sojkam1@fel.cvut.cz>
Date: Wed, 31 Jul 2013 07:01:01 +0000 (+0200)
Subject: Add more comments to the command processor
X-Git-Url: http://rtime.felk.cvut.cz/gitweb/sysless.git/commitdiff_plain/f44cc3fb374bfa4e8b4d92f77631ff52bfdcc15b?hp=46a6e1bfec7b50b1dd836a89830421c7244dd564

Add more comments to the command processor
---

diff --git a/libs4c/cmdproc/cmd_proc.c b/libs4c/cmdproc/cmd_proc.c
index c6de7e9..fe667b7 100644
--- a/libs4c/cmdproc/cmd_proc.c
+++ b/libs4c/cmdproc/cmd_proc.c
@@ -35,6 +35,11 @@ char *skip_white(char *p)
 }
 
 /**
+ * Process a command line
+ *
+ * @param cmd_io I/O stack
+ * @param des_arr Pointer to the command descriptors.
+ * @param line Command line to process.
  *
  * @return Zero if no command was given in line, -CMDERR_BADCMD if
  * command is not known or has no function assigned to it. If a
@@ -90,26 +95,27 @@ int proc_cmd_line(cmd_io_t *cmd_io, cmd_des_t const **des_arr, char *line)
     var=NULL;
     while(*r){
       while((*p==*r)&&i){i--;r++;p++;};
-      if((i==0)&&!*r) break;    /* We've found the command */
-      if((*r=='?')&&i){
+      if((i==0)&&!*r) break;    /* We've found the command (full match) */
+      if((*r=='?')&&i){		/* '?' stands for an arbitrary character */
         if(!var) var=p;
 	p++; r++; i--;
 	continue;
       }
-      if((*r=='#')&&i&&isdigit((uint8_t)*p)){
+      if((*r=='#')&&i&&isdigit((uint8_t)*p)){ /* '#' stands for a digit */
 	if(!var) var=p;
 	p++; r++; i--;
 	continue;
       }
-      if(*r=='*'){
+      if(*r=='*'){		/* '*' stands for any number of any characters */
 	if(!var) var=p;
 	i=0;
 	break;
       }
-      i=1;
+      i=1;			/* Signal no match */
       break;      
     }
     if(i!=0) continue; /* Try next command */
+    /* Setup parameters */
     if(des->mode&CDESM_OPCHR){
       if(!param[2])continue;
       if(!*param[2])continue;
diff --git a/libs4c/cmdproc/cmd_proc.h b/libs4c/cmdproc/cmd_proc.h
index 64af4df..18e2a21 100644
--- a/libs4c/cmdproc/cmd_proc.h
+++ b/libs4c/cmdproc/cmd_proc.h
@@ -113,10 +113,34 @@ int cmd_io_read_bychar(cmd_io_t *cmd_io,void *buf,int count);
 #define CDESM_WR	0x02	/* Value write is possible */
 #define CDESM_RW	(CDESM_RD|CDESM_WR) /* Both */
 
+/**
+ * Command descriptor.
+ *
+ * Command name may contain the following wildcards:
+ * - '?' stands for one arbitrary character
+ * - '#' stands for one digit
+ * - '*' stands for any number of arbitrary characters at the end of the command
+ *
+ * The fnc() function is passed the following information as the param array:
+ *   - param[0] points to the command (the longest sequence of alphanumeric characters)
+ *   If CDESM_OPCHR is specified in the command descriptor then
+ *   - param[1] points to the first wildcard in the command or is NULL for commands without wildcard in the name
+ *   - param[2] points to the operation character (':' or '?') and
+ *   - param[3] points to the string after the operation character (after skipping whitespace)
+ *   If CDESM_OPCHR is not specified then
+ *     If the command name contains a wildcard,
+ *     - param[1] points to the first wildcard in the command and
+ *     If the command has any parameters
+ *     - param[1] or param[2] (depending on the presence of a wildcard)
+ *       points to the beginning of those parameters (after skipping
+ *       whitespace)
+ *
+ *   The param elements are always terminated by NULL element.
+ */
 typedef struct cmd_des{
-  int code;
-  int mode;
-  char *name;
+  int code;			/* Application specific code */
+  int mode;			/* CDESM_* constants */
+  char *name;			/* Name of the command with possible wildcards */
   char *help;
   int (*fnc)(cmd_io_t *cmd_io, const struct cmd_des *des, char *param[]);
   char *info[];