Defining the command tree: the XML tree file

The XML tree file

The first step to create your own CLI, is to define the command tree, that represent the relation between the contexts and the available commands in each context.
The way to to that is to define a XML tree structure file.

The rules to follow are:

• the root of the tree has to be a context, that we will call main context. This is indeed the context you enter as soon as you run your CLI application
• every context must be parent of at least one command
• every command can parent of zero or any number of subcommands, that are represented as normal command tags
• every command (or subcommand) can have zero or any number of parameters, but up to only one default parameter
• a new context has to be the child node of a command. This means that, in order to enter the new context, its parent command has to be executed
• a parameter does not have children nodes, and its parent is always a command

In a few words:

• a context is a container of commands
• commands can have parameters, subcommands and subcontexts, recursively
• parameters do not have children
• the root of the tree is the main context

Attributes

Contexts, commands and parameters require addtional attributes, that are needed to specify the information about the relevant objects

Attributes for Contexts

• prompt: the prompt to be displayed when the CLI is running in this context

Attributes for Commands

• name: the command name, used to identify the command, and also the string to be used at runtime to call this command
• brief: a brief one line explanation of the command, to be displayed in the command list view and full help view
• help: a complete explanation of the command, to be displayed in the full help view only
• function: the name of the C function that will be called when the command gets executed (user callback)

Attributes for Parameters

• name: the parameter name, used to identify the parameter, and also the string to be used at runtime to specify this parameter
• required: this attribute indicates whether this parameter is mandatory to process the command. Possbile values are "true" or "false"
• numval: the number of strings, typed aftet the parameter name, to be passed at runtime to the C callback as values of the specific parameter
• reqval: this attribute indicates whether theparameter's values are mandatory to process the command. Possbile values are "true" or "false"

IMPORTANT NOTE ON PARAMETERS
As mentioned, every command could have up to one default parameter. If you want to specify it, you have to create a parameter without the name tag. Please remember that every command can have only one default parameter!

Representing the tree as an XML file

Contexts

The structure of a context looks like this:

<context>
    <prompt>myprompt</prompt>
    <command>
        ***
    </command>
    ...
    <command>
        ***
    </command>
</context>

The dots (...) are there to show that every context can have one or more commands

The stars (***) are there to show that every command has its own XML internal structure, that we are not showing here

The only attribute defined here is the prompt. When the CLI is running in this context, the prompt that will be shown is myprompt

myprompt>

Commands

For commands things are a bit more complicated.

Let's start with simple things. The structure of the simplest command, that in fact does NOT have any subcommand and any parameter, looks instead like this:

<command>
    <name>cmdname</name>
    <brief>cmdbrief</brief>
    <help>cmdhelp</help>
    <function>cmdfunction</function>
</command>

So when we are in the context where this command is defined, to call this command you have to type its name, that is cmdname in this case.

myprompt> cmdname

And, as a result of calling this function, the callback cmdfunction will be called.

In case the command as some parameters, the structure will be very similar:

<command>
    <name>cmdname</name>
    <brief>cmdbrief</brief>
    <help>cmdhelp</help>
    <function>cmdfunction</function>
    <param>
        ***
    </param>
    ...
    <param>
        ***
    </param>
</command>

Again, a command may have zero, one or more parameters.

One more step ahead: a command with NO parameters, but with some subcommands.

<command>
    <name>cmdname</name>
    <brief>cmdbrief</brief>
    <help>cmdhelp</help>
    <function>cmdfunction</function>
    <command>
        <name>subcmd1name</name>
        <brief>subcmd1brief</brief>
        <help>subcmd1help</help>
        <function>subcmd1function</function>
    </command>
    ...
        <command>
        <name>subcmd2name</name>
        <brief>subcmd2brief</brief>
        <help>subcmd2help</help>
        <function>subcmd2function</function>
    </command>
</command>

How many commands do we have here? Easy: three. What is different is HOW you can call these two commands. If you type

myprompt> cmdname

you are obviously calling the command cmdname. But if you type

myprompt> cmdname subcmd1name

you are calling subcmd1name. That means that, in order to call a subcommand, you have to type both the main command name and the internal command name as well.

Parameters

Structure of parameters is very simple:

<param>
    <name>paramname</name>
    <required>true/false</required>
    <numval>num</numval>
    <reqval>true/false</reqval>
</param>

• name is the parameter's name, that is used at runtime what parameter you want to pass to the callback
• required is a boolean value (true or false) to indicate whether this parameter is mandatory to execute the relevant command
• numval is the number of values expected at runtime after specifying the parameter name
• reqval indicates whether the value is mandatory as well

If a parameter is required does not mean that its value is required as well, and vice versa.

As already mentioned earlier, every command supports one optional default parameter that, differently from all the other parameters, does not have a name, and if defined, the very first word after the command name will be interpreted at runtime as the value of the default parameter. A default parameter is specified by creating a parameter without a name:

<param>
    <required>true/false</required>
    <numval>num</numval>
    <reqval>true/false</reqval>
</param>

Putting all together

Work in progress