@optique/man 0.10.7 → 1.0.0-dev.1109

package/dist/{generator-CCa36YC2.js → generator-YM0drazb.js}

@@ -1,18 +1,42 @@
-import { formatDocPageAsMan } from "./man-Leuf7kOn.js";
+import { formatDocPageAsMan } from "./man-BE1OY_lJ.js";
 import { getDocPageAsync, getDocPageSync } from "@optique/core/parser";
 
 //#region src/generator.ts
 /**
+* Checks if the given value looks like a {@link Parser} at runtime.
+*/
+function isParser(value) {
+	try {
+		if (value == null || typeof value !== "object") return false;
+		const p = value;
+		return "parse" in p && typeof p.parse === "function" && "complete" in p && typeof p.complete === "function" && "$mode" in p && (p.$mode === "sync" || p.$mode === "async") && "usage" in p && Array.isArray(p.usage) && "initialState" in p && "suggest" in p && typeof p.suggest === "function" && "getDocFragments" in p && typeof p.getDocFragments === "function";
+	} catch {
+		return false;
+	}
+}
+/**
 * Checks if the given value is a {@link Program} object.
 */
 function isProgram(value) {
-	return typeof value === "object" && value !== null && "parser" in value && "metadata" in value;
+	try {
+		return typeof value === "object" && value !== null && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata !== null && "name" in value.metadata && typeof value.metadata.name === "string";
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates that the extracted parser is a genuine Optique parser.
+* @throws {TypeError} If the value is not a valid Parser.
+*/
+function validateParser(value) {
+	if (!isParser(value)) throw new TypeError("The given value is not a valid Parser or Program.");
 }
 /**
 * Extracts parser and merged options from a parser or program.
 */
 function extractParserAndOptions(parserOrProgram, options) {
 	if (isProgram(parserOrProgram)) {
+		validateParser(parserOrProgram.parser);
 		const { metadata } = parserOrProgram;
 		const programOptions = options;
 		return {
@@ -26,6 +50,9 @@ function extractParserAndOptions(parserOrProgram, options) {
 				author: programOptions.author ?? metadata.author,
 				bugs: programOptions.bugs ?? metadata.bugs,
 				examples: programOptions.examples ?? metadata.examples,
+				brief: programOptions.brief ?? metadata.brief,
+				description: programOptions.description ?? metadata.description,
+				footer: programOptions.footer ?? metadata.footer,
 				seeAlso: programOptions.seeAlso,
 				environment: programOptions.environment,
 				files: programOptions.files,
@@ -33,6 +60,7 @@ function extractParserAndOptions(parserOrProgram, options) {
 			}
 		};
 	}
+	validateParser(parserOrProgram);
 	return {
 		parser: parserOrProgram,
 		mergedOptions: options
@@ -40,6 +68,7 @@ function extractParserAndOptions(parserOrProgram, options) {
 }
 function generateManPageSync(parserOrProgram, options) {
 	const { parser, mergedOptions } = extractParserAndOptions(parserOrProgram, options);
+	if (parser.$mode === "async") throw new TypeError("Cannot use an async parser with generateManPageSync(). Use generateManPageAsync() or generateManPage() instead.");
 	const docPage = getDocPageSync(parser) ?? { sections: [] };
 	return formatDocPageAsMan(docPage, mergedOptions);
 }

package/dist/index.cjs

@@ -1,8 +1,10 @@
-const require_generator = require('./generator-zoVk04OH.cjs');
-const require_roff = require('./roff-EpcecLXU.cjs');
-const require_man = require('./man-DGnow1Jr.cjs');
+const require_man = require('./man-CkvscTlM.cjs');
+const require_roff = require('./roff-DJ-LkRXl.cjs');
+const require_generator = require('./generator-RyVL5b_V.cjs');
 
 exports.escapeHyphens = require_roff.escapeHyphens;
+exports.escapeQuotedValue = require_roff.escapeQuotedValue;
+exports.escapeRequestArg = require_roff.escapeRequestArg;
 exports.escapeRoff = require_roff.escapeRoff;
 exports.formatDateForMan = require_man.formatDateForMan;
 exports.formatDocPageAsMan = require_man.formatDocPageAsMan;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-72Am6STB.cjs";
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BMb0Vyt9.cjs";
+import { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-COeDIWWF.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DKwa47XV.cjs";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 
@@ -14,10 +14,10 @@ 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.
+ * For Program inputs, `name`, `version`, `author`, `bugs`, `examples`,
+ * `brief`, `description`, and `footer` default to values from
+ * `program.metadata`.
+ * These fields are optional here and may be provided to override metadata.
  *
  * @since 0.10.0
  */
@@ -48,9 +48,10 @@ interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "se
  * console.log(manPage);
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @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.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -78,9 +79,10 @@ declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, o
  * });
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns A promise that resolves to the complete man page in roff format.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
@@ -148,6 +150,7 @@ declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown,
  * @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.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -156,4 +159,4 @@ declare function generateManPage(parser: Parser<"sync", unknown, unknown>, optio
 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 };
+export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, type RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-B36zMxYc.js";
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-tclTvdWs.js";
+import { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CgYQDHBN.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-B1Q2mhit.js";
 import { Program } from "@optique/core/program";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 
@@ -14,10 +14,10 @@ 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.
+ * For Program inputs, `name`, `version`, `author`, `bugs`, `examples`,
+ * `brief`, `description`, and `footer` default to values from
+ * `program.metadata`.
+ * These fields are optional here and may be provided to override metadata.
  *
  * @since 0.10.0
  */
@@ -48,9 +48,10 @@ interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "se
  * console.log(manPage);
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @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.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -78,9 +79,10 @@ declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, o
  * });
  * ```
  *
- * @param parser The parser to generate documentation from.
+ * @param parserOrProgram The parser or program to generate documentation from.
  * @param options The man page generation options.
  * @returns A promise that resolves to the complete man page in roff format.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
@@ -148,6 +150,7 @@ declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown,
  * @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.
+ * @throws {TypeError} If the input is not a valid Parser or Program.
  * @since 0.10.0
  */
 declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -156,4 +159,4 @@ declare function generateManPage(parser: Parser<"sync", unknown, unknown>, optio
 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 };
+export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, type RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-C_MiRXVS.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Leuf7kOn.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-CCa36YC2.js";
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CCdIQO7B.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BE1OY_lJ.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-YM0drazb.js";
 
-export { escapeHyphens, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/{man-BMb0Vyt9.d.cts → man-B1Q2mhit.d.ts}

@@ -1,6 +1,6 @@
 import { Message } from "@optique/core/message";
-import { DocPage, DocSection } from "@optique/core/doc";
 import { UsageTerm } from "@optique/core/usage";
+import { DocPage, DocSection } from "@optique/core/doc";
 
 //#region src/man.d.ts
 
@@ -32,7 +32,9 @@ interface ManPageOptions {
   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 `Date` object is provided, it will be formatted as `"Month Year"`
+   * using the host's local timezone.  For timezone-independent output (e.g.,
+   * in CI), pass a pre-formatted string instead.
    * If a string is provided, it will be used as-is.
    */
   readonly date?: string | Date;
@@ -62,7 +64,7 @@ interface ManPageOptions {
    */
   readonly seeAlso?: ReadonlyArray<{
     readonly name: string;
-    readonly section: number;
+    readonly section: ManPageSection;
   }>;
   /**
    * Environment variables to document in the ENVIRONMENT section.
@@ -76,12 +78,37 @@ interface ManPageOptions {
    * Exit status codes to document in the EXIT STATUS section.
    */
   readonly exitStatus?: DocSection;
+  /**
+   * A brief description of the program for the NAME section.
+   * Overrides the brief from the {@link DocPage} if both are present.
+   * @since 1.0.0
+   */
+  readonly brief?: Message;
+  /**
+   * A detailed description of the program for the DESCRIPTION section.
+   * Overrides the description from the {@link DocPage} if both are present.
+   * @since 1.0.0
+   */
+  readonly description?: Message;
+  /**
+   * Footer text appended at the end of the man page.
+   * Overrides the footer from the {@link DocPage} if both are present.
+   * @since 1.0.0
+   */
+  readonly footer?: Message;
 }
 /**
  * Formats a date for use in man pages.
  *
+ * When a `Date` object is given, the month and year are extracted using
+ * the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+ * the same `Date` instant may produce different output on machines in
+ * different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+ * if you need timezone-independent output.
+ *
  * @param date The date to format, or undefined.
  * @returns The formatted date string, or undefined.
+ * @throws {RangeError} If the given `Date` object is invalid.
  * @since 0.10.0
  */
 declare function formatDateForMan(date: string | Date | undefined): string | undefined;
@@ -90,6 +117,7 @@ declare function formatDateForMan(date: string | Date | undefined): string | und
  *
  * @param term The usage term to format.
  * @returns The roff-formatted string.
+ * @throws {TypeError} If the term has an unknown type.
  * @since 0.10.0
  */
 declare function formatUsageTermAsRoff(term: UsageTerm): string;
@@ -120,6 +148,9 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @param page The documentation page to format.
  * @param options The man page options.
  * @returns The complete man page in roff format.
+ * @throws {TypeError} If the program name is empty.
+ * @throws {RangeError} If the section number or any `seeAlso` entry's section
+ * number is not a valid man page section (1–8).
  * @since 0.10.0
  */
 declare function formatDocPageAsMan(page: DocPage, options: ManPageOptions): string;