Making a command (#1)

Making a command #1 : token registration

Token

We show a document Adding a command to the system. Just write a Python program which includes command registration process and locate it in CliPlugin directory. New command will be available at the CLI which starts after that process.

In this document, we explain detail structure and variations of the token using HelloCli.py as an example as follows;

bash-3.2# cat -n HelloCli.py
     1    import BasicCli, CliParser
     2    tokenHello = CliParser.KeywordRule( 'hello', helpdesc='Says hello' )
     3    def doHello( mode ):
     4        print "World.\n"
     5    BasicCli.UnprivMode.addCommand( ( tokenHello, doHello ) )
bash-3.2#

This program does;

1: it imports the minimum classes such as BasicCli, CliParser,
2: then makes a token with the name "hello" and the help message,
3: and makes a callback function doHello( ), it will be called when user types hello command on EOS CLI
4: but the body of doHello( ) function is simply printing a string "World".
5: finally, it registers the token and callback function pair to non-privilege mode.

In this context, the term "token" means the word to pick out from command string. Adding a token does mean adding a command to EOS CLI.

Rule

But you can guess from the name of CliParser.KeywordRule( ), this "token" is also handled as the "rule". So token is structured by a word picked out from command string and a rule which describes the relation to the other token. You can see the CliParser.py program in site-packages directory and it includes Rule class which defines several types of rule functions, such as KeywordRule( ) and more.

Rule defines acceptable combination of command and arguments or parameters. If the combination is broken, CLI does accept that command line. CLI has Rule tree for each command modes. So Rule itself has Rule sub-tree which works as a parsing tree for syntax analysis.

We show available functions which defined in Rule class in the other document. (not available yet, just a moment.)

Register to the top level

enable and non-priviledge mode

There are two variations to register a command to the top level.

BasicCli.EnableMode.addCommand( ( tokenHello, doHello ) )
BasicCli.UnprivMode.addCommand( ( tokenHello, doHello ) )

The first case, command will be appeared only privilege mode (EnableMode). The command is limited to privileged user only.

The next case, command will be appeared both of non-privilege mode (UnprivMode) and privilege mode.

Hidden command

It is possible to register your command without any help guidance at EOS CLI (with ? key) or tab key completion assistance. It means there is no way to discover that command for other users. It will be a hidden command. To make it, wrap the rule by CliParser.HiddenRule( ) then do addCommand( ). Here is how to do that for privilege mode and non-privelege mode registration.

BasicCli.EnableMode.addCommand( CliParser.HiddenRule( tokenHello, doHello ) )
BasicCli.UnprivMode.addCommand( CliParser.HiddenRule( tokenHello, doHello ) )

Register to the SHOW command

There is a function to add a command to show command too.

It is possible to add your own token (and rule) to show command token (and rule). It means you add a branch or sub-tree to the show command rule tree.

SHOW HELLO

For example, we add show hello command. Make ShowHelloCli.py program as follows and locate it to /usr/lib/python2.5/site-packages/CliPlugin directory.

import BasicCli, CliParser
def showHello( mode ):
    print "Hello World.\n"
tokenHello = CliParser.KeywordRule( 'hello', helpdesc='Show your hello' )
BasicCli.registerShowCommand( tokenHello, showHello )

Only BasicCli.registerShowCommand( ) function is different from the first example. It just registers a command as "show hello" command. Here is a execution result. You can see it on EOS CLI and it also reacts the "?" key input after "show" command.

localhost>show ?
...
  hello                 Show your hello
....
localhost>show hello ?
  |     Output modifiers
  <cr>
localhost>show hello
Hello World.

localhost>

Registration as a privilege command

To register as a privileged show command, add "privileged=True" argument as follows;

BasicCli.registerShowCommand( tokenHello, showHello, privileged=True )

Registration as a hidden command

To register as a hidden show command, add "hidden=True" argument as follows;

BasicCli.registerShowCommand( tokenHello, showHello, hidden=True )

If you want to set both privileged and hidden attribute, just set both parameters.

Implementation

To see how works privileged or hidden parameter in registerShowCommand( ) function, check registerShowCommand( ) implementation at BasicCli.py. It includes very informative code and comments. One of good entrances to the inside of the box.

Sections