Skip to content

Home

Jump to bottom
Daniele Pallastrelli edited this page Dec 10, 2020 · 17 revisions

Welcome to the cli wiki!

On this page, there are some random notes about the library. The target is mainly contributors. Eventually, some of these thoughts will end up in the CONTRIBUTING.md, README.md, and other repo files.

Goals (and non-goals)

  • The library goal is to provide an interactive command line to C++ programs (in particular to asynchronous programs). The behavior of the CLI provided should be as similar as possible to bash as for as history and autocompletion. One of the most useful features for servers and embedded software is the telnet server, i.e., its capability to provide a cli through a TCP port, so that a remote user can open a telnet client (or netcat) and interact with the cli. Moreover, we try to keep the menu structure as flexible as possible.
  • I started this library out of a specific need of mine, after searching in vain for something similar. After developing it, I thought it would be nice to share it with other developers that might need it. I wrote this library out of a specific need, and not to show off my C++/design/other skills. Please, remember this before writing a comment, open an issue, or doing a pull request.
  • Every c++14 compliant compiler should be able to compile the library. This is because many projects already using the library are constrained to old compilers. For this reason, I can’t accept pull requests exploiting C++ features newer than C++14 standard. The same applies if you rewrite any C++17 features and include them in the library: unless this is the only way to implement a very useful feature of cli library, I won’t accept the pull request.
  • TODO ...

Roadmap

  • Dynamically attach/detach/enable/disable of commands and submenus (issue #15)
  • Better description for parameters in help (explicit description VS type based)
  • Using variadic template when adding a new command
  • cmake support
  • Adding .clang-format ?
  • Optionally delimitate string parameters by " (issue #38)
  • Add vcpkg support (issue #23)
  • Add automated test
  • Add persistence of history
  • Limit boost dependency to CliTelnetServer
  • User defined arguments (issue #69)
  • Session context in menu items (issue #49)

FAQ

Isn’t the name “cli” a little bit too generic?

Yes, it is. The library was initially developed to satisfy my needs, to be included just in my projects. For that purpose, “cli” was fine. Unfortunately, now that the library starts to get used by other people, the original name starts to show all its limits. First of all, it’s difficult to find it on google. Then, the term “cli” is ambiguous because it can refer to the general concept of an interactive command line, to the general concept of command-line parameter parsing, or several libraries.

So, I plan to change the name of the library in the future. For this I want to ask you:

  • Which issues will I be facing by changing the name of an existing GitHub project? (e.g., link name, repository name, ...)
  • Any suggestion for a good name? A good name for me is ideally one self-explanatory and not already used by other well-known projects. If I don’t find a self-explanatory name, I will opt for some name with no meaning at all.

To answer any of these questions, you can use the github issue tracker, the forum, or — even better — my twitter account @DPallastrelli. Eventually, I will do a twitter poll to decide on a good name.

Isn’t the snake_case naming convention better than the CamelCase for C++ code?

I don’t think it’s better (with CamelCase you have way more combinations of identifiers available) but surely it is the de-facto standard in modern C++ code. Unfortunately, the cli library started inside projects with that convention, and the first public releases had CamelCase APIs. Since I don’t want to break code already using the library just for a matter of “conventions”, I won’t change my code to snake_case.

However. If

  1. The project will reach 1000 stars AND
  2. Someone opens an item in the GitHub issue tracker asking me to change to snake_case AND
  3. The item reach at least 800 stars

then, I will change the case of the whole source code, breaking the API.

Why don't you use clang-format to format cli source files?

I admit I have worked on a .clang-format file for quite a while, in the hope to find the best options to get a result similar to what I'm used to. Unfortunately, I find clang-format quite limited and I gave up.

After a while, I realized that after all, it's not a great idea to let a tool format your code for you. Yes, on huge codebases, with lots of developers working on it, it might be useful to use a tool to keep the formatting consistent. On the other hand, on small projects, with one (or few) developers, the formatting should be done at hand because some kind of formatting conveys information, and definitely, you don't want a tool to remove that information.

Other

  • I’d like to publish a list of projects using the library, maybe on a page of this wiki or — in the future — in the library website (if the library will ever have one). So, I invite every user of the library who wants its project to be inserted into the list, to contact me via Twitter at @DPallastrelli or through the github forum or issue tracker.
  • In general, to have updates about the library you should follow my Twitter account @DPallastrelli
Clone this wiki locally