cli.strata

// cli.strata — a small declarative command-line parser for Strata.
//
// Usage (Strata side):
//   import cli;   // or `import ../cli;` from a subdirectory like samples/
//
//   int app_main(const ref string[] args)
//   {
//       ^CliFlag[] flags = {
//           CliFlag { .longName = "verbose", .shortName = "v" },
//           CliFlag { .longName = "help",    .shortName = "h" }
//       };
//       ^CliOpt[] opts = {
//           CliOpt { .longName = "output", .shortName = "o", .def = "",    .hasDef = false },
//           CliOpt { .longName = "count",  .shortName = "n", .def = "1",   .hasDef = true  }
//       };
//       ^CliSpec spec = CliSpec { .flags = flags, .opts = opts };
//       ^CliResult r = CliParse(spec, args);
//       if (r.err != CliErr.None)
//       {
//           return 2;   // r.errArg holds the argv index of the failure
//       }
//       if (CliFlagSet(r, 0)) { /* --verbose / -v seen */ }
//       if (CliOptSet(r, 0))  { string o = copy(r.optVal[0]); /* ... */ }
//       CliInt n = CliParseInt(r.optVal[1]);
//       // r.pos holds positional args in order (owned copies).
//       return 0;
//   }
//
// Supported forms (v1, no subcommands):
//   --flag            long flag            --verbose
//   --opt value       long option          --output out.txt
//   --opt=value       long option, inline  --output=out.txt
//   -f                short flag           -v
//   -xyz              combined short flags -vh
//   -o value          short option         -o out.txt
//   -ovalue / -o=val  short option, inline -oout.txt / -o=out.txt
//   --                stop parsing flags; the rest (and a lone `-`) are positional.
// A repeated flag stays set; a repeated option keeps the LAST value.
// An unknown flag/option sets err to CliErr.UnknownArg; an option with no
// value sets err to CliErr.MissingValue. A flag with `=value` attached
// (--verbose=x) is an error (flags take no values).
// Negative numbers look like short flags: put `--` first if you take them.
//
// Host contract (see cli_shim.h / cli_shim.c):
// - The host builds the `string[]` the parser borrows: one fat
//   {ptr, len, cap} per argv entry plus one outer fat for the array.
//   Pass it as `const ref string[]` so the parser never frees host memory.
//   By convention the host strips argv[0] (program name) first.
// - The host implements `cli_slice` (declared below) and the Strata
//   runtime hooks (strata_alloc / strata_free / strata_panic).
// - Later, when Strata gains a non-owning `cstring` type, the borrowed
//   `string[]` handoff (and `copy()` calls below) can move to it.

// Slice helper the host provides: `cli_slice(s, start, len)` returns the
// substring s[start .. start+len] as a NEW owned string. Needed because pure
// Strata cannot carve a substring out of an argv entry (for `--opt=value`).
// ABI: `void cli_slice(const char* s, int start, int len, HostArr* out)`
// where HostArr is {data, u32 len, u32 cap}; the host mallocs len+1 bytes.
extern void cli_slice(string s, int start, int len, return string out);

enum CliErr : int
{
    None,
    UnknownArg,
    MissingValue
};

struct CliFlag
{
    string longName;
    string shortName;
};

struct CliOpt
{
    string longName;
    string shortName;
    string def;
    bool hasDef;
};

struct CliSpec
{
    ^CliFlag[] flags;
    ^CliOpt[] opts;
};

struct CliResult
{
    bool[] flagSet;
    bool[] optSet;
    string[] optVal;
    string[] pos;
    CliErr err;
    int errArg;
};

struct CliInt
{
    int v;
    bool ok;
};

bool CliIsLong(const ref string s)
{
    if (s.length < 2) { return false; }
    if ((int)s[0] != 45) { return false; }
    if ((int)s[1] != 45) { return false; }
    return true;
}

bool CliIsShort(const ref string s)
{
    if (s.length < 2) { return false; }
    if ((int)s[0] != 45) { return false; }
    return true;
}

int CliFindChar(const ref string s, int ch)
{
    for (uint i = 0; i < s.length; i = i + 1)
    {
        if ((int)s[i] == ch) { return (int)i; }
    }
    return -1;
}

// True when `arg` is "--" + `name` exactly (`nameLen` counts the chars
// after "--", stopping before any '='). Empty names never match.
bool CliMatchLongName(const ref string arg, const ref string name, int nameLen)
{
    if (name.length == 0) { return false; }
    if ((int)name.length != nameLen) { return false; }
    for (uint i = 0; i < name.length; i = i + 1)
    {
        if (arg[i + 2] != name[i]) { return false; }
    }
    return true;
}

int CliFindFlagShort(const ref ^CliSpec spec, int c)
{
    for (uint f = 0; f < spec.flags.length; f = f + 1)
    {
        if (spec.flags[f].shortName.length == 1 && (int)spec.flags[f].shortName[0] == c)
        {
            return (int)f;
        }
    }
    return -1;
}

int CliFindOptShort(const ref ^CliSpec spec, int c)
{
    for (uint o = 0; o < spec.opts.length; o = o + 1)
    {
        if (spec.opts[o].shortName.length == 1 && (int)spec.opts[o].shortName[0] == c)
        {
            return (int)o;
        }
    }
    return -1;
}

// Parses one `--name` / `--name=value` token. Returns extra args consumed
// beyond the token itself (0, or 1 when the value is the next arg),
// or -1 on error (r.err / r.errArg are set).
int CliParseLong(const ref ^CliSpec spec, ref ^CliResult r, const ref string[] args, int idx)
{
    int epos = CliFindChar(args[(uint)idx], 61);
    int nameLen;
    bool hasVal;
    if (epos < 0)
    {
        nameLen = (int)args[(uint)idx].length - 2;
        hasVal = false;
    }
    else
    {
        nameLen = epos - 2;
        hasVal = true;
    }

    for (uint o = 0; o < spec.opts.length; o = o + 1)
    {
        if (CliMatchLongName(args[(uint)idx], spec.opts[o].longName, nameLen))
        {
            if (hasVal)
            {
                int st = epos + 1;
                int ln = (int)args[(uint)idx].length - st;
                string v = cli_slice(args[(uint)idx], st, ln);
                r.optVal[o] = v;
                r.optSet[o] = true;
                return 0;
            }
            if (idx + 1 >= (int)args.length)
            {
                r.err = CliErr.MissingValue;
                r.errArg = idx;
                return -1;
            }
            r.optVal[o] = copy(args[(uint)(idx + 1)]);
            r.optSet[o] = true;
            return 1;
        }
    }

    for (uint f = 0; f < spec.flags.length; f = f + 1)
    {
        if (CliMatchLongName(args[(uint)idx], spec.flags[f].longName, nameLen))
        {
            if (hasVal)
            {
                r.err = CliErr.UnknownArg;
                r.errArg = idx;
                return -1;
            }
            r.flagSet[f] = true;
            return 0;
        }
    }

    r.err = CliErr.UnknownArg;
    r.errArg = idx;
    return -1;
}

// Parses one `-x` / `-xyz` / `-o value` / `-ovalue` / `-o=value` token.
// Same return contract as CliParseLong.
int CliParseShort(const ref ^CliSpec spec, ref ^CliResult r, const ref string[] args, int idx)
{
    uint n = args[(uint)idx].length;
    uint p = 1;
    while (p < n)
    {
        int c = (int)args[(uint)idx][p];
        int fi = CliFindFlagShort(spec, c);
        int oi = CliFindOptShort(spec, c);
        if (fi >= 0)
        {
            r.flagSet[(uint)fi] = true;
            p = p + 1;
        }
        else if (oi >= 0)
        {
            uint o = (uint)oi;
            if (p + 1 < n)
            {
                int st = (int)(p + 1);
                if ((int)args[(uint)idx][p + 1] == 61)
                {
                    st = st + 1;
                }
                int ln = (int)n - st;
                string v = cli_slice(args[(uint)idx], st, ln);
                r.optVal[o] = v;
                r.optSet[o] = true;
            }
            else
            {
                if (idx + 1 >= (int)args.length)
                {
                    r.err = CliErr.MissingValue;
                    r.errArg = idx;
                    return -1;
                }
                r.optVal[o] = copy(args[(uint)(idx + 1)]);
                r.optSet[o] = true;
                return 1;
            }
            return 0;
        }
        else
        {
            r.err = CliErr.UnknownArg;
            r.errArg = idx;
            return -1;
        }
    }
    return 0;
}

// Parses `args` (program name already stripped by the host) per `spec`.
// The spec and args are borrowed; the result owns its strings.
^CliResult CliParse(const ref ^CliSpec spec, const ref string[] args)
{
    ^CliResult r = CliResult { .err = CliErr.None, .errArg = -1 };
    for (uint i = 0; i < spec.flags.length; i = i + 1)
    {
        array_push(r.flagSet, false);
    }
    for (uint i = 0; i < spec.opts.length; i = i + 1)
    {
        array_push(r.optSet, false);
        if (spec.opts[i].hasDef)
        {
            array_push(r.optVal, copy(spec.opts[i].def));
        }
        else
        {
            array_push(r.optVal, "");
        }
    }

    uint i = 0;
    bool onlyPos = false;
    while (i < args.length)
    {
        if (onlyPos)
        {
            array_push(r.pos, copy(args[i]));
        }
        else if (args[i] == "--")
        {
            onlyPos = true;
        }
        else if (CliIsLong(args[i]))
        {
            int skip = CliParseLong(spec, r, args, (int)i);
            if (skip < 0)
            {
                return r;
            }
            i = i + (uint)skip;
        }
        else if (CliIsShort(args[i]))
        {
            int skip = CliParseShort(spec, r, args, (int)i);
            if (skip < 0)
            {
                return r;
            }
            i = i + (uint)skip;
        }
        else
        {
            array_push(r.pos, copy(args[i]));
        }
        i = i + 1;
    }
    return r;
}

// Parses an optional sign followed by decimal digits (no whitespace).
// Overflow fails closed: out-of-int32-range values report ok = false.
CliInt CliParseInt(const ref string s)
{
    CliInt r = { .v = 0, .ok = false };
    if (s.length == 0) { return r; }
    uint i = 0;
    bool neg = false;
    if ((int)s[0] == 45) { neg = true; i = 1; }
    else if ((int)s[0] == 43) { i = 1; }
    if (i >= s.length) { return r; }
    int v = 0;
    while (i < s.length)
    {
        int c = (int)s[i];
        if (c < 48 || c > 57)
        {
            r.v = 0;
            r.ok = false;
            return r;
        }
        int d = c - 48;
        if (!neg)
        {
            if (v > 214748364) { return r; }
            if (v == 214748364 && d > 7) { return r; }
            v = v * 10 + d;
        }
        else
        {
            if (v < -214748364) { return r; }
            if (v == -214748364 && d > 8) { return r; }
            v = v * 10 - d;
        }
        i = i + 1;
    }
    r.v = v;
    r.ok = true;
    return r;
}

// Bounds-checked result readers (OOB reads report false / "").
bool CliFlagSet(const ref ^CliResult r, int i)
{
    if (i < 0 || i >= (int)r.flagSet.length) { return false; }
    return r.flagSet[(uint)i];
}

bool CliOptSet(const ref ^CliResult r, int i)
{
    if (i < 0 || i >= (int)r.optSet.length) { return false; }
    return r.optSet[(uint)i];
}

string CliOptCopy(const ref ^CliResult r, int i)
{
    if (i < 0 || i >= (int)r.optVal.length) { return ""; }
    return copy(r.optVal[(uint)i]);
}