@optique/core 0.1.0-dev.1

package/dist/doc.d.ts

@@ -0,0 +1,129 @@
+import { Message } from "./message.js";
+import { Usage, UsageTerm } from "./usage.js";
+
+//#region src/doc.d.ts
+
+/**
+ * A documentation entry which describes a specific usage of a command or
+ * option.  It includes a subject (the usage), a description, and an optional
+ * default value.
+ */
+interface DocEntry {
+  /**
+   * The subject of the entry, which is typically a command or option
+   * usage.
+   */
+  readonly term: UsageTerm;
+  /**
+   * A description of the entry, which provides additional context or
+   * information about the usage.
+   */
+  readonly description?: Message;
+  /**
+   * An optional default value for the entry, which can be used to
+   * indicate what the default behavior is if the command or option is not
+   * specified.
+   */
+  readonly default?: string;
+}
+/**
+ * A section in a document that groups related entries together.
+ */
+interface DocSection {
+  readonly title?: string;
+  readonly entries: readonly DocEntry[];
+}
+/**
+ * A document page that contains multiple sections, each with its own brief
+ * and a list of entries. This structure is used to organize documentation
+ * for commands, options, and other related information.
+ */
+interface DocPage {
+  readonly brief?: Message;
+  readonly usage?: Usage;
+  readonly description?: Message;
+  readonly sections: readonly DocSection[];
+  readonly footer?: Message;
+}
+/**
+ * A documentation fragment that can be either an entry or a section.
+ * Fragments are building blocks used to construct documentation pages.
+ */
+type DocFragment = {
+  readonly type: "entry";
+} & DocEntry | {
+  readonly type: "section";
+} & DocSection;
+/**
+ * A collection of documentation fragments with an optional description.
+ * This structure is used to gather fragments before organizing them into
+ * a final document page.
+ */
+interface DocFragments {
+  /**
+   * An optional description that applies to the entire collection of fragments.
+   */
+  readonly description?: Message;
+  /**
+   * An array of documentation fragments that can be entries or sections.
+   */
+  readonly fragments: readonly DocFragment[];
+}
+/**
+ * Options for formatting a documentation page.
+ */
+interface DocPageFormatOptions {
+  /**
+   * Whether to include ANSI color codes in the output.
+   * @default `false`
+   */
+  colors?: boolean;
+  /**
+   * Number of spaces to indent terms in documentation entries.
+   * @default `2`
+   */
+  termIndent?: number;
+  /**
+   * Width allocated for terms before descriptions start.
+   * @default `26`
+   */
+  termWidth?: number;
+  /**
+   * Maximum width of the entire formatted output.
+   */
+  maxWidth?: number;
+}
+/**
+ * Formats a documentation page into a human-readable string.
+ *
+ * This function takes a structured {@link DocPage} and converts it into
+ * a formatted string suitable for display in terminals or documentation.
+ * The formatting includes proper indentation, alignment, and optional
+ * color support.
+ *
+ * @param programName The name of the program, used in usage lines
+ * @param page The documentation page to format
+ * @param options Formatting options to customize the output
+ * @returns A formatted string representation of the documentation page
+ *
+ * @example
+ * ```typescript
+ * const page: DocPage = {
+ *   brief: "A CLI tool",
+ *   usage: [{ type: "literal", value: "myapp" }],
+ *   sections: [{
+ *     title: "Options",
+ *     entries: [{
+ *       term: { type: "option", short: "-v", long: "--verbose" },
+ *       description: "Enable verbose output"
+ *     }]
+ *   }]
+ * };
+ *
+ * const formatted = formatDocPage("myapp", page, { colors: true });
+ * console.log(formatted);
+ * ```
+ */
+declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
+//#endregion
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage };

package/dist/doc.js

@@ -0,0 +1,104 @@
+import { formatMessage } from "./message.js";
+import { formatUsage, formatUsageTerm } from "./usage.js";
+
+//#region src/doc.ts
+/**
+* Formats a documentation page into a human-readable string.
+*
+* This function takes a structured {@link DocPage} and converts it into
+* a formatted string suitable for display in terminals or documentation.
+* The formatting includes proper indentation, alignment, and optional
+* color support.
+*
+* @param programName The name of the program, used in usage lines
+* @param page The documentation page to format
+* @param options Formatting options to customize the output
+* @returns A formatted string representation of the documentation page
+*
+* @example
+* ```typescript
+* const page: DocPage = {
+*   brief: "A CLI tool",
+*   usage: [{ type: "literal", value: "myapp" }],
+*   sections: [{
+*     title: "Options",
+*     entries: [{
+*       term: { type: "option", short: "-v", long: "--verbose" },
+*       description: "Enable verbose output"
+*     }]
+*   }]
+* };
+*
+* const formatted = formatDocPage("myapp", page, { colors: true });
+* console.log(formatted);
+* ```
+*/
+function formatDocPage(programName, page, options = {}) {
+	const termIndent = options.termIndent ?? 2;
+	const termWidth = options.termWidth ?? 26;
+	let output = "";
+	if (page.brief != null) {
+		output += formatMessage(page.brief, {
+			colors: options.colors,
+			maxWidth: options.maxWidth,
+			quotes: !options.colors
+		});
+		output += "\n";
+	}
+	if (page.usage != null) {
+		output += "Usage: ";
+		output += indentLines(formatUsage(programName, page.usage, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
+			expandCommands: true
+		}), 7);
+		output += "\n";
+	}
+	if (page.description != null) {
+		output += "\n";
+		output += formatMessage(page.description, {
+			colors: options.colors,
+			maxWidth: options.maxWidth,
+			quotes: !options.colors
+		});
+		output += "\n";
+	}
+	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	for (const section of sections) {
+		output += "\n";
+		if (section.title != null) output += `${section.title}:\n`;
+		for (const entry of section.entries) {
+			const term = formatUsageTerm(entry.term, {
+				colors: options.colors,
+				optionsSeparator: ", ",
+				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
+			});
+			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${entry.description == null ? "" : indentLines(formatMessage(entry.description, {
+				colors: options.colors,
+				quotes: !options.colors,
+				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2
+			}), termIndent + termWidth + 2)}\n`;
+		}
+	}
+	if (page.footer != null) {
+		output += "\n";
+		output += formatMessage(page.footer, {
+			colors: options.colors,
+			maxWidth: options.maxWidth,
+			quotes: !options.colors
+		});
+	}
+	return output;
+}
+function indentLines(text, indent) {
+	return text.split("\n").join("\n" + " ".repeat(indent));
+}
+function ansiAwareRightPad(text, length, char = " ") {
+	const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
+	const strippedText = text.replace(ansiEscapeCodeRegex, "");
+	if (strippedText.length >= length) return text;
+	return text + char.repeat(length - strippedText.length);
+}
+
+//#endregion
+export { formatDocPage };

package/dist/facade.cjs

@@ -0,0 +1,98 @@
+const require_message = require('./message.cjs');
+const require_usage = require('./usage.cjs');
+const require_doc = require('./doc.cjs');
+const require_valueparser = require('./valueparser.cjs');
+const require_parser = require('./parser.cjs');
+
+//#region src/facade.ts
+/**
+* Runs a parser against command-line arguments with built-in help and error
+* handling.
+*
+* This function provides a complete CLI interface by automatically handling
+* help commands/options and displaying formatted error messages with usage
+* information when parsing fails. It augments the provided parser with help
+* functionality based on the configuration options.
+*
+* The function will:
+*
+* 1. Add help command/option support (unless disabled)
+* 2. Parse the provided arguments
+* 3. Display help if requested
+* 4. Show formatted error messages with usage/help info on parse failures
+* 5. Return the parsed result or invoke the appropriate callback
+*
+* @template TParser The parser type being run.
+* @template THelp Return type when help is shown (defaults to `void`).
+* @template TError Return type when an error occurs (defaults to `never`).
+* @param parser The parser to run against the command-line arguments.
+* @param programName Name of the program used in usage and help output.
+* @param args Command-line arguments to parse (typically from
+*             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
+* @param options Configuration options for output formatting and callbacks.
+* @returns The parsed result value, or the return value of `onHelp`/`onError`
+*          callbacks.
+* @throws {RunError} When parsing fails and no `onError` callback is provided.
+*/
+function run(parser, programName, args, options = {}) {
+	let { colors, maxWidth, help = "none", onHelp = () => {}, aboveError = "usage", onError = () => {
+		throw new RunError("Failed to parse command line arguments.");
+	}, stderr = console.error, stdout = console.log } = options;
+	const helpCommand = require_parser.command("help", require_parser.multiple(require_parser.argument(require_valueparser.string({ metavar: "COMMAND" }))), { description: require_message.message`Show help information.` });
+	const helpOption = require_parser.option("--help", { description: require_message.message`Show help information.` });
+	const augmentedParser = help === "none" ? require_parser.object({
+		help: require_parser.constant(false),
+		result: parser
+	}) : require_parser.or(require_parser.object({
+		help: require_parser.constant(false),
+		result: parser
+	}), require_parser.object({
+		help: require_parser.constant(true),
+		command: help === "both" ? require_parser.or(helpCommand, helpOption) : help === "command" ? helpCommand : helpOption
+	}));
+	const result = require_parser.parse(augmentedParser, args);
+	if (result.success) {
+		if (!result.value.help) return result.value.result;
+		const doc = require_parser.getDocPage(typeof result.value.command === "boolean" || result.value.command.length < 1 ? augmentedParser : parser, typeof result.value.command === "boolean" ? [] : result.value.command);
+		if (doc != null) stdout(require_doc.formatDocPage(programName, doc, {
+			colors,
+			maxWidth
+		}));
+		return onHelp(0);
+	}
+	if (aboveError === "help") {
+		const doc = require_parser.getDocPage(args.length < 1 ? augmentedParser : parser, args);
+		if (doc == null) aboveError = "usage";
+		else stderr(require_doc.formatDocPage(programName, doc, {
+			colors,
+			maxWidth
+		}));
+	}
+	if (aboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+		colors,
+		maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+		expandCommands: true
+	}), 7)}`);
+	stderr(`Error: ${require_message.formatMessage(result.error, {
+		colors,
+		quotes: !colors
+	})}`);
+	return onError(1);
+}
+/**
+* An error class used to indicate that the command line arguments
+* could not be parsed successfully.
+*/
+var RunError = class extends Error {
+	constructor(message$1) {
+		super(message$1);
+		this.name = "RunError";
+	}
+};
+function indentLines(text, indent) {
+	return text.split("\n").join("\n" + " ".repeat(indent));
+}
+
+//#endregion
+exports.RunError = RunError;
+exports.run = run;

package/dist/facade.d.cts

@@ -0,0 +1,113 @@
+import { InferValue, Parser } from "./parser.cjs";
+
+//#region src/facade.d.ts
+
+/**
+ * Configuration options for the {@link run} function.
+ *
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
+ */
+interface RunOptions<THelp, TError> {
+  /**
+   * Enable colored output in help and error messages.
+   *
+   * @default `false`
+   */
+  readonly colors?: boolean;
+  /**
+   * Maximum width for output formatting. Text will be wrapped to fit within
+   * this width.  If not specified, text will not be wrapped.
+   */
+  readonly maxWidth?: number;
+  /**
+   * Determines how help is made available:
+   *
+   * - `"command"`: Only the `help` subcommand is available
+   * - `"option"`: Only the `--help` option is available
+   * - `"both"`: Both `help` subcommand and `--help` option are available
+   * - `"none"`: No help functionality is provided
+   *
+   * @default `"none"`
+   */
+  readonly help?: "command" | "option" | "both" | "none";
+  /**
+   * Callback function invoked when help is requested. The function can
+   * optionally receive an exit code parameter.
+   *
+   * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
+   * on Deno to this option.
+   *
+   * @default Returns `void` when help is shown.
+   */
+  readonly onHelp?: (() => THelp) | ((exitCode: number) => THelp);
+  /**
+   * What to display above error messages:
+   * - `"usage"`: Show usage information
+   * - `"help"`: Show help text (if available)
+   * - `"none"`: Show nothing above errors
+   *
+   * @default `"usage"`
+   */
+  readonly aboveError?: "usage" | "help" | "none";
+  /**
+   * Callback function invoked when parsing fails. The function can
+   * optionally receive an exit code parameter.
+   *
+   * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
+   * on Deno to this option.
+   * @default Throws a {@link RunError}.
+   */
+  readonly onError?: (() => TError) | ((exitCode: number) => TError);
+  /**
+   * Function used to output error messages.
+   *
+   * @default `console.error`
+   */
+  readonly stderr?: (text: string) => void;
+  /**
+   * Function used to output help and usage messages.
+   *
+   * @default `console.log`
+   */
+  readonly stdout?: (text: string) => void;
+}
+/**
+ * Runs a parser against command-line arguments with built-in help and error
+ * handling.
+ *
+ * This function provides a complete CLI interface by automatically handling
+ * help commands/options and displaying formatted error messages with usage
+ * information when parsing fails. It augments the provided parser with help
+ * functionality based on the configuration options.
+ *
+ * The function will:
+ *
+ * 1. Add help command/option support (unless disabled)
+ * 2. Parse the provided arguments
+ * 3. Display help if requested
+ * 4. Show formatted error messages with usage/help info on parse failures
+ * 5. Return the parsed result or invoke the appropriate callback
+ *
+ * @template TParser The parser type being run.
+ * @template THelp Return type when help is shown (defaults to `void`).
+ * @template TError Return type when an error occurs (defaults to `never`).
+ * @param parser The parser to run against the command-line arguments.
+ * @param programName Name of the program used in usage and help output.
+ * @param args Command-line arguments to parse (typically from
+ *             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
+ * @param options Configuration options for output formatting and callbacks.
+ * @returns The parsed result value, or the return value of `onHelp`/`onError`
+ *          callbacks.
+ * @throws {RunError} When parsing fails and no `onError` callback is provided.
+ */
+declare function run<TParser extends Parser<unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * An error class used to indicate that the command line arguments
+ * could not be parsed successfully.
+ */
+declare class RunError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { RunError, RunOptions, run };

package/dist/facade.d.ts

@@ -0,0 +1,113 @@
+import { InferValue, Parser } from "./parser.js";
+
+//#region src/facade.d.ts
+
+/**
+ * Configuration options for the {@link run} function.
+ *
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
+ */
+interface RunOptions<THelp, TError> {
+  /**
+   * Enable colored output in help and error messages.
+   *
+   * @default `false`
+   */
+  readonly colors?: boolean;
+  /**
+   * Maximum width for output formatting. Text will be wrapped to fit within
+   * this width.  If not specified, text will not be wrapped.
+   */
+  readonly maxWidth?: number;
+  /**
+   * Determines how help is made available:
+   *
+   * - `"command"`: Only the `help` subcommand is available
+   * - `"option"`: Only the `--help` option is available
+   * - `"both"`: Both `help` subcommand and `--help` option are available
+   * - `"none"`: No help functionality is provided
+   *
+   * @default `"none"`
+   */
+  readonly help?: "command" | "option" | "both" | "none";
+  /**
+   * Callback function invoked when help is requested. The function can
+   * optionally receive an exit code parameter.
+   *
+   * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
+   * on Deno to this option.
+   *
+   * @default Returns `void` when help is shown.
+   */
+  readonly onHelp?: (() => THelp) | ((exitCode: number) => THelp);
+  /**
+   * What to display above error messages:
+   * - `"usage"`: Show usage information
+   * - `"help"`: Show help text (if available)
+   * - `"none"`: Show nothing above errors
+   *
+   * @default `"usage"`
+   */
+  readonly aboveError?: "usage" | "help" | "none";
+  /**
+   * Callback function invoked when parsing fails. The function can
+   * optionally receive an exit code parameter.
+   *
+   * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
+   * on Deno to this option.
+   * @default Throws a {@link RunError}.
+   */
+  readonly onError?: (() => TError) | ((exitCode: number) => TError);
+  /**
+   * Function used to output error messages.
+   *
+   * @default `console.error`
+   */
+  readonly stderr?: (text: string) => void;
+  /**
+   * Function used to output help and usage messages.
+   *
+   * @default `console.log`
+   */
+  readonly stdout?: (text: string) => void;
+}
+/**
+ * Runs a parser against command-line arguments with built-in help and error
+ * handling.
+ *
+ * This function provides a complete CLI interface by automatically handling
+ * help commands/options and displaying formatted error messages with usage
+ * information when parsing fails. It augments the provided parser with help
+ * functionality based on the configuration options.
+ *
+ * The function will:
+ *
+ * 1. Add help command/option support (unless disabled)
+ * 2. Parse the provided arguments
+ * 3. Display help if requested
+ * 4. Show formatted error messages with usage/help info on parse failures
+ * 5. Return the parsed result or invoke the appropriate callback
+ *
+ * @template TParser The parser type being run.
+ * @template THelp Return type when help is shown (defaults to `void`).
+ * @template TError Return type when an error occurs (defaults to `never`).
+ * @param parser The parser to run against the command-line arguments.
+ * @param programName Name of the program used in usage and help output.
+ * @param args Command-line arguments to parse (typically from
+ *             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
+ * @param options Configuration options for output formatting and callbacks.
+ * @returns The parsed result value, or the return value of `onHelp`/`onError`
+ *          callbacks.
+ * @throws {RunError} When parsing fails and no `onError` callback is provided.
+ */
+declare function run<TParser extends Parser<unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * An error class used to indicate that the command line arguments
+ * could not be parsed successfully.
+ */
+declare class RunError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { RunError, RunOptions, run };

package/dist/facade.js

@@ -0,0 +1,97 @@
+import { formatMessage, message } from "./message.js";
+import { formatUsage } from "./usage.js";
+import { formatDocPage } from "./doc.js";
+import { string } from "./valueparser.js";
+import { argument, command, constant, getDocPage, multiple, object, option, or, parse } from "./parser.js";
+
+//#region src/facade.ts
+/**
+* Runs a parser against command-line arguments with built-in help and error
+* handling.
+*
+* This function provides a complete CLI interface by automatically handling
+* help commands/options and displaying formatted error messages with usage
+* information when parsing fails. It augments the provided parser with help
+* functionality based on the configuration options.
+*
+* The function will:
+*
+* 1. Add help command/option support (unless disabled)
+* 2. Parse the provided arguments
+* 3. Display help if requested
+* 4. Show formatted error messages with usage/help info on parse failures
+* 5. Return the parsed result or invoke the appropriate callback
+*
+* @template TParser The parser type being run.
+* @template THelp Return type when help is shown (defaults to `void`).
+* @template TError Return type when an error occurs (defaults to `never`).
+* @param parser The parser to run against the command-line arguments.
+* @param programName Name of the program used in usage and help output.
+* @param args Command-line arguments to parse (typically from
+*             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
+* @param options Configuration options for output formatting and callbacks.
+* @returns The parsed result value, or the return value of `onHelp`/`onError`
+*          callbacks.
+* @throws {RunError} When parsing fails and no `onError` callback is provided.
+*/
+function run(parser, programName, args, options = {}) {
+	let { colors, maxWidth, help = "none", onHelp = () => {}, aboveError = "usage", onError = () => {
+		throw new RunError("Failed to parse command line arguments.");
+	}, stderr = console.error, stdout = console.log } = options;
+	const helpCommand = command("help", multiple(argument(string({ metavar: "COMMAND" }))), { description: message`Show help information.` });
+	const helpOption = option("--help", { description: message`Show help information.` });
+	const augmentedParser = help === "none" ? object({
+		help: constant(false),
+		result: parser
+	}) : or(object({
+		help: constant(false),
+		result: parser
+	}), object({
+		help: constant(true),
+		command: help === "both" ? or(helpCommand, helpOption) : help === "command" ? helpCommand : helpOption
+	}));
+	const result = parse(augmentedParser, args);
+	if (result.success) {
+		if (!result.value.help) return result.value.result;
+		const doc = getDocPage(typeof result.value.command === "boolean" || result.value.command.length < 1 ? augmentedParser : parser, typeof result.value.command === "boolean" ? [] : result.value.command);
+		if (doc != null) stdout(formatDocPage(programName, doc, {
+			colors,
+			maxWidth
+		}));
+		return onHelp(0);
+	}
+	if (aboveError === "help") {
+		const doc = getDocPage(args.length < 1 ? augmentedParser : parser, args);
+		if (doc == null) aboveError = "usage";
+		else stderr(formatDocPage(programName, doc, {
+			colors,
+			maxWidth
+		}));
+	}
+	if (aboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
+		colors,
+		maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+		expandCommands: true
+	}), 7)}`);
+	stderr(`Error: ${formatMessage(result.error, {
+		colors,
+		quotes: !colors
+	})}`);
+	return onError(1);
+}
+/**
+* An error class used to indicate that the command line arguments
+* could not be parsed successfully.
+*/
+var RunError = class extends Error {
+	constructor(message$1) {
+		super(message$1);
+		this.name = "RunError";
+	}
+};
+function indentLines(text, indent) {
+	return text.split("\n").join("\n" + " ".repeat(indent));
+}
+
+//#endregion
+export { RunError, run };