argot-cli 0.0.0-stage → 0.4.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## v0.3.0 -- 2026-04-23
+- Added new error types for clearer distinction between runtime and
+configuration errors.
+- Deprecated `LabeledEntry`; option names should now be defined as object keys
+in configuration.
+
+## v0.2.0 -- 2026-02-08
+- Added filesystem support for Node.js and Bun runtimes.
+
+## v0.1.0 -- 2026-02-04
+- Implemented `argot-cli`, a command-line interface argument parser in
+TypeScript. As of its first publication, it is only compatible with Deno.

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Lucas L. S. Haine
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# argot-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is a command-line argument parser with a simple configuration format.

package/dist/arg_parser.d.ts

@@ -0,0 +1,60 @@
+import type { ParseResult } from './types.ts';
+import { ParserConfig } from './parser_config.ts';
+/**
+ * Command-line argument parser.
+ * The parser processes an array of strings according to a
+ * configuration and produces a structured result.
+ * Parsing follows UNIX-style short options and GNU-style long
+ * options.
+ */
+export declare class ArgParser {
+    private longOptExp;
+    private shortOptExp;
+    private assignmentExp;
+    private parameterExp;
+    private configs;
+    constructor(configs: ParserConfig);
+    /**
+     * Parse an array of command-line arguments.
+     * Arguments are processed from left to right. Each argument is
+     * classified as one of:
+     * - option: matches a configured short or long option
+     * - parameter: of the form "key=value"
+     * - operand: any other argument
+     * Parsing rules:
+     * - The literal "--" stops option parsing. All subsequent
+     *   arguments are treated as operands.
+     * - Short options may be combined (e.g. "-abc").
+     * - If a short option that accepts an associated value is not the
+     *   last character in a group, the remainder of the argument is
+     *   used as its value (e.g. "-n10").
+     * - If a short option that accepts an associated value appears as
+     *   the last character:
+     *   - If the option has a default value, no additional argument
+     *     is consumed.
+     *   - Otherwise, the next argument is used as its value.
+     * - Long options must be provided in the form "--name" if they do
+     *   not accept an associated value, or "--name=value" if they do.
+     * - Long options that accept an associated value never consume
+     *   the next argument.
+     * - Parameters are parsed from arguments matching "key=value" and
+     *   are stored separately from options.
+     * - If an option is repeated:
+     *   - count and list options accumulate values
+     *   - other options overwrite previous values
+     * - Alias options store their values under the target option's
+     *   name.
+     * Returns:
+     * - options: parsed option values
+     * - parameters: key/value assignments
+     * - operands: positional arguments
+     * Throws:
+     * - UnknownOptionError if an unrecognized option is encountered
+     * - NullArgError or NullIntError if a required value is missing
+     * - InvalidIntError or UnsafeIntegerError for invalid numeric values
+     */
+    parse(argList: string[]): Readonly<ParseResult>;
+    slice(argList: string[], index: number): [string[], string[]];
+    private parseLongOption;
+    private parseShortOption;
+}

package/dist/arg_parser.js

@@ -0,0 +1,557 @@
+import { ParserConfig } from './parser_config.js';
+import { Options, Parameters, Operands } from './types.js';
+import { NullArgError, NullFloatError, NullIntError, UnknownOptionError, } from './errors.js';
+import { parseFloatStrict, parseIntStrict } from './utils.js';
+/**
+ * Command-line argument parser.
+ * The parser processes an array of strings according to a
+ * configuration and produces a structured result.
+ * Parsing follows UNIX-style short options and GNU-style long
+ * options.
+ */
+export class ArgParser {
+    longOptExp = /^--/;
+    shortOptExp = /^-[^-]/;
+    assignmentExp = /^--([^=]+)=(.+)?/d;
+    parameterExp = /^([^=]+)=(.+)?/d;
+    configs;
+    constructor(configs) {
+        if (!(configs instanceof ParserConfig)) {
+            throw new TypeError('input value must be an instance of ParserConfig');
+        }
+        this.configs = configs;
+    }
+    /**
+     * Parse an array of command-line arguments.
+     * Arguments are processed from left to right. Each argument is
+     * classified as one of:
+     * - option: matches a configured short or long option
+     * - parameter: of the form "key=value"
+     * - operand: any other argument
+     * Parsing rules:
+     * - The literal "--" stops option parsing. All subsequent
+     *   arguments are treated as operands.
+     * - Short options may be combined (e.g. "-abc").
+     * - If a short option that accepts an associated value is not the
+     *   last character in a group, the remainder of the argument is
+     *   used as its value (e.g. "-n10").
+     * - If a short option that accepts an associated value appears as
+     *   the last character:
+     *   - If the option has a default value, no additional argument
+     *     is consumed.
+     *   - Otherwise, the next argument is used as its value.
+     * - Long options must be provided in the form "--name" if they do
+     *   not accept an associated value, or "--name=value" if they do.
+     * - Long options that accept an associated value never consume
+     *   the next argument.
+     * - Parameters are parsed from arguments matching "key=value" and
+     *   are stored separately from options.
+     * - If an option is repeated:
+     *   - count and list options accumulate values
+     *   - other options overwrite previous values
+     * - Alias options store their values under the target option's
+     *   name.
+     * Returns:
+     * - options: parsed option values
+     * - parameters: key/value assignments
+     * - operands: positional arguments
+     * Throws:
+     * - UnknownOptionError if an unrecognized option is encountered
+     * - NullArgError or NullIntError if a required value is missing
+     * - InvalidIntError or UnsafeIntegerError for invalid numeric values
+     */
+    parse(argList) {
+        // options: parsed option values
+        const options = new Options();
+        // parameters: name=value variable assignments
+        const parameters = new Parameters();
+        // operands: command-line positional arguments
+        const operands = new Operands();
+        if (!Array.isArray(argList)) {
+            throw new TypeError(`argList must be an array of strings`);
+        }
+        for (let i = 0, n = argList.length; i < n; i++) {
+            if (typeof argList[i] !== 'string') {
+                throw new TypeError(`argList must be an array of strings`);
+            }
+        }
+        let stopParsing = false;
+        for (let i = 0, n = argList.length; i < n; i++) {
+            const arg = argList[i];
+            if (stopParsing) {
+                operands.push(arg);
+                continue;
+            }
+            if (arg === '--') {
+                stopParsing = true;
+                continue;
+            }
+            try {
+                if (this.longOptExp.test(arg)) {
+                    const { name, value, shouldSkip } = this.parseLongOption(arg, argList[i + 1] ?? null);
+                    if (this.configs.get(name)?.type === 'count') {
+                        const oldValue = options.get(name) ?? 0;
+                        const newValue = value;
+                        options.set(name, oldValue + newValue);
+                    }
+                    else if (this.configs.get(name)?.type === 'list') {
+                        const oldValue = options.get(name) ?? [];
+                        const newValue = value;
+                        options.set(name, oldValue.concat(newValue));
+                    }
+                    else {
+                        options.set(name, value);
+                    }
+                    if (shouldSkip)
+                        i += 1;
+                }
+                else if (this.shortOptExp.test(arg)) {
+                    const [shouldSkip, pairs,] = this.parseShortOption(arg, argList[i + 1] ?? null);
+                    for (const [name, value] of Object.entries(pairs)) {
+                        if (this.configs.get(name)?.type === 'count') {
+                            const oldValue = options.get(name) ?? 0;
+                            const newValue = value;
+                            options.set(name, oldValue + newValue);
+                        }
+                        else if (this.configs.get(name)?.type === 'list') {
+                            const oldValue = options.get(name) ?? [];
+                            const newValue = value;
+                            options.set(name, oldValue.concat(newValue));
+                        }
+                        else {
+                            options.set(name, value);
+                        }
+                    }
+                    if (shouldSkip)
+                        i += 1;
+                }
+                else if (this.configs.parseParameters && this.parameterExp.test(arg)) {
+                    const [, name, value] = this.parameterExp.exec(arg);
+                    parameters.set(name, value ?? '');
+                }
+                else {
+                    operands.push(arg);
+                }
+            }
+            catch (err) {
+                if (!(err instanceof UnknownOptionError) || !this.configs.allowUnknown)
+                    throw err;
+            }
+        }
+        options.freeze();
+        parameters.freeze();
+        Object.freeze(operands);
+        if (this.configs.parseParameters) {
+            const result = { options, parameters, operands };
+            return Object.freeze(result);
+        }
+        else {
+            const result = { options, operands };
+            return Object.freeze(result);
+        }
+    }
+    slice(argList, index) {
+        let i;
+        let operands = 0;
+        let stopParsing = false;
+        for (i = 0; i < argList.length; i++) {
+            if (operands >= index)
+                break;
+            const arg = argList[i];
+            if (arg === '--' && !stopParsing) {
+                stopParsing = true;
+                continue;
+            }
+            if (stopParsing) {
+                operands += 1;
+                continue;
+            }
+            try {
+                if (this.longOptExp.test(arg)) {
+                    const { shouldSkip } = this.parseLongOption(arg, argList[i + 1] ?? null);
+                    if (shouldSkip)
+                        i += 1;
+                }
+                else if (this.shortOptExp.test(arg)) {
+                    const [shouldSkip,] = this.parseShortOption(arg, argList[i + 1] ?? null);
+                    if (shouldSkip)
+                        i += 1;
+                }
+                else if (this.configs.parseParameters && this.parameterExp.test(arg)) {
+                    continue;
+                }
+                else {
+                    operands += 1;
+                }
+            }
+            catch (err) {
+                if (!(err instanceof UnknownOptionError) || !this.configs.allowUnknown)
+                    throw err;
+            }
+        }
+        return [argList.slice(0, i), argList.slice(i)];
+    }
+    parseLongOption(arg, nextArg) {
+        const offset = 2;
+        let name;
+        let value;
+        try {
+            const [, _name, _value] = this.assignmentExp.exec(arg);
+            name = _name;
+            value = _value ?? '';
+        }
+        catch {
+            name = arg.slice(offset);
+            value = null;
+        }
+        const entry = this.configs.get(name);
+        if (entry == null) {
+            throw new UnknownOptionError(name);
+        }
+        const tag = entry.type;
+        switch (tag) {
+            case 'flag': {
+                return { name, value: true, shouldSkip: false };
+            }
+            case 'text': {
+                if (value != null) {
+                    return { name, value, shouldSkip: false };
+                }
+                else if (Object.hasOwn(entry, 'default')) {
+                    const { default: value } = entry;
+                    return { name, value: value, shouldSkip: false };
+                }
+                else if (nextArg != null) {
+                    return { name, value: nextArg, shouldSkip: true };
+                }
+                throw new NullArgError(name);
+            }
+            case 'int': {
+                if (value != null) {
+                    return { name, value: parseIntStrict(value), shouldSkip: false };
+                }
+                else if (Object.hasOwn(entry, 'default')) {
+                    const { default: value } = entry;
+                    return { name, value: value, shouldSkip: false };
+                }
+                else if (nextArg != null) {
+                    return { name, value: parseIntStrict(nextArg), shouldSkip: true };
+                }
+                throw new NullIntError(name);
+            }
+            case 'float': {
+                if (value != null) {
+                    return { name, value: parseFloatStrict(value), shouldSkip: false };
+                }
+                else if (Object.hasOwn(entry, 'default')) {
+                    const { default: value } = entry;
+                    return { name, value: value, shouldSkip: false };
+                }
+                else if (nextArg != null) {
+                    return { name, value: parseFloatStrict(nextArg), shouldSkip: true };
+                }
+                throw new NullFloatError(name);
+            }
+            case 'count': {
+                if (value != null)
+                    return { name, value: parseIntStrict(value), shouldSkip: false };
+                return { name, value: 1, shouldSkip: false };
+            }
+            case 'list': {
+                if (value === '') {
+                    return { name, value: [], shouldSkip: false };
+                }
+                else if (value != null) {
+                    const { sep } = entry;
+                    return { name, value: value.split(sep ?? ','), shouldSkip: false };
+                }
+                else if (nextArg != null) {
+                    const { sep } = entry;
+                    return { name, value: nextArg.split(sep ?? ','), shouldSkip: true };
+                }
+                throw new NullArgError(name);
+            }
+            case 'alias': {
+                const { target } = entry;
+                const targetEntry = this.configs.get(target);
+                const targetType = targetEntry.type;
+                switch (targetType) {
+                    case 'flag': {
+                        return { name: target, value: true, shouldSkip: false };
+                    }
+                    case 'text': {
+                        if (value != null) {
+                            return { name: target, value, shouldSkip: false };
+                        }
+                        else if (Object.hasOwn(targetEntry, 'default')) {
+                            const { default: value } = targetEntry;
+                            return { name: target, value: value, shouldSkip: false };
+                        }
+                        else if (nextArg != null) {
+                            return { name: target, value: nextArg, shouldSkip: true };
+                        }
+                        throw new NullArgError(name, target);
+                    }
+                    case 'int': {
+                        if (value != null) {
+                            return {
+                                name: target,
+                                value: parseIntStrict(value),
+                                shouldSkip: false,
+                            };
+                        }
+                        else if (Object.hasOwn(targetEntry, 'default')) {
+                            const { default: value } = targetEntry;
+                            return { name: target, value: value, shouldSkip: false };
+                        }
+                        else if (nextArg != null) {
+                            return {
+                                name: target,
+                                value: parseIntStrict(nextArg),
+                                shouldSkip: true
+                            };
+                        }
+                        throw new NullIntError(name, target);
+                    }
+                    case 'float': {
+                        if (value != null) {
+                            return {
+                                name: target,
+                                value: parseFloatStrict(value),
+                                shouldSkip: false,
+                            };
+                        }
+                        else if (Object.hasOwn(targetEntry, 'default')) {
+                            const { default: value } = targetEntry;
+                            return { name: target, value: value, shouldSkip: false };
+                        }
+                        else if (nextArg != null) {
+                            return {
+                                name: target,
+                                value: parseFloatStrict(nextArg),
+                                shouldSkip: true,
+                            };
+                        }
+                        throw new NullFloatError(name, target);
+                    }
+                    case 'count': {
+                        if (value != null)
+                            return {
+                                name: target,
+                                value: parseIntStrict(value),
+                                shouldSkip: false
+                            };
+                        return { name: target, value: 1, shouldSkip: false };
+                    }
+                    case 'list': {
+                        if (value === '') {
+                            return { name: target, value: [], shouldSkip: false };
+                        }
+                        else if (value != null) {
+                            const { sep } = targetEntry;
+                            return {
+                                name: target,
+                                value: value.split(sep ?? ','),
+                                shouldSkip: false
+                            };
+                        }
+                        else if (nextArg != null) {
+                            const { sep } = targetEntry;
+                            return {
+                                name: target,
+                                value: nextArg.split(sep ?? ','),
+                                shouldSkip: true
+                            };
+                        }
+                        throw new NullArgError(name, target);
+                    }
+                }
+            }
+        }
+    }
+    parseShortOption(arg, nextArg) {
+        let name;
+        let value;
+        let entry;
+        const pairs = Object.create(null);
+        for (let i = 1, n = arg.length; i < n; i++) {
+            name = arg[i];
+            value = nextArg ?? null;
+            entry = this.configs.get(name);
+            if (entry == null && this.configs.allowUnknown) {
+                /* silently skip unknown options */
+                continue;
+            }
+            else if (entry == null) {
+                throw new UnknownOptionError(name);
+            }
+            const tag = entry.type;
+            switch (tag) {
+                case 'flag': {
+                    pairs[name] = true;
+                    break;
+                }
+                case 'text': {
+                    if (i < n - 1) {
+                        value = arg.slice(i + 1, n);
+                        pairs[name] = value;
+                        return [false, pairs];
+                    }
+                    else if (Object.hasOwn(entry, 'default')) {
+                        const { default: value } = entry;
+                        pairs[name] = value;
+                        return [false, pairs];
+                    }
+                    else if (value != null) {
+                        pairs[name] = value;
+                        return [true, pairs];
+                    }
+                    throw new NullArgError(name);
+                }
+                case 'int': {
+                    if (i < n - 1) {
+                        value = arg.slice(i + 1, n);
+                        pairs[name] = parseIntStrict(value);
+                        return [false, pairs];
+                    }
+                    else if (Object.hasOwn(entry, 'default')) {
+                        const { default: value } = entry;
+                        pairs[name] = value;
+                        return [false, pairs];
+                    }
+                    else if (value != null) {
+                        pairs[name] = parseIntStrict(value);
+                        return [true, pairs];
+                    }
+                    throw new NullIntError(name);
+                }
+                case 'float': {
+                    if (i < n - 1) {
+                        value = arg.slice(i + 1, n);
+                        pairs[name] = parseFloatStrict(value);
+                        return [false, pairs];
+                    }
+                    else if (Object.hasOwn(entry, 'default')) {
+                        const { default: value } = entry;
+                        pairs[name] = value;
+                        return [false, pairs];
+                    }
+                    else if (value != null) {
+                        pairs[name] = parseFloatStrict(value);
+                        return [true, pairs];
+                    }
+                    throw new NullFloatError(name);
+                }
+                case 'count': {
+                    const oldValue = pairs[name] ?? 0;
+                    pairs[name] = oldValue + 1;
+                    break;
+                }
+                case 'list': {
+                    if (i < n - 1) {
+                        value = arg.slice(i + 1, n);
+                        const { sep } = entry;
+                        pairs[name] = value.split(sep ?? ',');
+                        return [false, pairs];
+                    }
+                    else if (value === '') {
+                        pairs[name] = [];
+                        return [true, pairs];
+                    }
+                    else if (value != null) {
+                        const { sep } = entry;
+                        pairs[name] = value.split(sep ?? ',');
+                        return [true, pairs];
+                    }
+                    throw new NullArgError(name);
+                }
+                case 'alias': {
+                    const { target } = entry;
+                    const targetEntry = this.configs.get(target);
+                    const targetType = targetEntry.type;
+                    switch (targetType) {
+                        case 'flag': {
+                            pairs[target] = true;
+                            break;
+                        }
+                        case 'text': {
+                            if (i < n - 1) {
+                                value = arg.slice(i + 1, n);
+                                pairs[target] = value;
+                                return [false, pairs];
+                            }
+                            else if (Object.hasOwn(targetEntry, 'default')) {
+                                const { default: value } = targetEntry;
+                                pairs[target] = value;
+                                return [false, pairs];
+                            }
+                            else if (value != null) {
+                                pairs[target] = value;
+                                return [true, pairs];
+                            }
+                            throw new NullArgError(name, target);
+                        }
+                        case 'int': {
+                            if (i < n - 1) {
+                                value = arg.slice(i + 1, n);
+                                pairs[target] = parseIntStrict(value);
+                                return [false, pairs];
+                            }
+                            else if (Object.hasOwn(targetEntry, 'default')) {
+                                const { default: value } = targetEntry;
+                                pairs[target] = value;
+                                return [false, pairs];
+                            }
+                            else if (value != null) {
+                                pairs[target] = parseIntStrict(value);
+                                return [true, pairs];
+                            }
+                            throw new NullIntError(name, target);
+                        }
+                        case 'float': {
+                            if (i < n - 1) {
+                                value = arg.slice(i + 1, n);
+                                pairs[target] = parseFloatStrict(value);
+                                return [false, pairs];
+                            }
+                            else if (Object.hasOwn(targetEntry, 'default')) {
+                                const { default: value } = targetEntry;
+                                pairs[target] = value;
+                                return [false, pairs];
+                            }
+                            else if (value != null) {
+                                pairs[target] = parseFloatStrict(value);
+                                return [true, pairs];
+                            }
+                            throw new NullFloatError(name, target);
+                        }
+                        case 'count': {
+                            const oldValue = pairs[target] ?? 0;
+                            pairs[target] = oldValue + 1;
+                            break;
+                        }
+                        case 'list': {
+                            if (i < n - 1) {
+                                value = arg.slice(i + 1, n);
+                                const { sep } = targetEntry;
+                                pairs[target] = value.split(sep ?? ',');
+                                return [false, pairs];
+                            }
+                            else if (value === '') {
+                                pairs[target] = [];
+                                return [true, pairs];
+                            }
+                            else if (value != null) {
+                                const { sep } = targetEntry;
+                                pairs[target] = value.split(sep ?? ',');
+                                return [true, pairs];
+                            }
+                            throw new NullArgError(name, target);
+                        }
+                    }
+                }
+            }
+        }
+        return [false, pairs];
+    }
+}