The basics

CLIck: the basics

The idea behind CLIck is to take the exact opposite strategy of GNU readline.

Readline is a complex framework, that gives the basic tools to make even crazy things in a 100% flexible way, but requires the user to do most of the job and the coding as well.

There is no automatic structure generation, in fact there is no structure at all, as the user can do whatever he wants.

CLIck is very different: it gives a pre-built flexible and customizable engine that takes care of almost everything is needed to implemente the desired CLI, leaving to the user the only task of defining the layout in a text (XML) file, and letting CLIck code generator make the rest of the job. It's fair enough to claim that CLIck is very focused on a specific style of CLI, but in a very flexible way, with the purpose of unloading the user from all the extra effort.

CLI structure: contexts, commands and sub-commands

CLIck is based on a context tree, where each context has a predefined set of commands and a custom prompt. So to better clarify, different commands in different contexts.

Everything is derived from the main context (root context), and moving around contexts is easy to do. Every context has its own prompt and command list, so it's easy to understand where you are.

Commands can also be organized in trees, so giving the ability of defining subcommands within the same command.

The following picture shows the generic structure of the Context tree

Here some definitions:

• a Command is a single command that can be executed by the CLI when its name is typed in the relevan context
• a Context is a container of commands, and it is used to have different views of available commands
• s Subcommand is a specialization of a parent command, and gives the user the possibilities of adding more information about the specific sub-function that the user wants to use.

Each of the entities above require additional information to be defined:

• A Context requires a prompt to be displayed when execution is in that context
• A Command or a sub-command requires a name, a brief description of the command, a complete description of the command usage, and a callback to be called to execute the command action.

Here follow some rules:

• in a specified context, only commands (and related subcommands) that are directly contained in that context are available
• every context contains implicitly the following default commands, that do not have to be specified in the command tree:
  • exit: exit from the current context
  • end: go back to the main context
  • bye: terminate the CLI application
• navigate from a context to another is achievable by executing commands:
  • going down the tree: execute the command or subcommand that connects the new context
  • going up the tree: execute the exit command
  • going to the main context: execute the end command

Commands and sub-commands are treated exactly the same way, so starting from now this Wiki will refer to both entities with the more generic term "command", unless explicitly clarified.

Parameters

Commands can be enriched with parameters, that represent the input data to be given to a specific command.
For example, say you have a command named call, you can add the parameter number to specify what number to call.

In that case, your command would look like the following:

prompt> call number 01234567

In this case, the parameter name is "number", and it would require one value to be indicated at runtime after the parameter name, that is actually the number to be called.
Every command can have zero, one or multiple parameters associated.
For every parameter, the CLI designer has to specify whether it is a mandatory parameter: in that case, the CLI user has to specify the parameters and its associated value in order to run the related command.
There is no limitation on the number of parameters that can be defined for a command.

There is also possibility to have, for each command, a default parameter, that does not require a parameter name. The first string after the command itself will be interpreted as the default parameter.
Every command might have up to one default parameter; when calling the command, it has to be the very first parameter.

Back to the call example, if instead of defining a parameter named number we assume that the number is the default parameter, the command would then look like:

prompt> call 01234567