@optique/man 0.10.0-dev.0

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-CK3-yKaY.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-tclTvdWs.js";
+import { Program } from "@optique/core/program";
+import { Mode, ModeValue, Parser } from "@optique/core/parser";
+
+//#region src/generator.d.ts
+
+/**
+ * Options for generating a man page from a parser.
+ * Extends {@link ManPageOptions} with the same configuration.
+ * @since 0.10.0
+ */
+interface GenerateManPageOptions extends ManPageOptions {}
+/**
+ * Options for generating a man page from a {@link Program}.
+ *
+ * This interface omits `name`, `version`, `author`, `bugs`, and `examples`
+ * from {@link ManPageOptions} since they are extracted from the program's
+ * metadata. You can still override them by providing values in this options
+ * object.
+ *
+ * @since 0.11.0
+ */
+interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "section">>, Pick<ManPageOptions, "section"> {}
+/**
+ * Generates a man page from a parser synchronously.
+ *
+ * This function extracts documentation from the parser's structure
+ * and formats it as a complete man page in roff format.
+ *
+ * @example
+ * ```typescript
+ * import { generateManPageSync } from "@optique/man";
+ * import { object, option, flag } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ *
+ * const parser = object({
+ *   verbose: flag("-v", "--verbose"),
+ *   config: option("-c", "--config", string()),
+ * });
+ *
+ * const manPage = generateManPageSync(parser, {
+ *   name: "myapp",
+ *   section: 1,
+ *   version: "1.0.0",
+ * });
+ *
+ * console.log(manPage);
+ * ```
+ *
+ * @param parser The parser to generate documentation from.
+ * @param options The man page generation options.
+ * @returns The complete man page in roff format.
+ * @since 0.10.0
+ * @since 0.11.0 Added support for {@link Program} objects.
+ */
+declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
+declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, options: GenerateManPageOptions): string;
+/**
+ * Generates a man page from a parser asynchronously.
+ *
+ * This function extracts documentation from the parser's structure
+ * and formats it as a complete man page in roff format. It supports
+ * both sync and async parsers.
+ *
+ * @example
+ * ```typescript
+ * import { generateManPageAsync } from "@optique/man";
+ * import { object, option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ *
+ * const parser = object({
+ *   config: option("-c", "--config", string()),
+ * });
+ *
+ * const manPage = await generateManPageAsync(parser, {
+ *   name: "myapp",
+ *   section: 1,
+ * });
+ * ```
+ *
+ * @param parser The parser to generate documentation from.
+ * @param options The man page generation options.
+ * @returns A promise that resolves to the complete man page in roff format.
+ * @since 0.10.0
+ * @since 0.11.0 Added support for {@link Program} objects.
+ */
+declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
+declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown, unknown>, options: GenerateManPageOptions): Promise<string>;
+/**
+ * Generates a man page from a parser or program.
+ *
+ * This function extracts documentation from the parser's structure
+ * and formats it as a complete man page in roff format.
+ *
+ * For sync parsers, it returns the man page directly.
+ * For async parsers, it returns a Promise that resolves to the man page.
+ *
+ * @example Parser-based API
+ * ```typescript
+ * import { generateManPage } from "@optique/man";
+ * import { object, option, flag } from "@optique/core/primitives";
+ * import { string, integer } from "@optique/core/valueparser";
+ * import { message } from "@optique/core/message";
+ *
+ * const parser = object({
+ *   verbose: flag("-v", "--verbose", {
+ *     description: message`Enable verbose output.`,
+ *   }),
+ *   port: option("-p", "--port", integer(), {
+ *     description: message`Port to listen on.`,
+ *   }),
+ * });
+ *
+ * const manPage = generateManPage(parser, {
+ *   name: "myapp",
+ *   section: 1,
+ *   version: "1.0.0",
+ *   date: new Date(),
+ *   author: message`Hong Minhee`,
+ * });
+ *
+ * // Write to file
+ * import { writeFileSync } from "node:fs";
+ * writeFileSync("myapp.1", manPage);
+ * ```
+ *
+ * @example Program-based API
+ * ```typescript
+ * import { generateManPage } from "@optique/man";
+ * import { defineProgram } from "@optique/core/program";
+ * import { object, flag } from "@optique/core/primitives";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog = defineProgram({
+ *   parser: object({
+ *     verbose: flag("-v", "--verbose"),
+ *   }),
+ *   metadata: {
+ *     name: "myapp",
+ *     version: "1.0.0",
+ *     author: message`Hong Minhee`,
+ *   },
+ * });
+ *
+ * // Metadata is automatically extracted from the program
+ * const manPage = generateManPage(prog, { section: 1 });
+ * ```
+ *
+ * @param parserOrProgram The parser or program to generate documentation from.
+ * @param options The man page generation options.
+ * @returns The complete man page in roff format, or a Promise for async parsers.
+ * @since 0.10.0
+ * @since 0.11.0 Added support for {@link Program} objects.
+ */
+declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
+declare function generateManPage<T>(program: Program<"async", T>, options: GenerateManPageProgramOptions): Promise<string>;
+declare function generateManPage(parser: Parser<"sync", unknown, unknown>, options: GenerateManPageOptions): string;
+declare function generateManPage(parser: Parser<"async", unknown, unknown>, options: GenerateManPageOptions): Promise<string>;
+declare function generateManPage<M extends Mode>(parser: Parser<M, unknown, unknown>, options: GenerateManPageOptions): ModeValue<M, string>;
+//#endregion
+export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, escapeHyphens, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-i3JSYqke.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BmhJz56F.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DQks_OLj.js";
+
+export { escapeHyphens, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/man-BMb0Vyt9.d.cts

@@ -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-BmhJz56F.js

@@ -0,0 +1,218 @@
+import { escapeHyphens, formatMessageAsRoff } from "./roff-i3JSYqke.js";
+
+//#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${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${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 = formatMessageAsRoff(entry.description);
+			if (entry.default) desc += ` [${formatMessageAsRoff(entry.default)}]`;
+			lines.push(desc);
+		} else if (entry.default) lines.push(`[${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} \\- ${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(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(formatMessageAsRoff(options.examples));
+	}
+	if (options.bugs) {
+		lines.push(".SH BUGS");
+		lines.push(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(formatMessageAsRoff(options.author));
+	}
+	if (page.footer) {
+		lines.push(".PP");
+		lines.push(formatMessageAsRoff(page.footer));
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };