Command-Line Interface Framework for Free Pascal 🚀

A robust toolkit for building command-line (terminal) applications in Free Pascal. Leverage Pascal's strong typing and compile-time checks while creating sophisticated terminal tools with features like git-style commands, progress bars, and coloured output for better readability.

Combines Free Pascal's speed and reliability with professional-grade features. The object-oriented design handles the complex parts, letting you focus on your application's logic.

📑 Table of Contents

• Command-Line Interface Framework for Free Pascal 🚀
  • 📑 Table of Contents
  • ✨ Features
  • 🚀 Quick Start
  • 🎯 Parameter Types and Validation
    • Basic Types
    • Boolean and Flags
    • Complex Types
    • Validation Rules
  • 📖 Screenshots
  • 📖 System Requirements
    • Tested Environments
    • Theoretical Compatibility
    • Dependencies
    • Build Requirements
  • 📖 Documentation
  • 🎯 Use Cases
  • 🤝 Contributing
  • 📝 License
  • 🙏 Acknowledgments
  • 📞 Contact

✨ Features

• 🎯 Command & Subcommand Support: Organize complex CLIs with hierarchical commands
• 🔍 Smart Parameter Handling: Automatic validation and type checking
• 📊 Progress Indicators: Built-in spinners and progress bars
• 🎨 Colored Output: Rich console output with basic color support
• 📚 Comprehensive Help System: Auto-generated help with examples
• 🛡️ Type-Safe: Interface-based design with strong typing
• 🔌 Extensible: Easy to extend with custom commands and parameters
• Modern Command-Line Interface
  • Subcommand support (e.g., app repo init, app repo clone)
  • Short and long flags (-h, --help)
  • Automatic help generation
  • Colored output support
• Robust Error Handling
  • Clear error messages for unknown commands and subcommands
  • Validation of command-line flags and parameters
  • Helpful suggestions when errors occur
  • Context-aware help display
• Developer-Friendly
  • Interface-based design
  • Easy command registration
  • Extensible parameter system
  • Built-in progress indicators
• User-Friendly
  • Consistent help formatting
  • Command suggestions
  • Default values support
  • Required parameter validation

🚀 Quick Start

1. Installation

No complex build system needed! Just:

# Clone the repository
git clone https://github.com/yourusername/cli-fp.git

# Or copy the source files to your project's directory

2. Use in Your Project

• Add the source directory to your project's search path (Project -> Project Options ... -> Compiler Options -> Paths -> Other unit files)
• Add the units to your uses clause:

uses
  CLI.Interfaces,    // Core interfaces
  CLI.Application,   // Main application framework
  CLI.Command,       // Base command implementation
  CLI.Parameter,     // Parameter handling
  CLI.Progress,      // Optional: Progress indicators
  CLI.Console;       // Optional: Colored console output

3. Create Your First CLI App

program MyApp;

{$mode objfpc}{$H+}{$J-}

uses
  SysUtils,
  CLI.Interfaces,
  CLI.Application,
  CLI.Command;

type
  // Define a new command
  TGreetCommand = class(TBaseCommand)
  public
    function Execute: integer; override;
  end;

  function TGreetCommand.Execute: integer;
  var
    Name: string;
  begin
    // Get parameter value using helper method
    if GetParameterValue('--name', Name) then
      WriteLn('Hello, ', Name, '!')
    else
      WriteLn('Hello, World!');
    Result := 0;
  end;

{ Main program }
var
  App: ICLIApplication;
  Cmd: TGreetCommand;

begin
  App := CreateCLIApplication('MyApp', '1.0.0');
  
  // Create and configure command
  Cmd := TGreetCommand.Create('greet', 'Say hello');
  Cmd.AddStringParameter('-n', '--name', 'Name to greet', False, 'World');
  
  // Register command
  App.RegisterCommand(Cmd);
  
  // Execute application
  ExitCode := App.Execute;
end.

Output:

$ ./myapp greet --name "John"
Hello, John!

$ ./myapp greet
Hello, World!

$ ./myapp greet --help
Usage: myapp greet [options]

Say hello

Options:
  -n, --name           Name to greet
      Default: World
  -h, --help          Show this help message

🎯 Parameter Types and Validation

The framework provides comprehensive type-safe parameter handling with built-in validation:

Basic Types

// String parameter
Cmd.AddStringParameter('-n', '--name', 'Name to greet');

// Integer parameter (required)
Cmd.AddIntegerParameter('-c', '--count', 'Number of items', True);

// Float parameter with default
Cmd.AddFloatParameter('-r', '--rate', 'Processing rate', False, '1.0');

Boolean and Flags

// Flag (true when present)
Cmd.AddFlag('-v', '--verbose', 'Enable verbose output');

// Boolean parameter (true/false)
Cmd.AddBooleanParameter('-d', '--debug', 'Enable debug mode', False, 'false');

Complex Types

// DateTime (YYYY-MM-DD HH:MM)
Cmd.AddDateTimeParameter('-d', '--date', 'Start date');

// Enum with allowed values
Cmd.AddEnumParameter('-l', '--level', 'Log level', 'debug|info|warn|error');

// URL with protocol validation
Cmd.AddUrlParameter('-u', '--url', 'Repository URL');

// Array (comma-separated)
Cmd.AddArrayParameter('-t', '--tags', 'Tag list');

// Password (masked in output)
Cmd.AddPasswordParameter('-k', '--api-key', 'API Key');

Validation Rules

Each parameter type has built-in validation:

• String: No validation
• Integer: Must be a valid integer number
• Float: Must be a valid floating-point number
• Boolean: Must be 'true' or 'false' (case-insensitive)
• DateTime: Must be in format "YYYY-MM-DD HH:MM" (24-hour)
• Enum: Must match one of the pipe-separated allowed values
• URL: Must start with http://, https://, git://, or ssh://
• Array: No validation on individual items
• Password: No validation, but value is masked in output

📖 Screenshots

Above: The ColorDemo example showing professional CLI styling with colors, Unicode characters, and progress indicators.

📖 System Requirements

Tested Environments

• Operating System: Windows 11
• Compiler: Free Pascal (FPC) 3.2.2
• IDE: Lazarus 3.6

Theoretical Compatibility

• Operating Systems:
  • Windows (7, 8, 10, 11)
  • Linux (Any distribution with FPC support)
  • macOS (with FPC support)
  • FreeBSD
• Compiler: Free Pascal 3.2.2 or higher
• IDE: Any IDE that supports Free Pascal
  • Lazarus 3.6 or higher
  • VS Code with OmniPascal
  • Other text editors

Dependencies

• No external dependencies required
• Uses only standard Free Pascal RTL units

Build Requirements

• Free Pascal Compiler (FPC) 3.2.2+
• Lazarus 3.6+
• Basic development tools (git, terminal, etc)

📖 Documentation

• User Manual: Complete guide for using the framework, including a cheat sheet
• API Reference: Detailed API reference for the framework
• Technical Documentation: Architecture and implementation details
• Examples: Working example applications

🎯 Use Cases

Perfect for building:

• Version Control Systems
• Build Tools
• Package Managers
• Development Tools
• System Utilities
• DevOps Tools

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by modern CLI frameworks
• Built with Free Pascal and Lazarus IDE

📞 Contact

Your Name - ikelaiah

Project Link: https://github.com/ikelaiah/cli-fp