Making a command (#2)

Code

Here is a quote command program. For detail instruction to make this Quote.py program file on the system, see  Adding a command document.

bash-3.2# cat -n Quote.py 
     1	import BasicCli, CliParser
     2	
     3	tokenQuote = CliParser.KeywordRule( 'quote', helpdesc='Quote a nice phrase from a movie.' )
     4	
     5	quoteOpt = CliParser.OrRule() 
     6	quoteOpt |= CliParser.KeywordRule( 'harry', helpdesc='Inspector Harry Callahan' ) 
     7	quoteOpt |= CliParser.KeywordRule( 'vader', helpdesc='Lord Vader' ) 
     8	quoteOpt |= CliParser.KeywordRule( 'solo', helpdesc='Captain Han Solo' ) 
     9	quoteOpt |= CliParser.KeywordRule( 'smith', helpdesc='Agent Smith' ) 
    10	
    11	def quoteCompat( mode, who ): 
    12	   if who == 'harry' or who is None:
    13	      print "I know what you are thinking.\n"
    14	   elif who == 'vader':
    15	      print "It is your destiny.\n"
    16	   elif who == 'solo':
    17	      print "Uh, uh, negative, negative. We had a reactor leak here now.\n"
    18	   elif who == 'smith':
    19	      print "Mr. Anderson. Welcome back. We missed you.\n"
    20	
    21	BasicCli.UnprivMode.addCommand( ( tokenQuote, [ '>>who', quoteOpt ], quoteCompat ) )
bash-3.2#

This program is;

1: it imports the minimum classes such as BasicCli, CliParser,
3: then makes a token with the name "quote" and the help message,
5: and makes a rule for options by OrRule( ) function. Initially, it has empty OrRule instance. 
6: and makes a token by KeywordRule( ) with "harry" keyword (it will be a option name) with help string for this option. Then add this rule to the current rule by |= operator.
7-9: And makes tokens for vader, solo, smith options too, then add them by |= again. 
11: it makes a callback function for quote command. The 2nd argument (who) receives given option. 
12-19: According to 2nd argument (who), it traverses the if judgments. If there is no option, it falls on line 13 by default. (see "who is None" condition)
21: Finally, it adds a command as non-privelege command by addCommand() function. The quote command will be registered to CLI with options. When user do "quote" command, CLI will call quoteCompat( ) function with "who" variable. The value of "who" variable should have the specified keyword as a value (it is option string).

addCommand() function

addCommand() has 3 arguments as follows;

1st argument

command name ("quote") and help string to register


2nd argument

ruleset (tokenQuote), it holds some rulesets by making OrRule( ). It is the option info. The "who" variable is also passed.

3rd argument

quote command body (callback function). It can access "who" variable to see what is the specified option. (given word)

In this example, arguments only limited 3 but it is more expandable. For example, if N arguments are given to addCommand(), the 1st argument works as the 1st which described above. The last argument works as the 3rd role of above. The rest "2nd to (N-1)th" arguments works as the 2nd role of above.

For your information, we showed only 2 argumets case of addCommand( ) function in Adding a command (#1). It is also acceptable.

Behavior

quote command is running thorough like follows;

1. when quote command is executed by user, CLI calls quoteCompat() function with "who" variable. The value of it shows which keyword did matched as an option.
2. If user executes quote command without any option, "who" variable has None value then the condition of line 12 matches true and fall into line 13. It does mean the default option.
3. If user executes with option such as "quote harry" or "quote vader", program branches depends on the value of "who" variable and so on.
4. It is not acceptable for CLI to specify multiple options such as "quote harry vader". It will be rejected by CLI, so quoteCompat( ) function will not be called back.

Help messages are also shows in context sensitive by CLI automatically as follows;

Help message by ? typing
When press ? key just after quote command, help messages will be showed like this;

localhost>quote ?
  harry  Inspector Harry Callahan
  smith  Agent Smith
  solo   Captain Han Solo
  vader  Lord Vader
  <cr>   

localhost>

Please look at the order of the lines. The help messages of options will be displayed in alphabetical order, not the registration order. 

TAB completion
When user types "quote va" then press TAB key, CLI will try to complete the command line.  After the completion succeed, if user press ? key, CLI shows only return key is available at the situation.

localhost>quote va    
localhost>quote vader ?
  <cr>  

localhost>quote vader 
It is your destiny.

localhost>

Implementation

OrRule() and KeywordRule() functions are implemented in /usr/lib/python2.5/site-packages/CliParser.py file. There are some valuable comments too.

next step

This example accepts no-option case. User can see it when type "quote ?". The help messages includes <cr> (just type return key without any option).

We are going to explain about the tree structure of the command token which does not accept no-option case.