ftz.Lyberta.net

Modern C++ goodness

ftz Console

Command line interpreter library

This library implements a command line interpreter with a simple syntax:

command1 argument1 "argument two"; command2 "argument;one"

It provides easy to use interface for defining variables of arbitrary type and commands taking arbitrary types that are automatically parsed under the hood using operator>> and operator<<.

The main Console::Core class does internal synchronization and can be safely shared between multiple threads.

Example code

/// \file
/// \brief This file shows an example usage of Console::UI::StdUI class along
/// with Console::Core.
/// \author Lyberta
/// \copyright GNU GPLv3 or any later version.

#include <iostream>

#include <ftz/Console/UI/StdUI.h>
#include <ftz/Console/StandardLibrary.h>

using namespace std::string_literals;

int main(int argc, char* argv[])
try
{
	// Console core and user interface are separated into different classes for
	// flexibility.
	ftz::Console::Core consolecore;
	ftz::Console::UI::StdUI consoleui{consolecore};

	// By default there are no commands or variables registered. Now it is a
	// good time to create some. To make things easier to manage, symbols are
	// grouped into libraries. There is a console standard library which
	// provides essential commands such as "echo" or "list".
	ftz::Console::StandardLibrary constdlib{consolecore};

	// Create commands to terminate the application.
	auto exit = consolecore.CreateCommand("exit"s, [&]{ consoleui.Stop(); },
		std::make_tuple(), "Quits the application."s);
	auto quit = consolecore.CreateCommand("quit"s, [&]{ consoleui.Stop(); },
		std::make_tuple(), "Quits the application."s);

	// Now it's time to get our message loop rolling.
	consoleui.Run();
}
catch (std::exception& e)
{
	std::cerr << "Exception caught: " << e.what() << '\n';
}
catch (...)
{
	std::cerr << "Unknown exception.\n";
}

Key features

  • Cross platform - written in pure ISO C++17 (+ #pragma once).
  • Unicode-aware - uses UTF-8 under the hood.
  • Internal synchronization of key classes - don’t worry about data races in multithreaded applications.
  • User interface independence - works with any interface that can transform user input into text. Several ready-made classes (both text and GUI) are provided.
  • Free software - released under the terms of GNU GPLv3 or any later version.

Dependencies

  • ftz General
  • ftz Platform - optional, used for example logger
  • ftz Unicode - used for example TUI.
  • Ncurses - optional, used for example TUI
  • Qt 5 - optional, used for example GUI

Compiler support

  • G++ 8 or newer with libstdc++ and libstdc++fs

How to get

You need to use Conan to install and use this library. To install Conan on APT-based distros you would typically do:

# apt install python-pip
$ pip install conan

Then add official ftz repository:

$ conan remote add ftz https://conan.ftz.lyberta.net

Then you need to follow a Conan tutorial to declare that your project depends on this library, for example, using conanfile.txt:

[requires]
ftzConsole/Latest@Lyberta/Latest

Or using conanfile.py:

build_requires = "ftzConsole/Latest@Lyberta/Latest"

The rest depends on your build system. In CMake you would do:

# Importing Conan settings.
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup(TARGETS)

# Adding example executable target.
add_executable(Example ...)

# Specifying libraries to link executable to.
target_link_libraries(Example PRIVATE CONAN_PKG::ftzConsole)

After that in your source code you include files like this:

#include <ftz/Console/SomeHeader.h>

To build your code, remember to execute conan install before calling conan build or cmake so your dependencies will be set correctly.

Source code

API reference

Manually building the library

Build dependencies:

  • Git
  • G++ 8 or newer
  • CMake 3.8 or newer
  • Conan 1.2 or newer
  • Ncurses
  • Qt 5

To install dependencies on Debian Testing you would invoke:

# apt install git g++-8 cmake python-pip libncursesw5-dev qtbase5-dev
$ pip install conan

If you didn’t have Conan installed before, you probably need to configure the default profile:

$ conan profile new --detect default
$ conan profile update settings.compiler.version=8 default
$ conan profile update settings.compiler.libcxx=libstdc++11 default
$ conan profile update settings.cppstd=17 default

Add official ftz repository to Conan:

$ conan remote add ftz https://conan.ftz.lyberta.net

Clone the repository and switch into it:

$ git clone https://gitlab.com/ftz/console.git
$ cd console

Build the Conan package with your specified user and channel:

$ conan create . User/Channel