readme.txt

简单的shell 程序

 this is a implement of a command shell,which is similar to Cisco router console. 
 the project also include example code about how to develop user console application
 with the command shell module.  
 
 
o example project file list

  cmd.c     -  kernel file
  cmd.h     -  macro definition and API function declaraiton
  cmddef.c  -  user commands definition    
  cmddef.h  -  user commands structure declaraiton     
  exec.c    -  user callback functions        
  exec.h    -  user callback functions declaraiton
  iofn.c    -  I/O  routings
  iofn.h    -  I/O  routings declaraiton
  shell.c    - main file
  
  
o what's the structure of the commands?

  commands structure is something like a tree,consisting of four kinds of nodes:
  
  1.token 
  2.token leaf
  3.value
  4.value leaf
  
  token---+---token---token leaf
          |    
          +---token---value---value leaf  
  
  here is a example:
  
  ip---+---show---address
       |
       +---set---<address>---<subnet mask>
      
  actually,it's two commands:
  ip show address
  ip set <address> <subnet mask>
  
  so you may build more complicated commands according to the rule.
  
  
o what's the rule?

  rule 1: each commad should have a leaf.
  
          token---token (end)              <--- error    
          token---token---token leaf (end) <--- OK
          token---value---value (end)      <--- error       
          token---value--value leaf (end)  <--- OK
  

  rule 2: "value" or "value leaf" should begins with "token".
  
           value---value leaf (end)         <--- error
           token---value---value leaf (end) <--- OK 
           token---value leaf (end)         <--- OK 
  
  
  rule 3: value(or value leaf) and token(or token leaf) should not be in one level.
  
          ---+---token---       
             |             <--- error
             +-- value---
  
  
  rule 4: value and value leaf should be alone in any level.
  
          ---value---value---value---value leaf     <---OK
           
          ---+---value---       
             |             <--- meaningless
             +-- value---
   
  
 
o how to built commands?  
  
  use macro defined in cmd.h
   
  BEGIN_CMD_DEFINE(cmd_1)
   
   ...
   
  END_CMD_DEFINE  
  
  "..."  consists of following maros,according to the rule.
  
  IMPLEMENT_CMD_TOKEN(NAME,TIP,NEXT)
  
  IMPLEMENT_CMD_TOKEN_LEAF(NAME,TIP,FUNC)
  
  IMPLEMENT_CMD_VALUE(NAME,TIP,NEXT)
  
  IMPLEMENT_CMD_VALUE_LEAF(NAME,TIP,FUNC)
  
  
  "cmd_1" should be declared in the head file:
  DECLEAR_CMD(cmd1)
  

o what about user callback functions?  

  there are two kinds of user callback functions,one is for "token leaf"
  the other is for "value leaf",
  
  1. void token_func(int argc,char *argv[])
  
  the args here is not much useful,just include all of the user arguments,for instance:
  here is "ip show address".
  then the args will be made of "ip show address".
   
  2. void value_func(int argc,char *argv[])
  
  the args here is the values that we need, for instance:
  here is "ip set  199.36.57.66  255.255.255.0".
  then the args will be made of "199.36.57.66  255.255.255.0".
  but we don't check whether it's valid.


o user API functions

  1. void cmd_root_set(struct cmd *root)
  
  user must call this function to specify the root of the commands,in another word,
  the start point of the commands.
  
  tip:this function also provides the possibility of changing the root of commands in runtime. 
   
  2. int cmd_process(int argc,char *argv[])
  
  this function is a user API for processing the arguments. 
  the arguments should be in "agrc-argv" format. 
  
  
o advice

  if you want to develop your own console application,you may take these steps:
  
  step 1: design your commands structure. implement it in cmddef.c and cmddef.h.
  step 2: implement user callback functions in exec.c and exec.h
  step 3: use cmd_root_set() and cmd_process() to build the main body of applicatin.
  
  
o note

  this is a freeware,you can copy or modify it. but you should keep the author information.
  if you have new ideas or suggestions, or find some bugs, please do not hesitate to contact
  me over e-mail: 
  
  [e-mail]

---------------
如果有问题，请联系[e-mail]  我将提供技术支持。
如果地点在上海，可以考虑现场技术支持。