@optique/man 0.10.0-dev.0

package/dist/man-K9LPAprq.cjs

@@ -0,0 +1,235 @@
+const require_roff = require('./roff-DzxoXJIL.cjs');
+
+//#region src/man.ts
+/**
+* Formats a date for use in man pages.
+*
+* @param date The date to format, or undefined.
+* @returns The formatted date string, or undefined.
+* @since 0.10.0
+*/
+function formatDateForMan(date) {
+	if (date === void 0) return void 0;
+	if (typeof date === "string") return date;
+	const months = [
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December"
+	];
+	return `${months[date.getMonth()]} ${date.getFullYear()}`;
+}
+/**
+* Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+*
+* @param term The usage term to format.
+* @returns The roff-formatted string.
+* @since 0.10.0
+*/
+function formatUsageTermAsRoff(term) {
+	if ("hidden" in term && term.hidden) return "";
+	switch (term.type) {
+		case "argument": return `\\fI${term.metavar}\\fR`;
+		case "option": {
+			const names = term.names.map((name) => `\\fB${require_roff.escapeHyphens(name)}\\fR`).join(" | ");
+			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			return `[${names}${metavarPart}]`;
+		}
+		case "command": return `\\fB${term.name}\\fR`;
+		case "optional": {
+			const inner = formatUsageAsRoff(term.terms);
+			return `[${inner}]`;
+		}
+		case "multiple": {
+			const inner = formatUsageAsRoff(term.terms);
+			if (term.min < 1) return `[${inner} ...]`;
+			return `${inner} ...`;
+		}
+		case "exclusive": {
+			const alternatives = term.terms.map((t) => formatUsageAsRoff(t)).join(" | ");
+			return `(${alternatives})`;
+		}
+		case "literal": return term.value;
+		case "passthrough": return "[...]";
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown usage term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Usage} array as roff markup.
+*
+* @param usage The usage terms to format.
+* @returns The roff-formatted string.
+*/
+function formatUsageAsRoff(usage) {
+	return usage.map(formatUsageTermAsRoff).filter((s) => s !== "").join(" ");
+}
+/**
+* Formats a {@link DocEntry}'s term for man page output.
+*
+* @param term The usage term from the entry.
+* @returns The roff-formatted term string.
+*/
+function formatDocEntryTerm(term) {
+	switch (term.type) {
+		case "option": {
+			const names = term.names.map((name) => `\\fB${require_roff.escapeHyphens(name)}\\fR`).join(", ");
+			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			return `${names}${metavarPart}`;
+		}
+		case "command": return `\\fB${term.name}\\fR`;
+		case "argument": return `\\fI${term.metavar}\\fR`;
+		case "literal": return term.value;
+		default: return formatUsageTermAsRoff(term);
+	}
+}
+/**
+* Formats a {@link DocSection} as roff markup with .TP macros.
+*
+* @param section The section to format.
+* @returns The roff-formatted section content.
+*/
+function formatDocSectionEntries(section) {
+	const lines = [];
+	for (const entry of section.entries) {
+		lines.push(".TP");
+		lines.push(formatDocEntryTerm(entry.term));
+		if (entry.description) {
+			let desc = require_roff.formatMessageAsRoff(entry.description);
+			if (entry.default) desc += ` [${require_roff.formatMessageAsRoff(entry.default)}]`;
+			lines.push(desc);
+		} else if (entry.default) lines.push(`[${require_roff.formatMessageAsRoff(entry.default)}]`);
+	}
+	return lines.join("\n");
+}
+/**
+* Formats a {@link DocPage} as a complete man page in roff format.
+*
+* This function generates a man page following the standard man(7) format,
+* including sections for NAME, SYNOPSIS, DESCRIPTION, OPTIONS, and more.
+*
+* @example
+* ```typescript
+* import { formatDocPageAsMan } from "@optique/man/man";
+* import type { DocPage } from "@optique/core/doc";
+*
+* const page: DocPage = {
+*   brief: message`A sample CLI application`,
+*   usage: [{ type: "argument", metavar: "FILE" }],
+*   sections: [],
+* };
+*
+* const manPage = formatDocPageAsMan(page, {
+*   name: "myapp",
+*   section: 1,
+*   version: "1.0.0",
+* });
+* ```
+*
+* @param page The documentation page to format.
+* @param options The man page options.
+* @returns The complete man page in roff format.
+* @since 0.10.0
+*/
+function formatDocPageAsMan(page, options) {
+	const lines = [];
+	const thParts = [options.name.toUpperCase(), options.section.toString()];
+	if (options.date != null) thParts.push(`"${formatDateForMan(options.date)}"`);
+	if (options.version != null) {
+		const dateStr = options.date != null ? "" : "\"\"";
+		if (dateStr) thParts.push(dateStr);
+		thParts.push(`"${options.name} ${options.version}"`);
+	}
+	if (options.manual != null) {
+		if (options.date == null) thParts.push("\"\"");
+		if (options.version == null) thParts.push("\"\"");
+		thParts.push(`"${options.manual}"`);
+	}
+	lines.push(`.TH ${thParts.join(" ")}`);
+	lines.push(".SH NAME");
+	if (page.brief) lines.push(`${options.name} \\- ${require_roff.formatMessageAsRoff(page.brief)}`);
+	else lines.push(options.name);
+	if (page.usage) {
+		lines.push(".SH SYNOPSIS");
+		lines.push(`.B ${options.name}`);
+		const usageStr = formatUsageAsRoff(page.usage);
+		if (usageStr) lines.push(usageStr);
+	}
+	if (page.description) {
+		lines.push(".SH DESCRIPTION");
+		lines.push(require_roff.formatMessageAsRoff(page.description));
+	}
+	for (const section of page.sections) {
+		if (section.entries.length === 0) continue;
+		const title = section.title?.toUpperCase() ?? "OPTIONS";
+		lines.push(`.SH ${title}`);
+		lines.push(formatDocSectionEntries(section));
+	}
+	if (options.environment && options.environment.entries.length > 0) {
+		lines.push(".SH ENVIRONMENT");
+		lines.push(formatDocSectionEntries(options.environment));
+	}
+	if (options.files && options.files.entries.length > 0) {
+		lines.push(".SH FILES");
+		lines.push(formatDocSectionEntries(options.files));
+	}
+	if (options.exitStatus && options.exitStatus.entries.length > 0) {
+		lines.push(".SH EXIT STATUS");
+		lines.push(formatDocSectionEntries(options.exitStatus));
+	}
+	if (options.examples) {
+		lines.push(".SH EXAMPLES");
+		lines.push(require_roff.formatMessageAsRoff(options.examples));
+	}
+	if (options.bugs) {
+		lines.push(".SH BUGS");
+		lines.push(require_roff.formatMessageAsRoff(options.bugs));
+	}
+	if (options.seeAlso && options.seeAlso.length > 0) {
+		lines.push(".SH SEE ALSO");
+		const refs = options.seeAlso.map((ref, i) => {
+			const suffix = i < options.seeAlso.length - 1 ? "," : "";
+			return `.BR ${ref.name} (${ref.section})${suffix}`;
+		});
+		lines.push(refs.join("\n"));
+	}
+	if (options.author) {
+		lines.push(".SH AUTHOR");
+		lines.push(require_roff.formatMessageAsRoff(options.author));
+	}
+	if (page.footer) {
+		lines.push(".PP");
+		lines.push(require_roff.formatMessageAsRoff(page.footer));
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+Object.defineProperty(exports, 'formatDateForMan', {
+  enumerable: true,
+  get: function () {
+    return formatDateForMan;
+  }
+});
+Object.defineProperty(exports, 'formatDocPageAsMan', {
+  enumerable: true,
+  get: function () {
+    return formatDocPageAsMan;
+  }
+});
+Object.defineProperty(exports, 'formatUsageTermAsRoff', {
+  enumerable: true,
+  get: function () {
+    return formatUsageTermAsRoff;
+  }
+});

package/dist/man-tclTvdWs.d.ts

@@ -0,0 +1,127 @@
+import { Message } from "@optique/core/message";
+import { DocPage, DocSection } from "@optique/core/doc";
+import { UsageTerm } from "@optique/core/usage";
+
+//#region src/man.d.ts
+
+/**
+ * Valid man page section numbers.
+ * @since 0.10.0
+ */
+type ManPageSection = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/**
+ * Options for generating a man page.
+ * @since 0.10.0
+ */
+interface ManPageOptions {
+  /**
+   * The name of the program.  This appears in the NAME section and header.
+   */
+  readonly name: string;
+  /**
+   * The manual section number.  Common sections:
+   * - 1: User commands
+   * - 2: System calls
+   * - 3: Library functions
+   * - 4: Special files
+   * - 5: File formats
+   * - 6: Games
+   * - 7: Miscellaneous
+   * - 8: System administration
+   */
+  readonly section: ManPageSection;
+  /**
+   * The date to display in the man page footer.
+   * If a Date object is provided, it will be formatted as "Month Year".
+   * If a string is provided, it will be used as-is.
+   */
+  readonly date?: string | Date;
+  /**
+   * The version string to display in the man page footer.
+   */
+  readonly version?: string;
+  /**
+   * The manual title (e.g., "User Commands", "System Calls").
+   * This appears in the header.
+   */
+  readonly manual?: string;
+  /**
+   * Author information to include in the AUTHOR section.
+   */
+  readonly author?: Message;
+  /**
+   * Bug reporting information to include in the BUGS section.
+   */
+  readonly bugs?: Message;
+  /**
+   * Examples to include in the EXAMPLES section.
+   */
+  readonly examples?: Message;
+  /**
+   * Cross-references to include in the SEE ALSO section.
+   */
+  readonly seeAlso?: ReadonlyArray<{
+    readonly name: string;
+    readonly section: number;
+  }>;
+  /**
+   * Environment variables to document in the ENVIRONMENT section.
+   */
+  readonly environment?: DocSection;
+  /**
+   * File paths to document in the FILES section.
+   */
+  readonly files?: DocSection;
+  /**
+   * Exit status codes to document in the EXIT STATUS section.
+   */
+  readonly exitStatus?: DocSection;
+}
+/**
+ * Formats a date for use in man pages.
+ *
+ * @param date The date to format, or undefined.
+ * @returns The formatted date string, or undefined.
+ * @since 0.10.0
+ */
+declare function formatDateForMan(date: string | Date | undefined): string | undefined;
+/**
+ * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+ *
+ * @param term The usage term to format.
+ * @returns The roff-formatted string.
+ * @since 0.10.0
+ */
+declare function formatUsageTermAsRoff(term: UsageTerm): string;
+/**
+ * Formats a {@link DocPage} as a complete man page in roff format.
+ *
+ * This function generates a man page following the standard man(7) format,
+ * including sections for NAME, SYNOPSIS, DESCRIPTION, OPTIONS, and more.
+ *
+ * @example
+ * ```typescript
+ * import { formatDocPageAsMan } from "@optique/man/man";
+ * import type { DocPage } from "@optique/core/doc";
+ *
+ * const page: DocPage = {
+ *   brief: message`A sample CLI application`,
+ *   usage: [{ type: "argument", metavar: "FILE" }],
+ *   sections: [],
+ * };
+ *
+ * const manPage = formatDocPageAsMan(page, {
+ *   name: "myapp",
+ *   section: 1,
+ *   version: "1.0.0",
+ * });
+ * ```
+ *
+ * @param page The documentation page to format.
+ * @param options The man page options.
+ * @returns The complete man page in roff format.
+ * @since 0.10.0
+ */
+declare function formatDocPageAsMan(page: DocPage, options: ManPageOptions): string;
+//#endregion
+export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.cjs

@@ -0,0 +1,6 @@
+require('./roff-DzxoXJIL.cjs');
+const require_man = require('./man-K9LPAprq.cjs');
+
+exports.formatDateForMan = require_man.formatDateForMan;
+exports.formatDocPageAsMan = require_man.formatDocPageAsMan;
+exports.formatUsageTermAsRoff = require_man.formatUsageTermAsRoff;

package/dist/man.d.cts

@@ -0,0 +1,2 @@
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BMb0Vyt9.cjs";
+export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.d.ts

@@ -0,0 +1,2 @@
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-tclTvdWs.js";
+export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.js

@@ -0,0 +1,4 @@
+import "./roff-i3JSYqke.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BmhJz56F.js";
+
+export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/roff-CK3-yKaY.d.ts

@@ -0,0 +1,64 @@
+import { Message } from "@optique/core/message";
+
+//#region src/roff.d.ts
+
+/**
+ * Escapes special roff characters in plain text.
+ *
+ * This function handles the following escapes:
+ * - Backslash (`\`) → `\\`
+ * - Period (`.`) at line start → `\&.`
+ * - Single quote (`'`) at line start → `\&'`
+ *
+ * @param text The plain text to escape.
+ * @returns The escaped text safe for use in roff documents.
+ * @since 0.10.0
+ */
+declare function escapeRoff(text: string): string;
+/**
+ * Escapes hyphens in option names to prevent line breaks.
+ *
+ * In roff, a regular hyphen (`-`) can be used as a line break point.
+ * For option names like `--verbose`, we want to use `\-` which prevents
+ * line breaks and renders as a proper minus sign.
+ *
+ * @param text The text containing hyphens to escape.
+ * @returns The text with hyphens escaped as `\-`.
+ * @since 0.10.0
+ */
+declare function escapeHyphens(text: string): string;
+/**
+ * Formats a {@link Message} as roff markup for use in man pages.
+ *
+ * This function converts Optique's structured message format into roff
+ * markup suitable for man pages. Each message term type is converted
+ * to appropriate roff formatting:
+ *
+ * | Term Type | Roff Output |
+ * |-----------|-------------|
+ * | `text` | Plain text (escaped) |
+ * | `optionName` | `\fB--option\fR` (bold) |
+ * | `optionNames` | `\fB--opt1\fR, \fB-o\fR` (comma-separated bold) |
+ * | `metavar` | `\fIFILE\fR` (italic) |
+ * | `value` | `"value"` (quoted) |
+ * | `values` | `"a" "b" "c"` (space-separated quoted) |
+ * | `envVar` | `\fBVAR\fR` (bold) |
+ * | `commandLine` | `\fBcmd\fR` (bold) |
+ *
+ * @example
+ * ```typescript
+ * import { formatMessageAsRoff } from "@optique/man/roff";
+ * import { message, optionName, metavar } from "@optique/core/message";
+ *
+ * const msg = message`Use ${optionName("--config")} ${metavar("FILE")}`;
+ * const roff = formatMessageAsRoff(msg);
+ * // => "Use \\fB\\-\\-config\\fR \\fIFILE\\fR"
+ * ```
+ *
+ * @param msg The message to format.
+ * @returns The roff-formatted string.
+ * @since 0.10.0
+ */
+declare function formatMessageAsRoff(msg: Message): string;
+//#endregion
+export { escapeHyphens, escapeRoff, formatMessageAsRoff };

package/dist/roff-Cs3_UBG5.d.cts

@@ -0,0 +1,64 @@
+import { Message } from "@optique/core/message";
+
+//#region src/roff.d.ts
+
+/**
+ * Escapes special roff characters in plain text.
+ *
+ * This function handles the following escapes:
+ * - Backslash (`\`) → `\\`
+ * - Period (`.`) at line start → `\&.`
+ * - Single quote (`'`) at line start → `\&'`
+ *
+ * @param text The plain text to escape.
+ * @returns The escaped text safe for use in roff documents.
+ * @since 0.10.0
+ */
+declare function escapeRoff(text: string): string;
+/**
+ * Escapes hyphens in option names to prevent line breaks.
+ *
+ * In roff, a regular hyphen (`-`) can be used as a line break point.
+ * For option names like `--verbose`, we want to use `\-` which prevents
+ * line breaks and renders as a proper minus sign.
+ *
+ * @param text The text containing hyphens to escape.
+ * @returns The text with hyphens escaped as `\-`.
+ * @since 0.10.0
+ */
+declare function escapeHyphens(text: string): string;
+/**
+ * Formats a {@link Message} as roff markup for use in man pages.
+ *
+ * This function converts Optique's structured message format into roff
+ * markup suitable for man pages. Each message term type is converted
+ * to appropriate roff formatting:
+ *
+ * | Term Type | Roff Output |
+ * |-----------|-------------|
+ * | `text` | Plain text (escaped) |
+ * | `optionName` | `\fB--option\fR` (bold) |
+ * | `optionNames` | `\fB--opt1\fR, \fB-o\fR` (comma-separated bold) |
+ * | `metavar` | `\fIFILE\fR` (italic) |
+ * | `value` | `"value"` (quoted) |
+ * | `values` | `"a" "b" "c"` (space-separated quoted) |
+ * | `envVar` | `\fBVAR\fR` (bold) |
+ * | `commandLine` | `\fBcmd\fR` (bold) |
+ *
+ * @example
+ * ```typescript
+ * import { formatMessageAsRoff } from "@optique/man/roff";
+ * import { message, optionName, metavar } from "@optique/core/message";
+ *
+ * const msg = message`Use ${optionName("--config")} ${metavar("FILE")}`;
+ * const roff = formatMessageAsRoff(msg);
+ * // => "Use \\fB\\-\\-config\\fR \\fIFILE\\fR"
+ * ```
+ *
+ * @param msg The message to format.
+ * @returns The roff-formatted string.
+ * @since 0.10.0
+ */
+declare function formatMessageAsRoff(msg: Message): string;
+//#endregion
+export { escapeHyphens, escapeRoff, formatMessageAsRoff };

package/dist/roff-DzxoXJIL.cjs

@@ -0,0 +1,140 @@
+
+//#region src/roff.ts
+/**
+* Escapes backslashes in text for roff.
+* This is an internal helper that only handles backslash escaping.
+*
+* @param text The text to escape.
+* @returns The text with backslashes escaped.
+*/
+function escapeBackslashes(text) {
+	return text.replace(/\\/g, "\\\\");
+}
+/**
+* Escapes period and single quote at line starts.
+* In roff, these characters have special meaning when at the start of a line.
+*
+* @param text The text to process.
+* @returns The text with line-start special characters escaped.
+*/
+function escapeLineStarts(text) {
+	if (text === "") return "";
+	let result = text;
+	if (result.startsWith(".") || result.startsWith("'")) result = "\\&" + result;
+	result = result.replace(/\n([.'])/g, "\n\\&$1");
+	return result;
+}
+/**
+* Escapes special roff characters in plain text.
+*
+* This function handles the following escapes:
+* - Backslash (`\`) → `\\`
+* - Period (`.`) at line start → `\&.`
+* - Single quote (`'`) at line start → `\&'`
+*
+* @param text The plain text to escape.
+* @returns The escaped text safe for use in roff documents.
+* @since 0.10.0
+*/
+function escapeRoff(text) {
+	if (text === "") return "";
+	return escapeLineStarts(escapeBackslashes(text));
+}
+/**
+* Escapes hyphens in option names to prevent line breaks.
+*
+* In roff, a regular hyphen (`-`) can be used as a line break point.
+* For option names like `--verbose`, we want to use `\-` which prevents
+* line breaks and renders as a proper minus sign.
+*
+* @param text The text containing hyphens to escape.
+* @returns The text with hyphens escaped as `\-`.
+* @since 0.10.0
+*/
+function escapeHyphens(text) {
+	return text.replace(/-/g, "\\-");
+}
+/**
+* Formats a single {@link MessageTerm} as roff markup.
+* Note: This does NOT escape line-start characters (. and ') because
+* these terms may be concatenated with other terms. Line-start escaping
+* is done in formatMessageAsRoff after all terms are joined.
+*
+* @param term The message term to format.
+* @returns The roff-formatted string.
+*/
+function formatTermAsRoff(term) {
+	switch (term.type) {
+		case "text": return escapeBackslashes(term.text);
+		case "optionName": return `\\fB${escapeHyphens(term.optionName)}\\fR`;
+		case "optionNames": return term.optionNames.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
+		case "metavar": return `\\fI${escapeBackslashes(term.metavar)}\\fR`;
+		case "value": return `"${escapeBackslashes(term.value)}"`;
+		case "values":
+			if (term.values.length === 0) return "";
+			return term.values.map((v) => `"${escapeBackslashes(v)}"`).join(" ");
+		case "envVar": return `\\fB${escapeBackslashes(term.envVar)}\\fR`;
+		case "commandLine": return `\\fB${escapeHyphens(escapeBackslashes(term.commandLine))}\\fR`;
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown message term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Message} as roff markup for use in man pages.
+*
+* This function converts Optique's structured message format into roff
+* markup suitable for man pages. Each message term type is converted
+* to appropriate roff formatting:
+*
+* | Term Type | Roff Output |
+* |-----------|-------------|
+* | `text` | Plain text (escaped) |
+* | `optionName` | `\fB--option\fR` (bold) |
+* | `optionNames` | `\fB--opt1\fR, \fB-o\fR` (comma-separated bold) |
+* | `metavar` | `\fIFILE\fR` (italic) |
+* | `value` | `"value"` (quoted) |
+* | `values` | `"a" "b" "c"` (space-separated quoted) |
+* | `envVar` | `\fBVAR\fR` (bold) |
+* | `commandLine` | `\fBcmd\fR` (bold) |
+*
+* @example
+* ```typescript
+* import { formatMessageAsRoff } from "@optique/man/roff";
+* import { message, optionName, metavar } from "@optique/core/message";
+*
+* const msg = message`Use ${optionName("--config")} ${metavar("FILE")}`;
+* const roff = formatMessageAsRoff(msg);
+* // => "Use \\fB\\-\\-config\\fR \\fIFILE\\fR"
+* ```
+*
+* @param msg The message to format.
+* @returns The roff-formatted string.
+* @since 0.10.0
+*/
+function formatMessageAsRoff(msg) {
+	const joined = msg.map(formatTermAsRoff).join("");
+	const escaped = escapeLineStarts(joined);
+	return escaped.replace(/\n\n+/g, "\n.PP\n");
+}
+
+//#endregion
+Object.defineProperty(exports, 'escapeHyphens', {
+  enumerable: true,
+  get: function () {
+    return escapeHyphens;
+  }
+});
+Object.defineProperty(exports, 'escapeRoff', {
+  enumerable: true,
+  get: function () {
+    return escapeRoff;
+  }
+});
+Object.defineProperty(exports, 'formatMessageAsRoff', {
+  enumerable: true,
+  get: function () {
+    return formatMessageAsRoff;
+  }
+});