User Guide - simple

Getting Started

Installation

Set the environment variable:
```
export SIMPLE_EIFFEL=/d/prod
```

Add to your ECF file:

<library name="simple_cli" location="$SIMPLE_EIFFEL/simple_cli/simple_cli.ecf"/>

Basic Usage

local
    cli: SIMPLE_CLI
do
    create cli.make
    cli.set_app_info ("myapp", "My Application", "1.0.0")

    -- Define flags and options
    cli.add_flag ("v|verbose", "Enable verbose output")
    cli.add_option ("o|output", "Output file", "FILE")

    -- Parse command line
    cli.parse

    -- Handle results
    if cli.help_requested then
        cli.print_help
    elseif cli.has_errors then
        cli.print_errors
    else
        run_application (cli)
    end
end

Defining Flags

Flags are boolean switches that are either present or absent.

Short and Long Names

-- Short and long names (separated by |)
cli.add_flag ("v|verbose", "Enable verbose output")
-- Can be used as: -v or --verbose

-- Long name only
cli.add_flag ("debug", "Enable debug mode")
-- Can be used as: --debug

Checking Flags

if cli.has_flag ("verbose") then
    print ("Verbose mode enabled%N")
end

-- You can use either the short or long name
if cli.has_flag ("v") then
    -- This also works
end

Built-in Flags

simple_cli provides two built-in flags:

-h, --help - Show help text
-V, --version - Show version

-- Check for help/version requests
if cli.help_requested then
    cli.print_help
elseif cli.version_requested then
    cli.print_version
end

-- Disable built-in flags if needed
cli.disable_help_flag
cli.disable_version_flag

Defining Options

Options take a value, like --output=file.txt.

Basic Options

-- Option with short and long names
cli.add_option ("o|output", "Output file path", "FILE")

-- Long name only
cli.add_option ("config", "Configuration file", "PATH")

-- The third argument is the placeholder shown in help text

Options with Defaults

-- Option with default value
cli.add_option_with_default ("f|format", "Output format", "FMT", "json")

-- If --format is not specified, returns "json"

Required Options

-- Required option (error if missing)
cli.add_required_option ("i|input", "Input file", "FILE")

-- Parsing will fail with an error if not provided

Getting Option Values

-- Get string value (may be Void)
if attached cli.option_value ("output") as out_file then
    print ("Output: " + out_file)
end

-- Get with inline default
output_path := cli.option_value_or_default ("output", "output.txt")

-- Check if option was provided
if cli.has_option ("output") then
    -- Option was set (or has default)
end

Typed Option Values

Integer Options

cli.add_option ("n|count", "Number of items", "NUM")

-- Get as integer
count := cli.integer_option ("count")

-- Get with default
count := cli.integer_option_or_default ("count", 10)

Boolean Options

cli.add_option ("dry-run", "Dry run mode", "BOOL")

-- Get as boolean
-- Recognizes: "true", "false", "yes", "no", "1", "0"
if cli.boolean_option ("dry-run") then
    print ("Dry run enabled%N")
end

Command-Line Formats

simple_cli supports standard Unix-style argument formats:

Flags

# Long form
myapp --verbose

# Short form
myapp -v

# Combined short flags
myapp -vd    # Same as -v -d

Options

# Long with equals
myapp --output=file.txt

# Long with space
myapp --output file.txt

# Short with space
myapp -o file.txt

# Short attached (no space)
myapp -ofile.txt

Mixed Usage

# Combining flags, options, and arguments
myapp -v --output=result.txt build src/

# Multiple short flags combined
myapp -vdf --output=result.txt

Positional Arguments

Arguments that aren't flags or options are positional arguments:

-- Command line: myapp build src/ tests/

-- Get the command (first positional argument)
if attached cli.command as cmd then
    print ("Command: " + cmd)  -- "build"
end

-- Get all positional arguments
across cli.arguments as arg loop
    print ("Arg: " + arg + "%N")
end
-- Prints: "build", "src/", "tests/"

-- Get arguments after the command
across cli.arguments_after_command as arg loop
    print ("Target: " + arg + "%N")
end
-- Prints: "src/", "tests/"

Error Handling

cli.parse

if cli.has_errors then
    -- Print built-in error messages
    cli.print_errors

    -- Or handle manually
    across cli.errors as err loop
        print ("Error: " + err + "%N")
    end
end

Common Errors

Unknown option: --foo - Unrecognized option name
Option --output requires a value - Missing value for option
Required option missing: --input - Required option not provided

Checking Success

-- is_successful is True when:
-- - No errors occurred
-- - Help was not requested
-- - Version was not requested

if cli.is_successful then
    run_application (cli)
end

Help Text Generation

simple_cli automatically generates help text:

cli.set_app_info ("myapp", "My awesome application", "2.1.0")
cli.add_flag ("v|verbose", "Enable verbose output")
cli.add_flag ("d|debug", "Enable debug mode")
cli.add_option ("o|output", "Output file", "FILE")
cli.add_option_with_default ("f|format", "Output format", "FMT", "json")
cli.add_required_option ("i|input", "Input file", "FILE")

-- Running: myapp --help
cli.print_help

Generated Output

myapp v2.1.0
My awesome application

Usage: myapp [OPTIONS] [COMMAND] [ARGS...]

Options:
  -h, --help          Show this help message
  -V, --version       Show version information
  -v, --verbose       Enable verbose output
  -d, --debug         Enable debug mode
  -o, --output=FILE   Output file
  -f, --format=FMT    Output format (default: json)
  -i, --input=FILE    Input file [required]

Complete Example

class MY_CLI_APP

create
    make

feature

    make
        local
            cli: SIMPLE_CLI
        do
            create cli.make
            configure_cli (cli)
            cli.parse
            handle_result (cli)
        end

feature {NONE} -- Implementation

    configure_cli (cli: SIMPLE_CLI)
        do
            cli.set_app_info ("compiler", "Simple compiler tool", "1.0.0")

            -- Flags
            cli.add_flag ("v|verbose", "Enable verbose output")
            cli.add_flag ("q|quiet", "Suppress all output")
            cli.add_flag ("w|warnings", "Show warnings")

            -- Options
            cli.add_required_option ("i|input", "Input source file", "FILE")
            cli.add_option ("o|output", "Output file", "FILE")
            cli.add_option_with_default ("O|optimize", "Optimization level", "LEVEL", "2")
            cli.add_option_with_default ("t|target", "Target platform", "PLATFORM", "native")
        end

    handle_result (cli: SIMPLE_CLI)
        do
            if cli.help_requested then
                cli.print_help
            elseif cli.version_requested then
                cli.print_version
            elseif cli.has_errors then
                cli.print_errors
                print ("%NUse --help for usage information%N")
            else
                compile (cli)
            end
        end

    compile (cli: SIMPLE_CLI)
        local
            input_file, output_file: STRING
            opt_level: INTEGER
        do
            -- Get required input
            if attached cli.option_value ("input") as f then
                input_file := f
            end

            -- Get optional output (default to input.out)
            output_file := cli.option_value_or_default ("output", input_file + ".out")

            -- Get optimization level
            opt_level := cli.integer_option_or_default ("optimize", 2)

            -- Check flags
            if cli.has_flag ("verbose") then
                print ("Compiling " + input_file + " -> " + output_file + "%N")
                print ("Optimization: O" + opt_level.out + "%N")
                print ("Target: " + cli.option_value_or_default ("target", "native") + "%N")
            end

            -- Do actual compilation...
        end

end