You are here: Home Documents Making a command (#2)

Making a command (#2)

Making a command #2 : simple option


Adding a command and Making a command (#1) uses very simple hello command as an example. In this document, we explain about command option.
Here is a quote command that has four options. This command says something according the specified option as follows;

localhost>quote vader 
It is your destiny.


There are 4 options. harry, vader, solo and smith. These options are exclusive each other and user needs to select zero or one option as follows;

quote harry
quote vader
quote solo
quote smith


So totally we have 5 possibilities as the command and option combination. We make it here with CliParser.OrRule() function.


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

bash-3.2# cat -n 
1 import BasicCli, CliParser
3 tokenQuote = CliParser.KeywordRule( 'quote', helpdesc='Quote a nice phrase from a movie.' )
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' )
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"
21 BasicCli.UnprivMode.addCommand( ( tokenQuote, [ '>>who', quoteOpt ], quoteCompat ) )

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.



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


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 ?

localhost>quote vader
It is your destiny.



OrRule() and KeywordRule() functions are implemented in /usr/lib/python2.5/site-packages/ 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.