Input.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Console - Input
 *
 * @package Italix\Console
 */

declare(strict_types=1);

namespace Italix\Console;

/**
 * Positional arguments and options, parsed by rules that fit in a paragraph.
 *
 *   --name=value   option "name" with that value
 *   --name         option "name" present, value '' — `flag()` reads it as true
 *   --no-name      option "name" present, value '0' — `flag()` reads it as false
 *   -abc           short flags a, b and c, each present with value ''
 *   --             stops option parsing; everything after is an argument
 *   anything else  a positional argument, in order
 *
 * There is no option *schema*: a command declares nothing in advance and asks
 * for what it wants, with the default it wants. That trades a class of typo
 * detection ("unknown option --frce") for not maintaining two descriptions of
 * the same flag, which is the trade the rest of this framework makes as well —
 * routes are listed, not discovered, but their parameters are read by name.
 */
final class Input
{
    /** @var string[] */
    private array $arguments;

    /** @var array<string, string> */
    private array $options;

    /**
     * @param string[]              $arguments
     * @param array<string, string> $options
     */
    public function __construct(array $arguments = [], array $options = [])
    {
        $this->arguments = array_values($arguments);
        $this->options   = $options;
    }

    /**
     * Parse a raw argument list — everything *after* the command name.
     *
     * @param string[] $argv
     */
    public static function parse(array $argv): self
    {
        $arguments   = [];
        $options     = [];
        $literal_flag = false;

        foreach ($argv as $token) {
            $token = (string) $token;

            if ($literal_flag) {
                $arguments[] = $token;
                continue;
            }

            if ($token === '--') {
                $literal_flag = true;
                continue;
            }

            if (strncmp($token, '--', 2) === 0) {
                $body = substr($token, 2);

                if ($body === '') {
                    $arguments[] = $token;
                    continue;
                }

                $pos = strpos($body, '=');

                if ($pos !== false) {
                    $options[substr($body, 0, $pos)] = substr($body, $pos + 1);
                    continue;
                }

                if (strncmp($body, 'no-', 3) === 0) {
                    $options[substr($body, 3)] = '0';
                    continue;
                }

                $options[$body] = '';
                continue;
            }

            if (strncmp($token, '-', 1) === 0 && strlen($token) > 1) {
                foreach (str_split(substr($token, 1)) as $letter) {
                    $options[$letter] = '';
                }
                continue;
            }

            $arguments[] = $token;
        }

        return new self($arguments, $options);
    }

    // -------------------------------------------------------------------------
    // Arguments
    // -------------------------------------------------------------------------

    public function argument(int $index, ?string $default = null): ?string
    {
        return $this->arguments[$index] ?? $default;
    }

    /**
     * @return string[]
     */
    public function arguments(): array
    {
        return $this->arguments;
    }

    public function arguments_n(): int
    {
        return count($this->arguments);
    }

    // -------------------------------------------------------------------------
    // Options
    // -------------------------------------------------------------------------

    public function option(string $name, ?string $default = null): ?string
    {
        $value = $this->options[$name] ?? null;

        // `--max` with no value means "present", not "empty": fall back to the
        // default so that `--max` and an omitted `--max` do not diverge into a
        // zero the caller never asked for.
        if ($value === null || $value === '') {
            return $default;
        }

        return $value;
    }

    public function int_option(string $name, int $default = 0): int
    {
        $value = $this->option($name);

        return $value === null ? $default : (int) $value;
    }

    public function has_option(string $name): bool
    {
        return array_key_exists($name, $this->options);
    }

    /**
     * A boolean switch.
     *
     * Present with no value is true; `--no-name` is false; an explicit value is
     * read the way a person would expect ('0', 'false', 'no', 'off' are false).
     */
    public function flag(string $name): bool
    {
        if (!array_key_exists($name, $this->options)) {
            return false;
        }

        $value = strtolower($this->options[$name]);

        if ($value === '') {
            return true;
        }

        return !in_array($value, ['0', 'false', 'no', 'off'], true);
    }

    /**
     * The first flag of the given names that is set.
     *
     * For the conventional pairs: `any_flag('h', 'help')`.
     */
    public function any_flag(string ...$names): bool
    {
        foreach ($names as $name) {
            if ($this->flag($name)) {
                return true;
            }
        }

        return false;
    }

    /**
     * @return array<string, string>
     */
    public function options(): array
    {
        return $this->options;
    }
}