npm 中文文档
C/C++ CI of Cli

cli


A cross-platform header only C++14 library for interactive command line interfaces (Cisco style)

C/C++ CI of Cli

❤️ Sponsor

IMPORTANT: Breaking API changes!Version 2.0 of cli has made breaking changes in order to add more functionality. To migrate your application to new cli version, see the section "Async programming and Schedulers" of this file, or the examples that come with the library.

Features


Header only
Cross-platform (linux and windows)
Menus and submenus
Remote sessions (telnet)
Persistent history (navigation with arrow keys)
Autocompletion (with TAB key)
Async interface
Colors

How to get CLI library


From GitHub
Using Vcpkg

Dependencies


The library has no dependencies if you don't need remote sessions.

The library depends on asio (either the standalone version or the boost version) onlyto provide telnet server (i.e., remote sessions).

Installation


The library is header-only: it consists entirely of header files containing templates and inline functions, and requires no separately-compiled library binaries or special treatment when linking.

Extract the archive wherever you want.

Now you must only remember to specify the cli (and optionally asio or boost) paths when compiling your source code.

If you fancy it, a Cmake script is provided. To install you can use:

  1. ``` sh
  2. mkdir build && cd build
  3. cmake ..
  4. sudo make install

  6. ```

or, if you want to specify the installation path:

  1. ``` sh
  2. mkdir build && cd build
  3. cmake .. -DCMAKE_INSTALL_PREFIX:PATH=<cli_install_location>
  4. make install

  6. ```

Alternatively, you can use CMake's FetchContent module to include CLI library in your project directly. Add something like this in your CMakeLists.txt file:

  1. ``` sh
  2. include(FetchContent)
  3. FetchContent_Declare(
  4.   cli
  5.   GIT_REPOSITORY https://github.com/daniele77/cli.git
  6.   GIT_TAG v2.0.2
  7. )
  8. FetchContent_MakeAvailable(cli)

  10. add_executable(main-project)
  11. target_link_libraries(main-project PRIVATE cli::cli)

  13. ```

Compilation of the examples


You can find some examples in the directory "examples". Each .cpp file corresponds to an executable. Each example can be compiled by including cli (and optionally asio/boost header files) and linking pthread on linux (and optionally boost system).

To compile the examples using cmake, use:

  1. ``` sh
  2. mkdir build && cd build

  4. # compile only the examples that do not require boost/asio libraries
  5. cmake .. -DCLI_BuildExamples=ON

  7. # compile the examples by using boost asio libraries
  8. cmake .. -DCLI_BuildExamples=ON -DCLI_UseBoostAsio=ON
  9. # or: cmake .. -DCLI_BuildExamples=ON -DCLI_UseBoostAsio=ON -DBOOST_ROOT=<boost_path>

  11. # compile the examples by using standalone asio library
  12. cmake .. -DCLI_BuildExamples=ON -DCLI_UseStandaloneAsio=ON
  13. # or: cmake .. -DCLI_BuildExamples=ON -DCLI_UseStandaloneAsio=ON -DASIO_INCLUDEDIR=<asio_path>

  15. cmake --build .

  17. ```

In the same directory you can also find:

GNU make files (Makefile.noasio, Makefile.boostasio, Makefile.standaloneasio)
Windows nmake files (makefile.noasio.win, makefile.boostasio.win, makefile.standaloneasio.win)
a Visual Studio solution

If needed, you can specify asio library path in the following ways:

GNU Make


for boost:

  1. ``` sh
  2. make CXXFLAGS="-isystem <boost_include>" LDFLAGS="-L<boost_lib>"

  4. ```

example:

  1. ``` sh
  2. make CXXFLAGS="-isystem /opt/boost_1_66_0/install/x86/include" LDFLAGS="-L/opt/boost_1_66_0/install/x86/lib"

  4. ```

for standalone asio:

  1. ``` sh
  2. make CXXFLAGS="-isystem <asio_include>"

  4. ```

example:

  1. ``` sh
  2. make CXXFLAGS="-isystem /opt/asio-1.18.0/include"

  4. ```

(if you want to use clang instead of gcc, you can set the variable CXX=clang++)

Windows nmake


Optionally set the environment variable ASIO or BOOST to provide the library path. Then, from a visual studio console, start nmake passing one of the makefile.*.win files.

E.g., from a visual studio console, use one of the following commands:

  1. ``` sh
  2. # only compile examples that do not require asio
  3. nmake /f makefile.noasio.win
  4. # compile examples using boost asio
  5. set BOOST=<path of boost libraries>
  6. nmake /f makefile.boostasio.win
  7. # compile examples using standalone asio
  8. set ASIO=<path of asio library>
  9. nmake /f makefile.standaloneasio.win

  11. ```

Visual Studio solution


Currently, the VS solution compiles the examples only with the BOOST dependency.

Set the environment variable BOOST. Then, open the file cli/examples/examples.sln

Compilation of the Doxygen documentation


If you have doxygen installed on your system, you can get the html documentation of the library in this way:

  1. ``` sh
  2. cd doc/doxy
  3. doxygen Doxyfile

  5. ```

CLI usage


Commands and shortcuts


At the start of your  application, cli is presenting a prompt with the name you provided in the Cli constructor. This means you're in the root menu.

To enter in a submenu, just type the submenu name: you should see the prompt change to reflect the name of the current submenu.

To go back to the parent menu, you must enter the name of the parent menu.

In any menu, you can enter:

exit : to exit the cli
help : to print the list of the commands available with a description
a submenu name: to enter the submenu
the parent menu name: to return to the parent menu
a command in the current menu: to exec the command
a command in a submenu (using the full path): to exec the command

You can also use:

up and down arrow keys: to navigate the history of commands
tab key: to autocomplete the command / menu

Parameter parsing


The cli interpreter can manage correctly sentences using quote (') and double quote ("). Any character (spaces too) comprises between quotes or double quotes are considered as a single parameter of a command. The characters ' and " can be used inside a command parameter by escaping them with a backslash.

Some example:

  1. ``` sh
  2. cli> echo "this is a single parameter"
  3. this is a single parameter
  4. cli> echo 'this too is a single parameter'
  5. this too is a single parameter
  6. cli> echo "you can use 'single quotes' inside double quoted parameters"
  7. you can use 'single quotes' inside double quoted parameters
  8. cli> echo 'you can use "double quotes" inside single quoted parameters'
  9. you can use "double quotes" inside single quoted parameters
  10. cli> echo "you can escape \"quotes\" inside a parameter"              
  11. you can escape "quotes" inside a parameter
  12. cli> echo 'you can escape \'single quotes\' inside a parameter'
  13. you can escape 'single quotes' inside a parameter
  14. cli> echo "you can also show backslash \\ ... "                
  15. you can also show backslash \ ...

  17. ```

Async programming and Schedulers


cli is an asynchronous library, and the handlers of commands are executed by a scheduler, in a thread provided by the user (possibly the main thread), this allows you to develop a single thread application without need to worry about synchronization.

So, your application must have a scheduler and pass it to CliLocalTerminalSession.

The library provides three schedulers:

LoopScheduler
BoostAsioScheduler
StandaloneAsioScheduler

LoopScheduler is the simplest: it does not depend on other libraries and should be your first choice if you don't need remote sessions.

BoostAsioScheduler and StandaloneAsioScheduler are wrappers around asio io_context objects. You should use one of them if you need a BoostAsioCliTelnetServer or a StandaloneAsioCliTelnetServer because they internally use boost::asio and asio.

You should use one of them also if your application uses asio in some way.

After setting up your application, you must call Scheduler::Run() to enter the scheduler loop. Each command handler of the library will execute in the thread that called Scheduler::Run().

You can exit the scheduler loop by calling Scheduler::Stop() (e.g., as an action associated to the "exit" command).

You can submit work to be executed by the scheduler invoking the method Scheduler::Post(const std::function<void()>& f). Schedulers are thread safe, so that you can post function object from any thread, to be executed in the scheduler thread.

This is an example of use of LoopScheduler :

  1. ``` sh
  2. ...
  3. LoopScheduler scheduler;
  4. CliLocalTerminalSession localSession(cli, scheduler);
  5. ...
  6. // in another thread you can do:
  7. scheduler.Post([](){ cout << "This will be executed in the scheduler thread\n"; });
  8. ...
  9. // start the scheduler main loop
  10. // it will exit from this method only when scheduler.Stop() is called
  11. // each cli callback will be executed in this thread
  12. scheduler.Run();
  13. ...
  14. ```

This is an example of use of BoostAsioScheduler

  1. ``` sh
  2. ...
  3. BoostAsioScheduler scheduler;
  4. CliLocalTerminalSession localSession(cli, scheduler);
  5. BoostAsioCliTelnetServer server(cli, scheduler, 5000);
  6. ...
  7. scheduler.Run();
  8. ...
  9. ```

Finally, this is an example of use of BoostAsioScheduler when your application already uses boost::asio and has a boost::asio::io_context object (the case of standalone asio is similar).

  1. ``` sh
  2. ...
  3. // somewhere else in your application
  4. boost::asio::io_context ioc;
  5. ...
  6. // cli setup
  7. BoostAsioScheduler scheduler(ioc);
  8. CliLocalTerminalSession localSession(cli, scheduler);
  9. BoostAsioCliTelnetServer server(cli, scheduler, 5000);
  10. ...
  11. // somewhere else in your application
  12. ioc.run();
  13. ...
  14. ```

Adding menus and commands


You must provide at least a root menu for your cli:

  1. ``` sh
  2. // create a menu (this is the root menu of our cli)
  3. auto rootMenu = make_unique<Menu>("myprompt");

  5. ... // fills rootMenu with commands

  7. // create the cli with the root menu
  8. Cli cli(std::move(rootMenu));

  10. ```

You can add menus to existing menus, to get a hierarchy:

  1. ``` sh
  2. auto rootMenu = make_unique<Menu>("myprompt");

  4. auto menuA = make_unique<Menu>("a_prompt");
  5. rootMenu->Insert( std::move(menuA) );

  7. auto menuAA = make_unique<Menu>("aa_prompt");
  8. menuA->Insert( std::move(menuAA) );

  10. auto menuAB = make_unique<Menu>("ab_prompt");
  11. menuA->Insert( std::move(menuAB) );

  13. auto menuAC = make_unique<Menu>("ac_prompt");
  14. menuA->Insert( std::move(menuAC) );

  16. auto menuACA = make_unique<Menu>("aca_prompt");
  17. menuAC->Insert( std::move(menuACA) );

  19. auto menuB = make_unique<Menu>("b_prompt");
  20. rootMenu->Insert( std::move(menuB) );

  22. auto menuBA = make_unique<Menu>("ba_prompt");
  23. menuB->Insert( std::move(menuBA) );

  25. auto menuBB = make_unique<Menu>("bb_prompt");
  26. menuB->Insert( std::move(menuBB) );
  27. ```

This results in this tree:

  1. ``` sh
  2. myprompt
  3.     |
  4.     +--- a_prompt
  5.     |        |
  6.     |        +--- aa_prompt
  7.     |        |
  8.     |        +--- ab_prompt
  9.     |        |
  10.     |        +--- ac_prompt
  11.     |                |
  12.     |                +--- aca_prompt
  13.     |
  14.     +--- b_prompt
  15.              |
  16.              +--- ba_prompt
  17.              |
  18.              +--- bb_prompt

  20. ```

Finally, you can add commands to menus, using the Menu::Insert method. The library supports adding commands handler via:

free functions
std::function
lambdas

  1. ``` sh
  2. static void foo(std::ostream& out, int x) { out << x << std::endl; }

  4. std::function<void(std::ostream& out, int x)> fun(foo);

  6. ...

  8. myMenu->Insert("free_function", foo);

  10. myMenu->Insert("std_function", fun);

  12. myMenu->Insert("lambda", [](std::ostream& out, int x){ out << x << std::endl; } );

  14. ```

There is no limit to the number of parameters that a command handler can take. They can be basic types and std::string s

  1. ``` sh
  2. myMenu->Insert(
  3.     "mycmd",
  4.     [](std::ostream& out, int a, double b, const std::string& c, bool d, long e)
  5.     {
  6.         ...
  7.     } );

  9. myMenu->Insert(
  10.     "complex",
  11.     [](std::ostream& out, std::complex c)
  12.     {
  13.         ...
  14.     } );
  15. ```

or they can be custom types overloading the std::istream << operator :

  1. ``` sh
  2. struct Foo
  3. {
  4.     friend istream & operator >> (istream &in, Foo& p);
  5.     int value;
  6. };

  8. istream & operator >> (istream& in, Foo& p)
  9. {
  10.     in >> p.value;
  11.     return in;
  12. }

  14. myMenu->Insert(
  15.     "foo",
  16.     [](std::ostream& out, Foo f)
  17.     {
  18.         ...
  19.     } );

  21. ```

If you need it, you can have a command handlers taking an arbitrary number of std::string parameters:

  1. ``` sh
  2. myMenu->Insert(
  3.     "mycmd",
  4.     [](std::ostream& out, const std::vector<std::string>& pars)
  5.     {
  6.         ...
  7.     } );

  9. ```

Please note that in this case your command handler must take only oneparameter of type std::vector<std::string>.

Enter and exit actions


You can add an enter action and/or an exit action (for example to print a welcome/goodbye message every time a user opens/closes a session, even a remote one):

  1. ``` sh
  2. Cli cli(std::move(rootMenu));
  3. cli.EnterAction(
  4.     [&enterActionDone](std::ostream& out) { out << "Welcome\n"; });
  5. cli.ExitAction(
  6.     [&enterActionDone](std::ostream& out) { out << "Goodbye\n"; });
  7. ```

Unicode


cli uses the input and output stream objects provided by the standard library (such as std::cin and std::cout ) by default, so currently cli does not have effective support for unicode input and output.

If you want to handle unicode input and output, you need to provide custom i/o unicode aware stream objects derived from std::istream or std::ostream.

For example, you can use boost::nowide as an alternative to implement UTF-8 aware programming in a out-of-box and cross-platform way:

  1. ``` sh
  2. #include <boost/nowide/iostream.hpp> // for boost::nowide::cin and boost::nowide::cout
  3. // other headers...

  5. cli::Cli app{/*init code*/};

  7. // FileSession session{app}; // default

  9. // now, all parameters is in a UTF-8 encoded std::string
  10. // pass boost::nowide::cin and boost::nowide::cout as parameters(FileSession requires std::istream and std::ostream)
  11. FileSession session{app, boost::nowide::cin, boost::nowide::cout};

  13. /*....*/

  15. // you can call this command funtion and get UTF-8 encoded input data (p), just use it.
  16. // boost::noide helps us avoid the trouble
  17. // caused by inconsistent default code page and encoding of the console under different platforms.
  18. void a_command_function(std::ostream& os, std::string const& p) {
  19. /* implements */
  20. }

  22. ```

Of course, you can also pass stream objects with other capabilities to achieve more customized input and output functions.

License


Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt )

Contact


Please report issues here: http://github.com/daniele77/cli/issues

and questions, feature requests, ideas, anything else here: http://github.com/daniele77/cli/discussions

You can always contact me via twitter at @DPallastrelli

Contributing (We Need Your Help!)


Any feedback from users and stakeholders, even simple questions about how things work or why they were done a certain way, carries value and can be used to improve the library.

Even if you just have questions, asking them in GitHub Discussions provi