indicators

repository·master·Indexed 25 days ago

https://github.com/p-ranav/indicators

A thread-safe, header-only C++ library for displaying progress indicators in the terminal, including progress bars, spinners, and block progress bars. It supports multi-byte Unicode characters, emojis, and provides tools for managing multiple progress bars via MultiProgress and DynamicProgress classes. The library also includes a Python utility, amalgamate.py, for combining source and header files into a single header.

Tokens
4.2K
Snippets
13
Records
22
Agent score
36%

What's inside indicators

  1. Use BlockProgressBar with iterables

    master

    To track progress while iterating over a collection (like a std::vector), use indicators::BlockProgressBar and provide the total size of the collection via option::MaxProgress. You can update the progress bar in each iteration using bar.tick() and update descriptive text using bar.set_option(option::PostfixText{...}).

    #include <chrono>
    #include <indicators/block_progress_bar.hpp>
    #include <indicators/cursor_control.hpp>
    #include <thread>
    
    int main() {
    
      // Hide cursor
      indicators::show_console_cursor(false);
    
      // Random list of numbers
      std::vector<size_t> numbers;
      for (size_t i = 0; i < 1259438; ++i) {
          numbers.push_back(i);
      }
    
      using namespace indicators;
      BlockProgressBar bar{
        option::BarWidth{80},
        option::ForegroundColor{Color::white},
        option::ShowPercentage{true},
        option::FontStyles{
              std::vector<FontStyle>{FontStyle::bold}},
        option::MaxProgress{numbers.size()}
      };
    
      std::cout << "Iterating over a list of numbers (size = "
                << numbers.size() << ")\n";
    
      std::vector<size_t> result;
      for (size_t i = 0; i < numbers.size(); ++i) {
    
        // Perform some computation
        result.push_back(numbers[i] * numbers[i]);
    
        // Show iteration as postfix text
        bar.set_option(option::PostfixText{
          std::to_string(i) + "/" + std::to_string(numbers.size())
        });
    
        // update progress bar
        bar.tick();
      }
    
      bar.mark_as_completed();
    
      // Show cursor
      indicators::show_console_cursor(true);
    
      return 0;
    }
  2. Build the project with samples and demos

    master

    To build the project including the provided samples and demonstrations, use CMake with the INDICATORS_SAMPLES and INDICATORS_DEMO flags enabled.

    git clone https://github.com/p-ranav/indicators
    cd indicators
    mkdir build && cd build
    cmake -DINDICATORS_SAMPLES=ON -DINDICATORS_DEMO=ON ..
    make
  3. Use Unicode and Emojis in progress bars

    master

    The indicators library supports multi-byte Unicode characters (including Japanese, Russian, Greek, Chinese, and Emojis) for Fill, Lead, and other text options. If option::BarWidth is set, the library respects the display width; if a character would exceed the width, it fills the remainder with space characters.

    // Example of using Emojis in a ProgressBar
    indicators::ProgressBar bar{
        indicators::option::BarWidth{50},
        indicators::option::Start{"["},
        indicators::option::Fill{"🔥"},
        indicators::option::Lead{"🔥"},
        indicators::option::Remainder{" "},
        indicators::option::End{" ]"},
        indicators::option::PostfixText{"Emojis"},
        indicators::option::ForegroundColor{indicators::Color::white},
        indicators::option::FontStyles{
            std::vector<indicators::FontStyle>{indicators::FontStyle::bold}}
    };
  4. Build using WinLibs + MinGW on Windows

    master

    When using WinLibs on Windows, specify the MinGW generator and the path to your g++.exe compiler during the CMake configuration step.

    mkdir build && cd build
    cmake -G "MinGW Makefiles" -DCMAKE_CXX_COMPILER="C:/WinLibs/mingw64/bin/g++.exe" -DINDICATORS_SAMPLES=ON -DINDICATORS_DEMO=ON ..
    make -j4
  5. Implement decremental (countdown) progress bars

    master

    You can create a countdown progress bar by setting the option::ProgressType to ProgressType::decremental. This is useful for tasks that represent a countdown or a reversion process.

    #include <chrono>
    #include <indicators/progress_bar.hpp>
    #include <thread>
    using namespace indicators;
    
    int main() {
    
      ProgressBar bar{option::BarWidth{50},
                      option::ProgressType{ProgressType::decremental},
                      option::Start{"["},
                      option::Fill{"■"},
                      option::Lead{"■"},
                      option::Remainder{"-"},
                      option::End{"]"},
                      option::PostfixText{"Reverting System Restore"},
                      option::ForegroundColor{Color::yellow},
                      option::FontStyles{std::vector<FontStyle>{FontStyle::bold}}};
    
      // Update bar state
      while (true) {
        bar.tick();
        if (bar.is_completed())
          break;
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
      }
    
      return 0;
    }
  6. Install the indicators library

    master
    The indicators library is a header-only C++ library. You can integrate it into your project by grabbing the include/indicators directory for the standard version, or the single_include/indicators directory for a single-header version.
  7. Configure amalgamate.py via JSON

    master

    The -c, --config option requires a JSON configuration file. This file must list the source files, include paths, and the destination path for the resulting amalgamation.

    For implementation examples, refer to test/source.c.json and test/include.h.json within the repository.

  8. Known limitations of amalgamate.py

    master

    Users should be aware of the following technical limitations:

    • Complex Includes: It cannot handle macro-based include directives, such as:
      #define HEADER_PATH "path/to/header.h"
      #include HEADER_PATH
    • File Termination: It assumes every non-empty source and header file ends with a newline character that is not preceded by a backslash (per ISO C99 5.1.1.2p1.2).
    • C++ Raw String Literals: While it can be used with C++, C++11 raw string literals will cause parsing errors if they contain quotation marks, as the parser will stop at the first quote encountered.
  9. Show Time Elapsed and Remaining time

    master

    To display how much time has passed and how much is left, enable option::ShowElapsedTime{true} and option::ShowRemainingTime{true} in your ProgressBar configuration. The format used is [{elapsed}<{remaining}].

    indicators::ProgressBar bar{
      // ... other options
      option::ShowElapsedTime{true},
      option::ShowRemainingTime{true}
    };
  10. Use a BlockProgressBar for smooth visuals

    master

    For a smoother visual experience using Unicode block elements, use indicators::BlockProgressBar. This is useful for high-fidelity CLI progress bars.

    #include <indicators/block_progress_bar.hpp>
    
    using namespace indicators;
    BlockProgressBar bar{
      option::BarWidth{80},
      option::Start{"["},
      option::End{"]"},
      option::ForegroundColor{Color::white},
      option::ShowPercentage{true},
      option::FontStyles{std::vector<FontStyle>{FontStyle::bold}}
    };
    
    // Update with float or size_t
    bar.set_progress(0.5f);