A cross-platform library for output stream manipulation using ANSI escape sequences.
osmanip is a C++ library containing useful tools to manipulate ANSI escape sequences and customize the output stream of your programs. Within this tools you can add colors and styles to the printed strings, change cursor location on the terminal and manage other tools like progress bars and terminal graphics. Using this features may be very useful to adorn your general output stream log or to perform cursor operations.
This is a fully type- and thread-safe library with automatic memory management, with only indispensable dependencies.
It can be installed from source or via vcpkg
. See this section for further details.
If you want to mention this software in one of your project / articles, please cite it.
If you use this library please tell me so I can add you to the list of know projects which use this library.
If you want to contribute to the repository, please read this file before. If you have ideas to propose write a post into the discussion section.
Code documentation is generated using Doxygen and can be accessed here. An extra wiki is also provided and contains how-to guides and many examples.
Colors and styles manipulators examples:
Progress bars examples:
2D terminal-graphics examples:
The software is and will stay free, but if you want to support me with a donation it would be really appreciated!
#include <iostream>
#include <osmanip/manipulators/colsty.hpp>
// Print a red string
std::cout << osm::feat( osm::col, "red" ) << "This string is red!" << osm::feat( osm::rst, "color" );
// Print a bold string
std::cout << osm::feat( osm::sty, "red" ) << "This string is bold!" << osm::feat( osm::rst, "bd/ft" );
#include <iostream>
#include <osmanip/manipulators/cursor.hpp>
// Move the cursor right by 2 spaces
std::cout << osm::feat( osm::crs, "right", 2 ) << "Cursor moved!";
#include <iostream>
#include <osmanip/manipulators/cursor.hpp>
// Output a bell sound
std::cout << osm::feat( osm::tcs, "bell" );
#include <iostream>
#include <osmanip/manipulators/printer.hpp>
osm::Decorator my_shell;
// Change std::cout predefined style and color
my_shell.setColor( "green", std::cout );
my_shell.setStyle( "underlined", std::cout );
my_shell( std::cout ) << "The stdout stream has been changed using the Decorator class!" << "\n";
// Change std::cerr predefined style and color
my_shell.setColor( "red", std::cerr );
my_shell.setStyle( "bold italics", std::cerr ); // NOTE: added 2 styles
my_shell( std::cerr ) << "The stderr stream has been changed using the Decorator class!" << "\n";
More examples and how-to guides can be found here.
Why choosing this library for ANSI escape sequences manipulation:
#include <iostream>
#include <osmanip/progressbar/progressbar.hpp>
#include <osmanip/utility/options.hpp>
osm::ProgressBar<int> percentage_bar;
percentage_bar.setMin( 5 );
percentage_bar.setMax ( 46 );
percentage_bar.setStyle( "indicator", "%" );
std::cout << "This is a normal percentage bar: " << "\n";
osm::OPTION( osm::CURSOR::OFF ); // Hide cursor for better output rendering
for ( int i = percentage_bar.getMin(); i < percentage_bar.getMax(); i++ )
{
percentage_bar.update( i );
//Do some operations...
}
osm::OPTION( osm::CURSOR::ON );
#include <iostream>
#include <osmanip/progressbar/progressbar.hpp>
#include <osmanip/utility/options.hpp>
osm::ProgressBar<int> loading_bar( 3, 25 );
loading_bar.setStyle( "loader", "#" );
loading_bar.setBrackets( "{", "}" );
loading_bar.setMessage( "processing..." );
std::cout << "This is a loading bar: with message: " << "\n";
osm::OPTION( osm::CURSOR::OFF ); // Hide cursor for better output rendering
for ( int i = loading_bar.getMin(); i < loading_bar.getMax(); i++ )
{
loading_bar.update( i );
//Do some operations...
}
osm::OPTION( osm::CURSOR::ON );
#include <iostream>
#include <osmanip/progressbar/progressbar.hpp>
#include <osmanip/utility/options.hpp>
osm::ProgressBar<int> progress_bar( 3, 25 );
progress_bar.setStyle( "complete", "%", "■" );
progress_bar.setBrackets( "[", "]" );
progress_bar.setMessage( "elaborating..." );
progress_bar.setRemainingTimeFlag( "on" );
progress_bar.setColor( "red" );
std::cout << "This is a mixed progress bar with color and time remaining info: " << "\n";
osm::OPTION( osm::CURSOR::OFF ); // Hide cursor for better output rendering
for ( int i = progress_bar.getMin(); i < progress_bar.getMax(); i++ )
{
progress_bar.update( i );
//Do some operations...
}
osm::OPTION( osm::CURSOR::ON );
#include <iostream>
#include <osmanip/progressbar/progressbar.hpp>
#include <osmanip/utility/options.hpp>
osm::ProgressBar<int> spinner;
spinner.setMin( 2 );
spinner.setMax ( 33 );
spinner.setStyle( "spinner", "/-\\|" );
std::cout << "This is a progress spinner: " << "\n";
osm::OPTION( osm::CURSOR::OFF ); // Hide cursor for better output rendering
for ( int i = spinner.getMin(); i < spinner.getMax(); i++ )
{
spinner.update( i );
//Do some operations...
}
osm::OPTION( osm::CURSOR::ON );
#include <iostream>
#include <osmanip/progressbar/progress_bar.hpp>
#include <osmanip/redirection/output_redirector.hpp>
osm::OutputRedirector redirector( "output.txt" );
std::cout << "I am printing to the console!\n";
// Redirect output to the file
redirector.begin();
std::cout << "Now I am printing to a file!\n";
osm::ProgressBar<int> my_bar;
// ...
for( int i = my_bar.getMin(); i < my_bar.getMax(); i++ )
{
// Flush the buffer at the start of each loop
redirector.flush();
my_bar.update( i );
}
// Return output to the console
redirector.end();
More examples and how-to guides can be found here.
Why choosing this library for progress bars? Some properties:
#include <osmanip/manipulators/colsty.hpp>
#include <osmanip/graphics/canvas.hpp>
osm::Canvas canvas(10,10);
canvas.setBackground( '.', osm::feat( osm::col, "bg white" ) + osm::feat( osm::col, "black" ) );
std::cout << "Display an animation in a canvas\n";
for( uint i = 0; i < 10; i++ )
{
canvas.clear();
canvas.put( 0, 2, 'x' );
canvas.put( i, 3, 'A', osm::feat( osm::col, "red" ) );
canvas.put( 5, 0, 'B', osm::feat( osm::col, "blue" ) );
canvas.put( 7, 8, 'Z', osm::feat( osm::col, "bg cyan" ) + osm::feat( osm::col, "black" ) + osm::feat( osm::sty, "bold" ) );
canvas.refresh();
}
#include <functional>
#include <osmanip/manipulators/colsty.hpp>
#include <osmanip/graphics/canvas.hpp>
osm::Plot2DCanvas plot_2d_canvas( 50, 20 );
std::cout << "\n" << "Plot2DCanvas with sin and cos" << "\n";
plot_2d_canvas.setBackground( ' ', osm::feat( osm::col, "bg white" ) );
plot_2d_canvas.enableFrame( true );
plot_2d_canvas.setFrame( osm::FrameStyle::BOX, osm::feat( osm::col, "bg white" ) + osm::feat( osm::col, "black" ) );
plot_2d_canvas.enableFrame( true );
plot_2d_canvas.setFrame( osm::FrameStyle::BOX, osm::feat( osm::col, "bg white" ) + osm::feat( osm::col, "black" ) );
plot_2d_canvas.setScale( 1/3.14, 0.2) ;
for( float i = 0; i < 40; i++ )
{
plot_2d_canvas.setOffset( i/3.14, -2 );
plot_2d_canvas.clear();
plot_2d_canvas.draw( std::function <float( float )>( []( float x ) ->
float{ return std::cos( x ); } ), 'X', osm::feat( osm::col, "bg white" ) + osm::feat( osm::col, "bd red" ) );
plot_2d_canvas.draw( std::function <float( float )>( []( float x ) ->
float{ return std::sin( x ); } ), 'X', osm::feat( osm::col, "bg white" ) + osm::feat( osm::col, "bd blue" ) );
plot_2d_canvas.refresh();
sleep_for( milliseconds( 100 ) );
}
More examples and how-to guides can be found here.
Why choosing this library for terminal graphics:
// Enable ANSI escape sequences
osm::OPTION( osm::ANSI::ON );
// doing some stuff...
osm::OPTION( osm::ANSI::OFF );
// Enable unicode characters
osm::OPTION( osm::UNICODECH::ON );
// doing some stuff...
osm::OPTION( osm::UNICODECH::OFF );
More examples and how-to guides can be found here.
Steps to be reproduced:
1) Download one of the releases of the repository
2) Unzip and enter the downloaded repository directory
3) Install and compile the library and its dependencies:
cmake -B build
Install:
sudo cmake --build build --target install
:warning:
sudo
is not required on Windows.
Mandatory prerequisites (automatically installed with the script):
This is the list of available package managers for osmanip
:
Tu use on or more headers of the library:
#include <osmanip/module_folder/module_name.hpp>
If you are using the library in a program, add the -losmanip
flag to
link source code.
:warning:: remember also to add
-pthread
flag if you want to use some thread-dependent libraries like ** progressbar/multi_progress_bar.hpp** .
To get an installed version of the library:
find_package( osmanip )
then, to link it to a target:
target_link_libraries( ${TARGET} osmanip::osmanip )
Examples are compiled during the installation procedure.
To run all the examples:
./build/examples/osmanip_manipulators
./build/examples/osmanip_progressbar
./build/examples/osmanip_graphics
./build/examples/osmanip_redirection
:warning: executables end with
.exe
if you are on Windows of course.
To compile tests you must build the app in debug mode:
cmake -B build -DCMAKE_BUILD_TYPE=Debug
sudo cmake --build build --target install
:warning: remember to install the library before launching include tests, or an error will appear. :warning: if you want to build the library in debug mode, but without compiling tests use also the option
-DOSMANIP_TESTS=OFF
.
Tests are produced using -Wall -Wextra -pedantic
flags. To check them you need some prerequisites:
The doctest package is automatically installed with the installation step. Also the clang-format package is required. The format procedure is performed automatically when compiling.
To launch all tests simultaneously:
./test/all_tests.sh
EXTRA: to check that only the needed headers are include use this script:
./test/IWYU.sh
elapsedTime()
method to the ProgressBar
class, to show elapsed progress bar time and substitute it to the already existing getTime()
method.output_redirector
.Gianluca Bianco |
MiguelMJ |
Ted Lyngmo |
myermo |
nick-botticelli |
Joel Thomas |
oz_10 |
Kai Pastor |