Library with output stream tools like: colors and styles manipulators and progress bars

---

Table of contents

• Introduction
• Documentation
• List of features
  • Colors and styles manipulation
  • Cursor navigation
  • Terminal control sequences
  • Progress bars

Introduction

Here I want to present you osmanip: my personal C++ library containing useful output-stream tools to customize your output stream. Probably there are already some similar libraries in the web that do the same job, but since I personally don't like them at all I preferred writing my own code for that. Thanks to this you can manipulate the output stream of your program with colors, styles (ex: bold, italics, etc...) and helper tools like progress bars and CPU-usage monitor objects. Using this feaures may be very useful to better read error messages or special information you want to be sure other users see when they run your code, or to adorn your general output stream log.

This software has been built for Linux systems (it has been tested with Ubuntu and WSL). Its compatibility has not been tested with Windows or MacOS operating systems.

If you want to use this software in one of your project, please cite it. You can find the citation template here.

NOTE: all the manipulators of this library are compatible with iomanip.

The software is and will stay free, but if you want to support me with a donation it would be really appreciated!

Documentation

In the doc folder useful documentation files are stored, in order to help the user learning how to properly use the library:

• Repository structure: contains general information about the files and folders of the repository.
• Code structure: contains general information about the code structure of the library, therefore details on classes, functions and variables used in it.
• Download and install: a guide to download, install and run the library into your system.
• Todo: contains a list of future implementations of the library.

List of features

Here you can find examples of all the features supported in the current version of the manipulator and how to use them.

NOTE: all the examples are written supposing to use the following directive:

using namespace osm;

Colors and styles manipulation

List of the supported color / style features (part of the output of the main.cpp program):

Blink string feature:

If you want to change for example the output stream color into red you have to call the feat function and give it the col map as a first argument and the color name as the second one. See the following example:

cout << feat( col, "red" ) << "This stream is red!" << reset( "color" );

This will color the output stream in red until the reset( "color" ) function is met again, in order to reset the output stream color.

It is possible to access a wider variety of colors by directly using the RGB( int r, int g, int b ) function and the corresponding rgb color codes from this page. For example:

std::string DeepPink = RGB( 255, 20, 147 );

cout << DeepPink << "This stream is deep pink!" << reset( "color" );

You can also print mixed color and style strings:

cout << feat( sty, "underlined" ) << feat( col, "red" ) << "This is an underlined red string." << reset( "all" );

This will underline and color the output stream in red until the reset( "all" ) function is met again, in order to reset all the output stream color / style.

If you want to know all the available commands, visit the code structure page.

Cursor navigation

You can modify the cursor navigation in all the 4 directions (up, down, right, left) by using the feat function within the crs map, in this way:

cout << feat( crs, "left" ) << "Moving cursor on the left";

You can additionally add a third argument to the feat function, in order to increase the parameter of the ANSII code of the cursor navigation (see csmanip.cpp).

If you want to know all the available commands, visit the code structure page.

It is not so easy to show a simple example of this feature. Certainly, a very intuitive application is for progress bars creation, explained in the next section. See the progress bar update method definition in progress_bar.cpp for more information.

Terminal control sequences

You can add a terminal control sequency to your output by using the feat function within the tcs map, in this way:

cout << feat( tcs, "bell" );

For example, the previous command will output a bell sound from your computer.

If you want to know all the available commands, visit the code structure page.

Progress bars

From release 2.0.0 of the library, also progress bars have been introduced.

Main proprieties:

• Compatible with positive or negative variable of any standard type (integer, float, double and others).
• Maximum and minimum values can be set with any value you prefer and the progress bar will be self-built with respect to them.
• Each progress bar feature can be fully customized (messages, style, color, brackets type etc...) regarding to your requirements.
• It is thread-safe.

Here you can find some examples about how to use them into your code.

If you want to know all the available commands, visit the code structure page.

It may happens that cursor disappears if stopping a program in which a progress bar is running. In this case you have to simply close the terminal and open a new one to restore it.

Initialize and use a percentage progress bar:

ProgressBar <int> percentage_bar;
percentage_bar.setMin( 5 );
percentage_bar.setMax ( 46 );
percentage_bar.setStyle( "indicator", "%" );

cout << "This is a normal percentage bar: " << endl;
 for ( int i = percentage_bar.getMin(); i < percentage_bar.getMax(); i++ )
  {
   sleep_for( milliseconds( 100 ) );
   percentage_bar.update( i );
   //Do some operations...
  }

NOTE: sleep_for( milliseconds( 100 ) ) has been inserted to delay the loop in order to better visualize the progress bar into this .gif file. You don't need to use it in your code.

NOTE: you can insert each min and max value you prefer, like also -3 and 52 for example, and the bar will work perfectly too.

Add a message to a percentage bar and change its style:

percentage_bar.setMessage( " processing..." );
percentage_bar.setStyle( "indicator", "/100" );

Add CPU time consuming info when using a progress bar in loops:

cout << "This is a percentage bar with time consuming info: " << endl;
 for ( int i = percentage_bar.getMin(); i < percentage_bar.getMax(); i++ )
  {
   percentage_bar.setBegin();
   sleep_for( milliseconds( 100 ) );
   percentage_bar.update( i );
   //Do some operations...
   percentage_bar.setEnd();
  }
cout << endl << "Time needed to complete the previous cycle: " << percentage_bar.getTime() << " ms." << endl;

It is possible to add also colors and much more.

You can also create a classic loading bar:

ProgressBar <int> loading_bar;
loading_bar.setMin( 3 );
loading_bar.setMax ( 25 );
loading_bar.setStyle( "loader", "#" );
loading_bar.setBrackets( "{", "}" );
loading_bar.setMessage( "processing..." );

cout << "This is a normal loading bar: " << endl;
for ( int i = loading_bar.getMin(); i < loading_bar.getMax(); i++ )
 {
  sleep_for( milliseconds( 100 ) );
  loading_bar.update( i );
  //Do some operations...
 }

And customize it with messages and time-consuming info, like the previous percentage.

If using mixed bar styles, for example:

progress_bar.setStyle( "complete", "%", "#" );

you can create loading bar with percentage counter (mixed bar):

You can also add new customized styles, both for indicator and loader:

progress_bar.addStyle( "indicator", "|100" );
progress_bar.addStyle( "loader", ">" );
progress_bar.setStyle( "complete", "|100", ">" );