Consolix Framework Documentation

Version: 0.0.0-untagged

   █████████                                       ████   ███             
  ███░░░░░███                                     ░░███  ░░░              
 ███     ░░░   ██████  ████████    █████   ██████  ░███  ████  █████ █████
░███          ███░░███░░███░░███  ███░░   ███░░███ ░███ ░░███ ░░███ ░░███ 
░███         ░███ ░███ ░███ ░███ ░░█████ ░███ ░███ ░███  ░███  ░░░█████░  
░░███     ███░███ ░███ ░███ ░███  ░░░░███░███ ░███ ░███  ░███   ███░░░███ 
 ░░█████████ ░░██████  ████ █████ ██████ ░░██████  █████ █████ █████ █████
  ░░░░░░░░░   ░░░░░░  ░░░░ ░░░░░ ░░░░░░   ░░░░░░  ░░░░░ ░░░░░ ░░░░░ ░░░░░ 

Welcome to the Consolix Framework, a header-only C++ library for structured console applications built around reusable components, a service locator, and a focused set of utility modules.

Overview

Consolix is designed for console applications that need more structure than a single source file, but do not want the weight of a large framework.

It helps organize application startup, shared services, logging, CLI parsing, configuration loading, and common utility tasks so console applications remain easier to grow and maintain. It also targets the recurring runtime concerns of console tools: startup and shutdown flow, termination-signal-driven stop requests, logo and title output, and keeping the main loop readable instead of scattering that logic across main.cpp.

Capabilities

• Component-based application structure built around reusable components and a shared service locator
• Lifecycle and loop management for startup, execution, and controlled shutdown flows
• Console-oriented presentation helpers for titles, ASCII logos, colors, and logging
• CLI and configuration components for command-line parsing and JSON-backed settings
• Utility helpers for paths, encodings, system tasks, and other recurring console-app support code
• Lightweight delivery model with header-only consumption, C++11/14/17 support, and opt-in integrations only when needed

Key Modules

• Core:
  • ServiceLocator for global resource management
  • AppComponentManager and ConsoleApplication for application lifecycle
  • service and application helpers for common setup flows
• Components:
  • TitleComponent: manages the console window title
  • LoggerComponent: centralized logging for console and file output
  • CliComponent: command-line argument handling
  • ConfigComponent: JSON-based configuration with comment support
  • LogoComponent: displays a custom ASCII logo in the console
  • LoopComponent: customizable application loops
• Utilities:
  • path_utils.hpp: path and executable-location helpers
  • json_utils.hpp: helpers for parsing and cleaning JSON strings
  • additional helpers for colors, encoding, system info, and common types

Quick Start

For most projects, the shortest path is:

1. Add Consolix headers to your project.
2. Enable only the optional integrations you need.
3. Include an aggregate entry header such as #include <consolix/consolix.hpp>.
4. If you use CMake, link against Consolix::Consolix.

Dependencies

Consolix vendors several external libraries in libs/.

• LogIt is used by the optional logging integration and powers LoggerComponent when CONSOLIX_USE_LOGIT=1
• time-shield-cpp is a vendored dependency used by the LogIt integration; it is not intended as a primary Consolix-facing API layer
• cxxopts is used by CliComponent when CONSOLIX_USE_CXXOPTS=1
• nlohmann/json is used by ConfigComponent when CONSOLIX_USE_JSON=1

Example Usage

#include <consolix/components.hpp>
 
int main(int argc, char* argv[]) {
    // Add logging functionality
    consolix::add<consolix::LoggerComponent>();
 
    // Display the application logo
    consolix::add<consolix::LogoComponent>(consolix::TextColor::DarkYellow);
 
    // Handle command-line arguments
    consolix::add<consolix::CliComponent>("MyApp", "Program description", [](auto& options) {
        options.add_options()("debug", "Enable debug mode");
    }, argc, argv);
 
    // Load configuration from a JSON file
    consolix::add<consolix::ConfigComponent<MyConfig>>("config.json");
 
    // Execute the main loop
    consolix::run([]() {
        CONSOLIX_STREAM() << "Executing main loop...";
    });
}

Documentation Structure

Main Sections

1. General Guidance
   • Installation and Configuration
   • Usage Examples
2. Modules and Components
   • Core Modules
   • Components
3. Utilities
   • Path Utilities
   • JSON Utilities
   • Console Text Colors
   • Common Types and Enumerations
4. Project Overview
   • Project Structure

Structure

• Core — foundational classes and utilities
• Components — modules implementing key application features
• Utilities — helper functions and reusable support modules
• Interfaces — interface classes defining component contracts

License

Consolix is distributed under the MIT License. For details, see the LICENSE file.