CLI library user guide

The CLI library can be downloaded from here in the form of gzipped archives.

Regular Linux installs usually have everything needed to have the CLI library compile. If you compile on Windows, you may install cygwin.

Here is a list of required utilities:

Plus, for Java users:

Plus, optionally, for unit tests (make check):

or documentation generation (make doc):

Once you have downloaded the archive, unpack it on your disk:

tar xvfz cli-X.Y.tgz

and declare a CLI_DIR environment variable that points to directory just extracted:

export CLI_DIR=$(pwd)/cli-X.Y

Optionally, set the JAVA_HOME environment variable:

export JAVA_HOME="$(dirname "$(dirname "$(which javac)")")"

Go to build/make:

cd ${CLI_DIR}/build/make

and build:

make

or (debug version):

make _DEBUG=

This compilation will run over C++ and Java (depending on JAVA_HOME value) library compilations.

make check

make _DEBUG= check

Output libraries go in the following directories:

with:

The transformation of the XML resource file into target language code is very easy. It is nothing but a simple transformation.

You may use either the original XSL transformation stylesheets cli2cpp.xsl and cli2java.xsl, or their python tools equivalents cli2cpp.py and cli2java.py. Even though python tools, added in version 2.8, run faster than XSL stylesheets, both techologies are still provided for backward compatibility reasons.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="myCLI">
</cli>

xsltproc ${CLI_DIR}/tools/cli2cpp.xsl empty.xml > empty.cpp

python ${CLI_DIR}/tools/cli2cpp.py empty.xml > empty.cpp

xsltproc --stringparam STR_CliClassName "Empty" ${CLI_DIR}/tools/cli2java.xsl empty.xml > Empty.java

python ${CLI_DIR}/tools/cli2java.py --cli-class-name "Empty" empty.xml > Empty.java

The XSL transformation stylesheets have several parameters:

The python tools come with --help options:

$ python ${CLI_DIR}/tools/cli2cpp.py --help
usage: cli2cpp [-h] [--version] [--cli-class-name CLI_CLASS_NAME]
               [--cli-class-scope CLI_CLASS_SCOPE] [--static | --no-static]
               [--class-prefix CLASS_PREFIX] [--var-prefix VAR_PREFIX]
               [--indent INDENT] [--user-indent USER_INDENT]
               xml-res

positional arguments:
  xml-res               CLI XML resource file

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --cli-class-name CLI_CLASS_NAME
                        Main CLI class name (default is based on <class-
                        prefix> and @name attribute).
  --cli-class-scope CLI_CLASS_SCOPE
                        Main CLI class scope (default is empty).
  --static              Static instance creation
  --no-static           No static instance creation (default)
  --class-prefix CLASS_PREFIX
                        Class prefix (default is empty).
  --var-prefix VAR_PREFIX
                        Variable prefix (default is 'm_pcli_').
  --indent INDENT       Indentation pattern (default is 4 spaces).
  --user-indent USER_INDENT
                        User-code indentation pattern (default is '/* > */ ').

$ python ${CLI_DIR}/tools/cli2java.py --help
usage: cli2java [-h] [--version] [--cli-class-name CLI_CLASS_NAME]
                [--cli-class-scope CLI_CLASS_SCOPE]
                [--class-prefix CLASS_PREFIX] [--var-prefix VAR_PREFIX]
                [--indent INDENT] [--user-indent USER_INDENT]
                xml-res

positional arguments:
  xml-res               CLI XML resource file

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --cli-class-name CLI_CLASS_NAME
                        Main CLI class name (default is based on <class-
                        prefix> and @name attribute).
  --cli-class-scope CLI_CLASS_SCOPE
                        Main CLI class scope (default is empty).
  --class-prefix CLASS_PREFIX
                        Class prefix (default is empty).
  --var-prefix VAR_PREFIX
                        Variable prefix (default is 'm_cli').
  --indent INDENT       Indentation pattern (default is 4 spaces).
  --user-indent USER_INDENT
                        User-code indentation pattern (default is '/* > */ ').

Now that you have your target language file, you want to have a CLI program running don't you?

xsltproc --param STR_CliClassName "'EmptyCli'" ${CLI_DIR}/tools/cli2cpp.xsl empty.xml > empty_cli.h

#include "cli/common.h"
#include "cli/console.h"
#include "empty_cli.h"

int main(void) {
    EmptyCli cli_EmptyCli;
    cli::Shell cli_Shell(cli_EmptyCli);
    cli::Console cli_Console(false);
    cli_Shell.Run(cli_Console);
}

g++ -I${CLI_DIR}/cpp/include -Wno-unused-label -c goempty.cpp
g++ -o empty goempty.o -L${CLI_DIR}/cpp/build/make/Cygwing++/Release -lclicpp -lncurses

./empty

xsltproc --param B_CliStaticCreation 1 ${CLI_DIR}/tools/cli2cpp.xsl empty.xml > empty_cli.cpp

#include "cli/common.h"
#include "cli/console.h"

int main(void) {
    cli::Cli::List cli_List(10);
    const int i_Clis = cli::Cli::FindFromName(cli_List, ".*");
    if (i_Clis == 0)
    {
        fprintf(stderr, "Error: No CLI found.\n");
        return -1;
    }
    else if (i_Clis > 1)
    {
        fprintf(stderr, "Warning: Several CLIs found. Executing only the first one.\n");
    }
    cli::Shell cli_Shell(*cli_List.GetHead());
    cli::Console cli_Console(false);
    cli_Shell.Run(cli_Console);
}

g++ -I${CLI_DIR}/cpp/include -Wno-unused-label -c empty_cli.cpp
g++ -I${CLI_DIR}/cpp/include -c goempty2.cpp
g++ -o empty2 empty_cli.o goempty2.o -L${CLI_DIR}/cpp/build/make/${TARGET}${CXX}/${RDX} -lclicpp -lncurses

./empty2

class GoEmpty {
    public static void main(String ARJ_Args[]) {
        // Load the class.
        cli.Cli cli_Cli = null;
        try {
            Class j_CliClass = Class.forName("Empty");
            cli_Cli = (cli.Cli) j_CliClass.newInstance();
        } catch (Exception e) {
            e.printStackTrace();
            return;
        }
        // Create an I/O device.
        cli.IODevice.Interface cli_Input = new cli.Console();
        // Create a shell.
        cli.Shell cli_Shell = new cli.Shell(cli_Cli);
        // Launch the shell.
        cli_Shell.run(cli_Input);
    }
}

javac -classpath ${CLI_JAVA_DIR}/cli.jar GoEmpty.java Empty.java

java -classpath "${CLI_JAVA_DIR}/cli.jar;." -Djava.library.path=${CLI_JAVA_DIR} GoEmpty

The examples above showed you how to create and launch an empty CLI. Now you want to do more interesting stuff, don't you?

So go to next section.

The root element, named cli, directly defines the CLI. It has only one resource related attribute: name. It obviously gives the name of the CLI.

Keywords and end of lines are the basics of a CLI.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello">
 <keyword string="say">
  <keyword string="hello">
   <endl></endl>
  </keyword>
 </keyword>
</cli>

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello">
 <keyword string="say">
  <keyword string="hello">
   <endl></endl>
  </keyword>
 </keyword>
 <keyword string="shout">
  <keyword string="hello">
   <endl></endl>
  </keyword>
 </keyword>
</cli>

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello">
 <keyword string="say">
  <keyword string="hello">
   <endl></endl>
  </keyword>
  <keyword string="bye">
   <endl></endl>
  </keyword>
 </keyword>
 <keyword string="shout">
  <keyword string="hello">
   <endl></endl>
  </keyword>
  <keyword string="bye">
   <endl></endl>
  </keyword>
 </keyword>
</cli>

Considering certain command lines have keywords in common, like say hello and say bye in the previous example, eventually what you define is a syntax tree. A first node corresponds to the keyword say, which has two children hello and bye. For an illustration of that syntax tree, load the XML file of the last example into your favorite web browser and play with toggles.

Hold on! Next section tells how to do that.

CLI is basically a user interface, so that's a good idea to give help as much as you can. It's easy to do such a thing in XML resource files. help elements can be added to CLI elements to document them. The lang attribute identifies the corresponding language.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello"><help lang="en">Hello menu</help><help lang="fr">Menu Hello</help>
 <keyword string="say"><help lang="en">Say something.</help><help lang="fr">Dire quelque chose.</help>
  <keyword string="hello"><help lang="en">Say hello.</help><help lang="fr">Dire bonjour.</help>
   <endl></endl>
  </keyword>
  <keyword string="bye"><help lang="en">Say goodbye.</help><help lang="fr">Dire au revoir.</help>
   <endl></endl>
  </keyword>
 </keyword>
</cli>

For sure, automatic documentation generation will help you. This feature is described in a later section.

Target language instructions are inserted straight forward in the XML resource file through target language tags:

Basically, these tags are located in endl elements. It allows you to define what is executed when a command line has been successfully parsed.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello">
 <keyword string="say">
  <keyword string="hello">
   <endl>
    <cpp>sayHello();</cpp>
    <java>HelloApi.sayHello();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello">
 <cpp option="include">#include "hello_api.h"</cpp>
 <java option="import">import cli.test.HelloApi;</java>
 <keyword string="say">
  <keyword string="hello">
   <endl>
    <cpp>sayHello();</cpp>
    <java>HelloApi.sayHello();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

cpp and java are not restricted to endl elements. You can attach target code to almost any element of your syntax tree, as shown in examples Syntax tags - An optional command line and Syntax tags - Another optional command line.

Now you may need to print out results. Use the out and err elements for that. Use them like std::cout and std::cerr in C++, and use the cli::endl constant for carriage returns. Use put and endl methods in Java.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Hello">
 <keyword string="say">
  <keyword string="hello">
   <endl>
    <cpp><out/> << "Hello world!" << cli::endl;</cpp>
    <java><out/>.put("Hello world!").endl();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

Special sections have been introduced in the example above. Here is the detail of how they are organized, for C++ generation:

Java sections look the same except for the include section, which is named import in Java.

param elements can be used instead of keyword elements. Obviously, this kind of element controls parameters elements. The CLI library manages different types of parameters:

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Params">
 <keyword string="enter">
  <keyword string="string">
   <param type="string" id="a-string">
    <endl>
     <cpp><out/> << <value-of param="a-string"/> << cli::endl;</cpp>
     <java><out/>.put(<value-of param="a-string"/>).endl();</java>
    </endl>
   </param>
  </keyword>
  <keyword string="int">
   <param type="int" id="an-int">
    <endl>
     <cpp><out/> << <value-of param="an-int"/> << cli::endl;</cpp>
     <java><out/>.put(<value-of param="an-int"/>).endl();</java>
    </endl>
   </param>
  </keyword>
  <keyword string="float">
   <param type="float" id="a-float">
    <endl>
     <cpp><out/> << <value-of param="a-float"/> << cli::endl;</cpp>
     <java><out/>.put(<value-of param="a-float"/>).endl();</java>
    </endl>
   </param>
  </keyword>
  <keyword string="host">
   <param type="host" id="a-host">
    <endl>
     <cpp><out/> << <value-of param="a-host"/> << cli::endl;</cpp>
     <java><out/>.put(<value-of param="a-host"/>).endl();</java>
    </endl>
   </param>
  </keyword>
 </keyword>
</cli>

Have a look at the way you get access to the entered values: through param attributes of value-of elements.

This is discussed apart from the XML resource file section in the UI controls section.

I know, that's the reason why I've created tag elements.

Tags act like labels and gotos do in C/C++. The equivalent of the label definition is a tag element with an id attribute. And the equivalent of a goto statement is a tag element with a ref attribute.

Thanks to tags, you can define such kind of patterns:

The following examples show you how to do such syntax patterns.

,->
|
|
`--

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="a*">
 <tag id="my-tag">
  <endl></endl>
  <keyword string="a">
   <tag ref="my-tag" max="unbounded"/>
  </keyword>
 </tag>
</cli>

,->
|
|
`--

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="a+">
 <tag id="my-tag">
  <keyword string="a">
   <endl></endl>
   <tag ref="my-tag" max="unbounded"/>
  </keyword>
 </tag>
</cli>

,->
|
|
|
`--

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="(ab)*">
 <tag id="my-tag">
  <endl></endl>
  <keyword string="a">
   <keyword string="b">
    <tag ref="my-tag" max="unbounded"/>
   </keyword>
  </keyword>
 </tag>
</cli>

,->
|
|
|
`--

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="(ab)+">
 <tag id="my-tag">
  <keyword string="a">
   <keyword string="b">
    <endl></endl>
    <tag ref="my-tag" max="unbounded"/>
   </keyword>
  </keyword>
 </tag>
</cli>

Let me show you how to make a a(b1|b2|)c syntax pattern before a(b1|b2)c.

,--
|
|
+--
|
`->

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="a(b1|b2|)c">
 <keyword string="a">
  <keyword string="b1">
   <tag ref="my-tag"/>
  </keyword>
  <keyword string="b2">
   <tag ref="my-tag"/>
  </keyword>
  <tag id="my-tag">
   <keyword string="c">
    <endl></endl>
   </keyword>
  </tag>
 </keyword>
</cli>

Now, in order to forbid the CLI to go directly from keyword a to tag my-tag, just add a hollow attribute with a yes value.

,--
|
|
+--
|
`->

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="a(b1|b2)c">
 <keyword string="a">
  <keyword string="b1">
   <tag ref="my-tag"/>
  </keyword>
  <keyword string="b2">
   <tag ref="my-tag"/>
  </keyword>
  <tag id="my-tag" hollow="yes">
   <keyword string="c">
    <endl></endl>
   </keyword>
  </tag>
 </keyword>
</cli>

Now let us combine | and * patterns.

,--->
|
|
| ,--
| |
| |
| +--
| |
| `->
`----

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="(a|b)*">
 <tag id="my-tag1">
  <endl></endl>
  <keyword string="a">
   <tag ref="my-tag2"/>
  </keyword>
  <keyword string="b">
   <tag ref="my-tag2"/>
  </keyword>
  <tag id="my-tag2" hollow="yes">
   <tag ref="my-tag1" max="unbounded"/>
  </tag>
 </tag>
</cli>

,--->
|
| ,--
| |
| |
| +--
| |
| `->
|
`----

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="(a|b)+">
 <tag id="my-tag1">
  <keyword string="a">
   <tag ref="my-tag2"/>
  </keyword>
  <keyword string="b">
   <tag ref="my-tag2"/>
  </keyword>
  <tag id="my-tag2" hollow="yes">
   <endl></endl>
   <tag ref="my-tag1" max="unbounded"/>
  </tag>
 </tag>
</cli>

In lesser theoretical words, tag elements allow you to define command lines with options.

class Circle {
public:
    Circle(void) : m_iX(0), m_iY(0), m_iR(1), m_ulColor(0) {}
    void SetXPosition(int X) { m_iX = X; }
    int GetXPosition(void) const { return m_iX; }
    void SetYPosition(int Y) { m_iY = Y; }
    int GetYPosition(void) const { return m_iY; }
    void SetRadius(int R) { m_iR = R; }
    int GetRadius(void) const { return m_iR; }
    void SetColor(unsigned long C) { m_ulColor = C; }
    unsigned long GetColor(void) const { return m_ulColor; }
private:
    int m_iX;
    int m_iY;
    int m_iR;
    unsigned long m_ulColor;
};
void Draw(const Circle& C) {}

public class Circle {
    public Circle() { m_iX = 0; m_iY = 0; m_iR = 1; m_ulColor = 0; }
    public void setXPosition(int X) { m_iX = X; }
    public int getXPosition() { return m_iX; }
    public void setYPosition(int Y) { m_iY = Y; }
    public int getYPosition() { return m_iY; }
    public void setRadius(int R) { m_iR = R; }
    public int getRadius() { return m_iR; }
    public void setColor(long C) { m_ulColor = C; }
    public long getColor() { return m_ulColor; }
    public void draw() {}

    private int m_iX;
    private int m_iY;
    private int m_iR;
    private long m_ulColor;
}

,->
|
|
|
|
|
|
|
|
+--
|
|
|
|
|
|
+--
|
|
|
|
|
|
`--

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Circle">
 <cpp option="include">#include "circle.h"</cpp>
 <keyword string="add">
  <keyword string="circle">
   <cpp>Circle c;</cpp>
   <java>Circle c = new Circle();</java>
   <tag id="circle">
    <endl>
     <cpp>Draw(c);</cpp>
     <java>c.draw();</java>
    </endl>
    <keyword string="x_position">
     <param type="int" id="X">
      <cpp>c.SetXPosition(<value-of param="X"/>);</cpp>
      <java>c.setXPosition(<value-of param="X"/>);</java>
      <tag ref="circle" max="1"/>
     </param>
    </keyword>
    <keyword string="y_position">
     <param type="int" id="Y">
      <cpp>c.SetYPosition(<value-of param="Y"/>);</cpp>
      <java>c.setYPosition(<value-of param="Y"/>);</java>
      <tag ref="circle" max="1"/>
     </param>
    </keyword>
    <keyword string="radius">
     <param type="int" id="R">
      <cpp>c.SetRadius(<value-of param="R"/>);</cpp>
      <java>c.setRadius(<value-of param="R"/>);</java>
      <tag ref="circle" max="1"/>
     </param>
    </keyword>
   </tag>
  </keyword>
 </keyword>
</cli>

(1)



(2)




(3)






(3)






(3)

add circle
add circle x_position 1
add circle y_position 2
add circle radius 2
add circle x_position -1 y_position -1 radius 3
...

,--
|
|
|
|
+--
|
|
|
|
+--
|
|
|
|
+--
|
`->

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="Circle">
 <cpp option="include">#include "circle.h"</cpp>
 <keyword string="add">
  <keyword string="circle">
   <cpp>Circle c;</cpp>
   <java>Circle c = new Circle();</java>
   <keyword string="black">
    <cpp>c.SetColor(0x000000);</cpp>
    <java>c.setColor(0x000000);</java>
    <tag ref="draw-circle"/>
   </keyword>
   <keyword string="blue">
    <cpp>c.SetColor(0x00ff00);</cpp>
    <java>c.setColor(0x00ff00);</java>
    <tag ref="draw-circle"/>
   </keyword>
   <keyword string="red">
    <cpp>c.SetColor(0xff0000);</cpp>
    <java>c.setColor(0xff0000);</java>
    <tag ref="draw-circle"/>
   </keyword>
   <keyword string="green">
    <cpp>c.SetColor(0x0000ff);</cpp>
    <java>c.setColor(0x0000ff);</java>
    <tag ref="draw-circle"/>
   </keyword>
   <tag id="draw-circle" hollow="yes">
    <endl>
     <cpp>Draw(c);</cpp>
     <java>c.draw();</java>
    </endl>
   </tag>
  </keyword>
 </keyword>
</cli>

(1)


(2)




(2)




(2)




(2)





(3)

add circle black
add circle blue
add circle red
add circle green

You're right! That's a possibility. But hold on! What you are looking for is probably menus.

The cli element basically implements the main menu of a CLI interface. You may also define sub-menus, gathering sets of commands under a common topic by the way. Menus are then accessed through command lines.

A menu element with a name attribute defines a new menu. Inside, you can declare new command lines, as you would proceed in the cli element. This menu element can be placed:

It is now time to introduce the pwm command. If you have tried any example of this user guide, you may have noticed a basic command pwm meaning Print Working Menu. The same way pwd gives you the working directory in a UNIX shells, this command gives you the current working menu, and the current stack of menus.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="my-config">
 <keyword string="show">
  <keyword string="ip">
   <keyword string="config">
    <endl></endl>
   </keyword>
   <keyword string="stats">
    <endl></endl>
   </keyword>
  </keyword>
 </keyword>
 <keyword string="edit">
  <keyword string="config">
   <endl>
    <menu name="edit">
     <keyword string="set">
      <keyword string="ip">
       <keyword string="address">
        <param type="host" id="addr">
         <endl></endl>
        </param>
       </keyword>
      </keyword>
     </keyword>
     <keyword string="reset">
      <keyword string="stats">
       <endl></endl>
      </keyword>
     </keyword>
    </menu>
   </endl>
  </keyword>
 </keyword>
</cli>

(1)
(1) (3)




(2)






(2)

This toolkit is provided with two schema files: cli.xsd and cli.rng.

cli.xsd is a regular W3C Xml Schema 1.0 file. Because of W3C limitations, some constraints are not checked with this Xml Schema:

However cli.xsd can be used in order to have a first level of syntax checking.

$ xmllint --schema ${CLI_DIR}/tools/cli.xsd --noout my-cli.xml
my-cli.xml validates

cli.rng is a Relax NG schema. Relax NG permits the description of elements having the same name but different attributes, however it still does not cover all the constraints that should be checked:

But once again, cli.rng can be used in order to have a first level of syntax checking.

$ xmllint --relaxng ${CLI_DIR}/tools/cli.rng --noout --noout my-cli.xml
my-cli.xml validates

Automatic documentation generation may do part of the job for you then.

Since version 2.5, the CLI toolkit is provided with a cli2help.xsl XSL stylesheet. And since version 2.8, a python tool equivalent cli2help.py is also provided. These tools generate CLI documentation automatically.

xsltproc ${CLI_DIR}/tools/cli2help.xsl clisample.xml > clisample.html

python ${CLI_DIR}/tools/cli2help.py clisample.xml > clisample.html

The XSL transformation stylesheet has several parameters:

The python tool comes with a --help option:

$ python ${CLI_DIR}/tools/cli2help.py --help
usage: cli2help [-h] [--version] [--lang LANG] [--toc | --no-toc]
                [--title-numbers | --no-title-numbers]
                xml-res

positional arguments:
  xml-res             CLI XML resource file

optional arguments:
  -h, --help          show this help message and exit
  --version           show program's version number and exit
  --lang LANG         Language ('en', 'fr'...).
  --toc               Generate table of content.
  --no-toc            Do not generate table of content.
  --title-numbers     Generate titles with their number.
  --no-title-numbers  Generate titles with no number.

This documentation generation is not as clever as a human being, therefore here is a couple of directions in order to generate a smart documentation:

Make the user enter a single text line on request, with regular text edition facilities:

plus other features:

Check C++ doxygen or javadoc documentations for details on programming interfaces.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_line.h"</cpp>
 <keyword string="enter">
  <keyword string="line">
   <endl>
    <!-- C++ implementation -->
    <cpp><out/> << "Enter line: ";</cpp>
    <cpp>cli::ui::Line ui_Line(GetShell(), cli::tk::String(10, ""), 0, 1024);</cpp>
    <cpp>ui_Line.Run();</cpp>
    <cpp><out/> << "User entered '" << ui_Line.GetLine() << "'" << cli::endl;</cpp>
    <!-- Java implementation -->
    <java><out/>.put("Enter line: ");</java>
    <java>cli.ui.Line ui_Line = new cli.ui.Line(getShell(), "", 0, 1024);</java>
    <java>ui_Line.run();</java>
    <java><out/>.put("User entered '" + ui_Line.getLine() + "'").endl();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

UI>enter line
Enter line: Hello world
User entered 'Hello world'
UI>

Same as above, but without displaying the text. Either nothing is displayed or only stars.

Check C++ doxygen or javadoc documentations for details on programming interfaces.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_password.h"</cpp>
 <keyword string="enter">
  <keyword string="password">
   <endl>
    <!-- C++ implementation -->
    <cpp><out/> << "Enter password: ";</cpp>
    <cpp>cli::ui::Password ui_Password(GetShell(), true, 0, 1024);</cpp>
    <cpp>ui_Password.Run();</cpp>
    <cpp><out/> << "User entered '" << ui_Password.GetPassword() << "'" << cli::endl;</cpp>
    <!-- Java implementation -->
    <java><out/>.put("Enter password: ");</java>
    <java>cli.ui.Password ui_Password = new cli.ui.Password(getShell(), true, 0, 1024);</java>
    <java>ui_Password.run();</java>
    <java><out/>.put("User entered '" + ui_Password.getPassword() + "'").endl();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

UI>enter password
Enter password: *****
User entered 'hello'
UI>

Let the user enter an integer number. The Int class provides default value, plus min and max checkers.

Check C++ doxygen or javadoc documentations for details on programming interfaces.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_int.h"</cpp>
 <keyword string="enter">
  <keyword string="int">
   <endl>
    <!-- C++ implementation -->
    <cpp><out/> << "Enter integer number: ";</cpp>
    <cpp>cli::ui::Int ui_Int(GetShell(), 0, -1000, 1000);</cpp>
    <cpp>ui_Int.Run();</cpp>
    <cpp><out/> << "User entered " << ui_Int.GetInt() << cli::endl;</cpp>
    <!-- Java implementation -->
    <java><out/>.put("Enter integer number: ");</java>
    <java>cli.ui.Int ui_Int = new cli.ui.Int(getShell(), 0, -1000, 1000);</java>
    <java>ui_Int.run();</java>
    <java><out/>.put("User entered " + ui_Int.getInt()).endl();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

UI>enter int
Enter integer number: 107
User entered 107
UI>

Let the user enter a floating point number. The Float class provides default value, plus min and max checkers.

Check C++ doxygen or javadoc documentations for details on programming interfaces.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_float.h"</cpp>
 <keyword string="enter">
  <keyword string="float">
   <endl>
    <!-- C++ implementation -->
    <cpp><out/> << "Enter floating point number: ";</cpp>
    <cpp>cli::ui::Float ui_Float(GetShell(), 0, - 1000.0, 1000.0);</cpp>
    <cpp>ui_Float.Run();</cpp>
    <cpp><out/> << "User entered " << ui_Float.GetFloat() << cli::endl;</cpp>
    <!-- Java implementation -->
    <java><out/>.put("Enter floating point number: ");</java>
    <java>cli.ui.Float ui_Float = new cli.ui.Float(getShell(), 0, -1000.0, 1000.0);</java>
    <java>ui_Float.run();</java>
    <java><out/>.put("User entered " + ui_Float.getFloat()).endl();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

UI>enter float
Enter floating point number: -3.14
User entered -3.14
UI>

Let the user answer "yes/no" questions. "Yes/no" questions are nothing but multiple choice questions with "yes" or "no" for choices.

Check C++ doxygen or javadoc documentations for details on programming interfaces.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_yesno.h"</cpp>
 <keyword string="enter">
  <keyword string="yesno">
   <endl>
    <!-- C++ implementation -->
    <cpp><out/> << "Please select [YES/no]: ";</cpp>
    <cpp>cli::ui::YesNo ui_YesNo(GetShell(), true);</cpp>
    <cpp>ui_YesNo.Run();</cpp>
    <cpp><out/> << "User entered " << (ui_YesNo.GetYesNo() ? "true" : "false") << "/'" << ui_YesNo.GetstrChoice().GetString(GetShell().GetLang()) << "'" << cli::endl;</cpp>
    <!-- Java implementation -->
    <java><out/>.put("Please select [YES/no]: ");</java>
    <java>cli.ui.YesNo ui_YesNo = new cli.ui.YesNo(getShell(), true);</java>
    <java>ui_YesNo.run();</java>
    <java><out/>.put("User entered " + ui_YesNo.getYesNo() + "/'" + ui_YesNo.getstrChoice().getString(getShell().getLang()) + "'").endl();</java>
   </endl>
  </keyword>
 </keyword>
</cli>

UI>enter yesno
Please select [YES/no]: No
User entered false/'No'
UI>

Let the user answer multiple choice questions. Either the user types directly the choice himself/herself (auto-completion is provided), or he/she can use UP and DOWN keys to move from one choice to the other.

Check C++ doxygen or javadoc documentations for details on programming interfaces.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_choice.h"</cpp>
 <cpp option="include">#include "cli/string_device.h"</cpp>
 <keyword string="enter">
  <keyword string="choice">
   <param type="int" id="count">
    <endl>
     <!-- C++ implementation -->
     <cpp><out/> << "Select choice: ";</cpp>
     <cpp>cli::tk::Queue<cli::ResourceString> tk_Choices(<value-of param="count"/>);</cpp>
     <cpp>for (int i=0; i<<value-of param="count"/>; i++) {</cpp>
     <cpp>    cli::StringDevice cli_Choice(1024, false); cli_Choice << "Choice#" << (i + 1);</cpp>
     <cpp>    tk_Choices.AddTail(cli::ResourceString().SetString(cli::ResourceString::LANG_EN, cli_Choice.GetString()));</cpp>
     <cpp>}</cpp>
     <cpp>cli::ui::Choice ui_Choice(GetShell(), 0, tk_Choices);</cpp>
     <cpp>ui_Choice.Run();</cpp>
     <cpp><out/> << "User entered " << ui_Choice.GetChoice() << "/'" << ui_Choice.GetstrChoice().GetString(GetShell().GetLang()) << "'" << cli::endl;</cpp>
     <!-- Java implementation -->
     <java><out/>.put("Select choice: ");</java>
     <java>java.util.Vector<cli.ResourceString> j_Choices = new java.util.Vector<cli.ResourceString>();</java>
     <java>for (int i=0; i<<value-of param="count"/>; i++) {</java>
     <java>    j_Choices.add(new cli.ResourceString().setString(cli.ResourceString.LANG_EN, "Choice#" + (i + 1)));</java>
     <java>}</java>
     <java>cli.ui.Choice ui_Choice = new cli.ui.Choice(getShell(), 0, j_Choices);</java>
     <java>ui_Choice.run();</java>
     <java><out/>.put("User entered " + ui_Choice.getChoice() + "/'" + ui_Choice.getstrChoice().getString(getShell().getLang()) + "'").endl();</java>
    </endl>
   </param>
  </keyword>
 </keyword>
</cli>

UI>enter choice 10
Select choice: Choice#6
User entered 5/'Choice#6'
UI>

Display long text, page by page, as a regular "more" display:

Check C++ doxygen or javadoc documentations for details on programming interfaces. Basically, the text is prepared in the OutputDevice text member, then the More execution is invoked for text display.

static void FillText(const cli::OutputDevice& CLI_UI, const unsigned int UI_Count) {
    for (unsigned int i=1; (i<=UI_Count) && (i<1024); i++) {
        CLI_UI << i << ": ";
        for (unsigned int j=1; j<=i; j++) CLI_UI << "*";
        CLI_UI << cli::endl;
    }
}

public class UISampleText {
    public static void fillText(cli.OutputDevice.Interface CLI_UI, int I_Count) {
        for (int i=1; (i<=I_Count) && (i<1024); i++) {
            CLI_UI.put(i + ": ");
            for (int j=1; j<=i; j++) CLI_UI.put("*");
            CLI_UI.endl();
        }
    }
}

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_more.h"</cpp>
 <cpp option="include">#include "ui_sample_text.h"</cpp>
 <keyword string="more">
  <param type="int" id="count">
   <endl>
    <!-- C++ implementation -->
    <cpp>cli::ui::More ui_More(GetShell(), 1024, <value-of param="count"/>);</cpp>
    <cpp>FillText(ui_More.GetText(), <value-of param="count"/>);</cpp>
    <cpp>ui_More.Run();</cpp>
    <!-- Java implementation -->
    <java>cli.ui.More ui_More = new cli.ui.More(getShell());</java>
    <java>UISampleText.fillText(ui_More.getText(), <value-of param="count"/>);</java>
    <java>ui_More.run();</java>
   </endl>
  </param>
 </keyword>
</cli>

UI>more 100
1: *
2: **
3: ***
4: ****
5: *****
6: ******
7: *******
8: ********
9: *********
10: **********
11: ***********
12: ************
13: *************
14: **************
15: ***************
16: ****************
17: *****************
18: ******************
19: *******************
--- More ---

20: ********************
--- More ---

21: *********************
22: **********************
23: ***********************
24: ************************
25: *************************
26: **************************
27: ***************************
28: ****************************
29: *****************************
30: ******************************
31: *******************************
32: ********************************
33: *********************************
34: **********************************
35: ***********************************
36: ************************************
37: *************************************
38: **************************************
39: ***************************************
--- More ---

UI>

Display long text, page by page, as a regular "less" display:

Check C++ doxygen or javadoc documentations for details on programming interfaces. A Less object is prepared the same as a More object (see previous section).

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="UI">
 <cpp option="include">#include "cli/ui_less.h"</cpp>
 <cpp option="include">#include "ui_sample_text.h"</cpp>
 <keyword string="less">
  <param type="int" id="count">
   <endl>
    <!-- C++ implementation -->
    <cpp>cli::ui::Less ui_Less(GetShell(), 80, <value-of param="count"/>);</cpp>
    <cpp>FillText(ui_Less.GetText(), <value-of param="count"/>);</cpp>
    <cpp>ui_Less.Run();</cpp>
    <!-- Java implementation -->
    <java>cli.ui.Less ui_Less = new cli.ui.Less(getShell());</java>
    <java>UISampleText.fillText(ui_Less.getText(), <value-of param="count"/>);</java>
    <java>ui_Less.run();</java>
   </endl>
  </param>
 </keyword>
</cli>

UI>less 100
1: *
2: **
3: ***
4: ****
5: *****
6: ******
7: *******
8: ********
9: *********
10: **********
11: ***********
12: ************
13: *************
14: **************
15: ***************
16: ****************
17: *****************
18: ******************
19: *******************
:

2: **
3: ***
4: ****
5: *****
6: ******
7: *******
8: ********
9: *********
10: **********
11: ***********
12: ************
13: *************
14: **************
15: ***************
16: ****************
17: *****************
18: ******************
19: *******************
20: ********************
:

UI>

Let's start with telnet implementation. The CLI library provides TelnetServer and TelnetConnection classes. These classes allow you to easily make your CLI run with network connections.

Example 32. Simple telnet server

First of all, inherit from TelnetServer. All you have to do is to override onNewConnection to allocate resources for new network connections, and onCloseConnection to free them when the thing is done.

class MyServer extends cli.TelnetServer {
    public MyServer() {
        // Up to 10 clients on port 9012.
        super(10, 9012, cli.ResourceString.LANG_EN);
    }
    protected cli.ExecutionContext.Interface onNewConnection(cli.TelnetConnection CLI_NewConnection) {
        // Create CLI and Shell instances for that new connection.
        cli.Cli cli_Cli = new MyCli();
        cli.Shell cli_Shell = new cli.Shell(cli_Cli);
        return cli_Shell;
    }
    protected void onCloseConnection(cli.TelnetConnection CLI_ConnectionClosed, cli.ExecutionContext.Interface CLI_Context) {
        // Free connection resources: the garbage collector does the thing for us in Java.
        // Note: CLI_Context corresponds to the cli.Shell instance we have created in onNewConnection().
    }
}

Eventually call startServer and that's it.

MyServer cli_Server = new MyServer();
cli_Server.startServer(); // Blocking call

Note

The TelnetServer and TelnetConnection interfaces have been modified in 2.7 and 2.8 consequent versions. Sorry if those changes disturb integrations of some of your software with prior versions of the library, but note that the motivation for those modifications is real improvements:

CLI 2.7 improvements

• Redesign of TelnetConnection, made as non blocking for a better management of parallel connections.
• Redesign of TelnetServer, made virtual, so that the user software can create as many shells and clis for each connection.

CLI 2.8 improvements

• Redesign again of TelnetServer, due to execution contexts improvements , so that the user software can create shells and clis, but also any other kind of execution contexts.

Start your server, and connect to it thanks to teraterm for instance:

teraterm telnet settings

If you need the server not to be blocking for your application, up to you to thread the thing.

The features described in the table below are available from native code. Please refer to doxygen or javadoc documentation for additional information.

The CLI library has an internal traces system. All traces are attached to a class of traces. By the way, you can control which traces have to be displayed thanks to the traces class filter. When compiled in debug, the CLI library natively includes a traces menu to see and change this filter.

The cli::Traces and cli::TraceClass classes are defined in cli/traces.h, which is available to you. The traces system can be accessed through the singleton cli::GetTraces. This gives you the opportunity to use it to control the trace filter through the cli::Traces::SetFilter and cli::Traces::SetAllFilter methods. You may also use it for your own traces through the cli::Traces::Trace method.

cli::Traces uses an output device that defaults to stderr. You may change this device through the cli::Traces::SetStream method, and redirect traces to a file for instances. Changing this device for the null device is a way to disable all traces.

Considering the input device could be not the same all along CLI execution, I have created an input / output multiplexer device. Thus, this kind of device allows you to mix several input devices and redirect outputs to other devices.

This device may seem complex at first. It can be useful however to create simple compilers as described in the section after.

Thanks to real improvements of non blocking executions with the addition of execution contexts, the cli::Shell::QuitThreadSafe method has been deprecated and even removed in version 2.8. Indeed, if you need to terminate a CLI execution from external events, it is far much better to make it work in a non blocking mode. This way, it can remain in a single main thread, without the threat of threading border effects.

The basic integration of the CLI is to have the shell running its main loop in the main thread, waiting for the input device to return characters, thanks to the blocking call cli::IODevice::GetKey.

This method is fast, but not convenient in various situations:

That's the reason why a "non blocking" execution mode has been developed.

It is available by simply giving a cli::NonBlockingIODevice input device to the shell for its execution. It is up to you to:

cli.Cli cli_Cli = new MyCli();
cli.Shell cli_Shell = new cli.Shell(cli_Cli);
MyNonBlockingIODevice cli_Device = new MyNonBlockingIODevice(); // extends cli.NonBlockingIODevice

// Since cli_Device is a non blocking device, the following call does not block the execution thread.
cli_Shell.run(cli_Device);
// cli_Shell is still running at this point!

// Let's push characters...
cli_Device.onKey(cli.OutputDevice.KEY_q);
cli_Device.onKey(cli.OutputDevice.KEY_u);
cli_Device.onKey(cli.OutputDevice.KEY_i);
cli_Device.onKey(cli.OutputDevice.KEY_t);
cli_Device.onKey(cli.OutputDevice.ENTER);
// Since the 'quit' command has been pushed, cli_Shell is not running anymore at this point!

Regarding UI controls, in non blocking mode, you have to rely on the ExecutionResult interface in order to be notified when their execution is done (see Execution contexts).

final MyNonBlockingIODevice cli_Device = new MyNonBlockingIODevice(); // extends cli.NonBlockingIODevice
final cli.ui.Line ui_Line = new cli.ui.Line(cli_Shell, "", 0, 1024);
cli_Device.put("Enter line: ");
ui_Line.watchResult(
    new cli.ExecutionResult() {
        // This method will be called when the control is done
        protected void onResult(cli.ExecutionContext.Interface CLI_Context) {
            cli_Device.put("End of execution: ").put(ui_Line.getLine()).endl();
        }
    }
);
ui_Line.run();
cli_Device.onKey(cli.OutputDevice.KEY_h);
cli_Device.onKey(cli.OutputDevice.KEY_e);
cli_Device.onKey(cli.OutputDevice.KEY_l);
cli_Device.onKey(cli.OutputDevice.KEY_l);
cli_Device.onKey(cli.OutputDevice.KEY_o);
cli_Device.onKey(cli.OutputDevice.ENTER);
// "End of execution: hello" printed out there

Generic execution contexts have been added in version 2.8. They consist in something that manages:

It basically corresponds to what the Shell does, but also UI controls, and possibly something you could define for your own needs. This feature is basically implemented with the ExecutionContext and ExecutionResult classes.

6.9.1. Input character processing

Input character processing is implemented through the ExecutionContext::Run method. It may be either a blocking or a non blocking call depending on the type of input/output device given.

The following flow chart illustrates how it works for a regular blocking call execution, (i.e. when the input/output device is a direct IODevice-derived class):

Execution contexts: blocking call execution flow chart

As discussed in the Non blocking execution section, it also supports non blocking call executions (i.e. when the input/output device is a NonBlockingIODevice). In that case, the ExecutionResult allows one to retrieve execution results of ExecutionContext once they are done, as shown in the Non blocking execution and UI controls example. The following flow chart illustrates a non blocking call execution:

Execution contexts: non blocking call execution flow chart

#include "cli/exec_context.h"
#include "cli/ui_password.h"
#include "cli/shell.h"

//! @brief Authentication for a shell access.
class PwdShellContext : public cli::ExecutionContext, public cli::ExecutionResult
{
public:
    //! @brief Constructor.
    PwdShellContext(const cli::Cli& CLI_Cli, const char* const STR_Pwd)
          : cli::ExecutionContext(),                                    // Create top execution context.
            m_tkPwd(256, STR_Pwd), m_uiPwdAttempsLeft(MAX_PWD_ATTEMPTS)
    {
        m_pcliPwd = new cli::ui::Password(*this, true, -1, -1);         // Create password child execution context.
        m_pcliShell = new cli::Shell(*this, CLI_Cli);                   // Create shell child execution context.
    }
    //! @brief Destructor.
    virtual ~PwdShellContext(void) {
        delete m_pcliPwd;
        delete m_pcliShell;
    }
public:
    //! @brief Password control accessor.
    cli::ui::Password& GetPwdControl(void) { return *m_pcliPwd; }
    //! @brief Shell accessor.
    cli::Shell& GetShell(void) { return *m_pcliShell; }
protected:
    //! @brief OnStartExecution(): start the password control.
    virtual const bool OnStartExecution(void) {
        GetStream(cli::OUTPUT_STREAM) << "Enter password: ";
        WatchResult(*m_pcliPwd);
        m_pcliPwd->Run();
        return true;
    }
    //! @brief Receives notifications when a child execution context is done.
    virtual void OnResult(const cli::ExecutionContext& CLI_ExecutionContext) {
        if (IsRunning()) {
            // When this is a notification from the password control...
            if (& CLI_ExecutionContext == m_pcliPwd) {
                if (m_pcliPwd->GetbExecResult()) {
                    if (m_uiPwdAttempsLeft > 0) {
                        // Decrement the password attempts left at first.
                        m_uiPwdAttempsLeft --;
                        if (m_pcliPwd->GetPassword() == m_tkPwd) {
                            // Password OK: restore the password attempts left and run the shell.
                            m_uiPwdAttempsLeft = MAX_PWD_ATTEMPTS;
                            WatchResult(*m_pcliShell);
                            m_pcliShell->Run();
                            return;
                        } else {
                            // Wrong password
                            if (m_pcliPwd->GetPassword().IsEmpty()) {
                                m_uiPwdAttempsLeft ++;
                            } else {
                                GetStream(cli::ERROR_STREAM) << "Wrong password!" << cli::endl;
                            }
                            if (m_uiPwdAttempsLeft > 0) {
                                // Let the user enter his password again.
                                PwdShellContext::OnStartExecution();
                                return;
                            }
                        }
                    }
                }
            }
            // Default behaviour.
            ExecutionContext::StopExecution();
        }
    }
    //! @brief OnStopExecution(): called when either the user has typed too many wrong passwords, or when the shell is done.. */
    virtual const bool OnStopExecution(void) { return true; }
    //! @brief OnKey(): should not happen.
    virtual void OnKey(const cli::KEY E_Key) {}
private:
    cli::ui::Password* m_pcliPwd;
    cli::Shell* m_pcliShell;
    cli::tk::String m_tkPwd;
    enum { MAX_PWD_ATTEMPTS = 3 };
    unsigned int m_uiPwdAttempsLeft;
};

/** Authentication for a shell access. */
class PwdShellContext extends cli.ExecutionContext.Java
{
    /** Constructor. */
    public PwdShellContext(cli.Cli CLI_Cli, String J_Pwd) {
        super();                                            // Create top execution context.
        m_jPwd = J_Pwd;
        m_cliPwd = new cli.ui.Password(this, true, -1, -1); // Create password child execution context.
        m_cliShell = new cli.Shell(this, CLI_Cli);          // Create shell child execution context.
        m_cliResult = new PwdShellResult();
        m_iPwdAttempsLeft = MAX_PWD_ATTEMPTS;
    }
    /** Password control accessor. */
    public cli.ui.Password getPwdControl() { return m_cliPwd; }
    /** Shell accessor. */
    public cli.Shell getShell() { return m_cliShell; }
    /** onStartExecution(): start the password control. */
    protected boolean onStartExecution() {
        getStream(cli.ExecutionContext.OUTPUT_STREAM).put("Enter password: ");
        m_cliResult.watchResult(m_cliPwd);
        m_cliPwd.run();
        return true;
    }
    /** onStopExecution(): called when either the user has typed too many wrong passwords, or when the shell is done.. */
    protected boolean onStopExecution() { return true; }
    /** onKey(): should not happen. */
    protected void onKey(int E_Key) {}

    /** Receives notifications when a child execution context is done. */
    private class PwdShellResult extends cli.ExecutionResult {
        protected void onResult(cli.ExecutionContext.Interface CLI_ExecutionContext) {
            if (isRunning()) {
                // When this is a notification from the password control...
                if (CLI_ExecutionContext == m_cliPwd) {
                    if (m_cliPwd.getbExecResult()) {
                        if (m_iPwdAttempsLeft > 0) {
                            // Decrement the password attempts left at first.
                            m_iPwdAttempsLeft --;
                            if (m_cliPwd.getPassword().equals(m_jPwd)) {
                                // Password OK: restore the password attempts left and run the shell.
                                m_iPwdAttempsLeft = MAX_PWD_ATTEMPTS;
                                m_cliResult.watchResult(m_cliShell);
                                m_cliShell.run();
                                return;
                            } else {
                                // Wrong password
                                if (m_cliPwd.getPassword().length() <= 0) {
                                    m_iPwdAttempsLeft ++;
                                } else {
                                    getStream(cli.ExecutionContext.ERROR_STREAM).put("Wrong password!").endl();
                                }
                                if (m_iPwdAttempsLeft > 0) {
                                    // Let the user enter his password again.
                                    onStartExecution();
                                    return;
                                }
                            }
                        }
                    }
                }
                // Default behaviour.
                stopExecution();
            }
        }
    }

    private final int MAX_PWD_ATTEMPTS = 3;
    private final String m_jPwd;
    private final cli.ui.Password m_cliPwd;
    private final cli.Shell m_cliShell;
    private final PwdShellResult m_cliResult;
    private int m_iPwdAttempsLeft;
}

When integrating the CLI in an embedded context, memory considerations become a critical point.

The library basically uses the STL library for strings, queues and maps basic objects. But in an embedded integration, it is usually preferred not to use STL at all, because the memory is not known to be safely managed. That's the reason why an inner toolkit implement is provided with the CLI library. This toolkit, enabled through the CLI_NO_STL compilation directive, provides an implementation of strings, queues and maps with a limit of memory extension.

Eventually, you may also have a look at the header file constraints.h. This header defines a set of constants that are overridable at compile time.

C++ CLI is ready for pre-compiled headers. Every CLI source starts its inclusions with:

#include "cli/pch.h"

A default empty cli/pch.h is provided with C++ CLI includes, so that builds work on even though pre-compiled headers are not set up.

I you wish to use pre-compiled headers, I advise you not to modify the header provided with the library. Indeed, if you modify that header, then when you upgrade the CLI library with later versions, you may loose your changes by the way. You'd better create your own cli/pch.h somewhere by your own sources, and configure include paths so that your cli/pch.h file is included before the one provided by the library. Then include cli/pch.h in your pre-compiled source object to finalize pre-compilation settings.

The CLI library can be used to make out compilers of simple syntaxes. I'm used to combine the cli::InputFileDevice class to read from files, and the cli::IOMux class to read from a set of files one after the other.

The cli::InputFileDevice provides two methods very useful in that case:

Some of you could find the library interesting for what it already implements, but not the XML resource file, too limitative maybe.

Indeed the XML resource file aims to facilitate and fasten the development. But you could plan using library objects directly, and maybe inherit from them in order to improve the stuff.

Well... Up to you!

tag elements allow you to reuse command line patterns within in a same command line, but they do not work across different menus.

By the way, repeating a same set of commands in different menus is a regular expectation. You can use XML inclusions for that.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE cli [
 <!ENTITY child SYSTEM "child.xml">
]>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="top">
 <keyword string="menu1">
  <endl>
   <menu name="menu1">
    &child;
   </menu>
  </endl>
 </keyword>
 <keyword string="menu2">
  <endl>
   <menu name="menu2">
    &child;
   </menu>
  </endl>
 </keyword>
</cli>

<?xml version="1.0" encoding="ISO-8859-1"?>
<keyword string="k1">
 <endl></endl>
</keyword>

xmllint --dropdtd --noent top.xml > full.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<cli xmlns="http://alexis.royer.free.fr/CLI" name="top">
 <keyword string="menu1">
  <endl>
   <menu name="menu1">
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="child.xml" parse="xml"/>
   </menu>
  </endl>
 </keyword>
 <keyword string="menu2">
  <endl>
   <menu name="menu2">
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="child.xml" parse="xml"/>
   </menu>
  </endl>
 </keyword>
</cli>

xmllint --xinclude top2.xml > full2.xml

The aim of this software is to ease the development of command line interfaces, not to provided a high-security shell implementation. That's the reason why the Shell class does not provide a password authentication nor a timeout feature.

It is up to you to implement such kind of functions, depending on your security requirements. By the way, I advise you to read through the Execution contexts section, and its PwdShellContext execution context example. Also have a look at non blocking devices, in the Non blocking execution section, which are more suitable to implement timeout aspects.

If I had provided a general member for a context reference in Cli objects, it would have been an opaque pointer of type void*, which I definitely dislike. I prefer when objects are accessed through full type accessors, such as singletons, or register databases. Or even better, you could make use of member code generation as described in the cpp, java - Insert target language directly in the resource file section in order to declare your own context reference, with getters and setters.

Please note at first that a bug around formatting pointer values has been fixed in version 2.8 in io_device.cpp.

Then, it seems there may be troubles around Java. Here is what Pete Geremia emailed to me after he managed to make it work on a 64 bit architecture (thank you Pete):

Now, if you, guys, have some more info, please let me know.

Has far as CLI symbols are all scoped in a cli namespace, I have not specified them with redundant prefixes. To my point of view, this is a smart way of organizing C++ code. Therefore, the DELETE symbol is defined as an enum value in the scope of the cli namespace.

The compilation error with Visual C++ comes with an abusive VC++ DELETE define directive in Windows headers. This define is useless in CLI sources, therefore I advise to use a cli/pch.h file as described in the Pre-compiled headers section, and undefine the DELETE symbol in it, after Windows inclusions:

#undef DELETE

First check you have installed the ncurses devel tools as described in section Prerequisite.

If you have already installed the ncurses devel tools, and still have the error, check whether your curses.h header is located in your regular system include path (/usr/include in general). You may notice that it is not exactly in this directory but maybe in a subdirectory. I recently faced this problem with my latest Cygwin install. You'd then set (or extend) your CPLUS_INCLUDE_PATH environment variable to the required directory, as below for example:

export CPLUS_INCLUDE_PATH=/usr/include/ncurses

Then try to rebuild.

Indeed, C++ CLI auto-generated source files contain lots of labels and gotos. Not all of the labels defined are used with goto statements, which causes all those warnings with most of compilers.

You may have noticed the use of the g++ -Wno-unused-label option in the C++ integration section. This option can be set specifically for the compilation of CLI generated source file, in order to avoid all those warnings.

With VC++, you shall use the following pragma instruction:

#pragma warning(disable:4102)

either by putting it in a cli/pch.h as described in the Pre-compiled headers section, or by using generated code sections as described in the cpp, java - Insert target language directly in the resource file section.

The problem must be because you are using standard outputs (printf, std::cout...), while the cli is ran with a cli::Console device which relies on the ncurses library on Linux platforms. Mixing standard and ncurses outputs does not behave correctly.

Indeed, you should always use the output and error devices used by your Cli (and Shell), even in your user code. Here is a way of doing it:

<keyword string="bye"><help lang="en">Say goodbye.</help>
 <endl><cpp>sayBye(<out/>);</cpp></endl>
</keyword>

Notice the use of out that references the cli/shell output device. Could also be err for the error device. See Output example.

Then:

void sayBye(const cli::OutputDevice& CLI_Out)
{
    CLI_Out << "Bye" << cli::endl;
    CLI_Out << "Bye Again" << cli::endl;
}

Notice the use of CLI_Out instead of std::cout, and the use of cli::endl instead of std::endl.

By the way, if you ever wish to change that device later on (for telnet input/output for instance, or a serial port...), you would just have to change the kind of device given to the Shell instance for running. Here is a sample with file devices:

void runShellWithFiles()
{
    MyCli cli_MyCli;
    cli::Shell cli_Shell(cli_MyCli);
    cli::OutputFileDevice cli_OutFile("output.log", false);
    cli::InputFileDevice cli_InFile("input.cli", cli_OutFile, false);
    cli_Shell.Run(cli_InFile);
}

The Java implementation relies on a native dynamic library which device console is based on win_console.cpp under cygwin. This choice makes your Java programs work without a dependency on cygwin1.dll, which is convenient for applications running in a Windows environment.

Latest Cygwin distributions propose the mintty console, which works correctly with ncurses_console.cpp but unfortunatley not with win_console.cpp implementation. By the way, if you run the given java command line in a regular cmd.exe console, it works as expected.

If you want to compile Java programs under cygwin and execute them in the same console as well (devel configuration for example), you may launch a cmd.exe console and run the Cygwin.bat script provided in your cygwin install directory.

I had once noticed strange behaviours with my WinConsole device, through Java execution under cygwin:

I then figured out that it was because I was executing the CLI within the context of a Makefile, launched through colormake, which uses output redirection. When using make directly, no problem anymore.

As a matter of fact, if you face non optimal behaviours with Console devices, please make sure no output redirection is used, otherwise console primitives will operate on the pipe and not the console anymore.

The CLI library does not intend to be VC++ specific code, nor Eclipse specific, nor CodeWarrior... I do not intend neither to "pollute" the CLI sources with various compiler specific macros. That's the reason why regular VC++ memory leak macros are not set in the CLI sources, even guarded by pre-compilation switches.

Nevertheless, I've tried to deal with memory leaks so far. A special thank to Oleg Smolsky's contribution at this point, for another one detected and fixed. Now if you figure out that leaks still remain, up to you to set your macros in the CLI sources for investigations, depending on the tool you use: VC++, valgrind... I'll be glad to integrate your fixes if you have any.