@optique/core 0.4.0-dev.56 → 0.4.0-dev.58

package/dist/facade.cjs

@@ -289,7 +289,7 @@ function run(parser, programName, args, options = {}) {
 	const onVersion = options.version?.onShow ?? (() => ({}));
 	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log } = options;
+	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
 	const help = options.help ? helpMode : "none";
 	const version = options.version ? versionMode : "none";
 	const helpParsers = help === "none" ? {
@@ -334,11 +334,19 @@ function run(parser, programName, args, options = {}) {
 				else helpGeneratorParser = parser;
 			} else helpGeneratorParser = parser;
 			const doc = require_parser.getDocPage(helpGeneratorParser, classified.commands);
-			if (doc != null) stdout(require_doc.formatDocPage(programName, doc, {
-				colors,
-				maxWidth,
-				showDefault
-			}));
+			if (doc != null) {
+				const augmentedDoc = {
+					...doc,
+					brief: brief ?? doc.brief,
+					description: description ?? doc.description,
+					footer: footer ?? doc.footer
+				};
+				stdout(require_doc.formatDocPage(programName, augmentedDoc, {
+					colors,
+					maxWidth,
+					showDefault
+				}));
+			}
 			try {
 				return onHelp(0);
 			} catch {
@@ -350,11 +358,19 @@ function run(parser, programName, args, options = {}) {
 	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,
-			showDefault
-		}));
+		else {
+			const augmentedDoc = {
+				...doc,
+				brief: brief ?? doc.brief,
+				description: description ?? doc.description,
+				footer: footer ?? doc.footer
+			};
+			stderr(require_doc.formatDocPage(programName, augmentedDoc, {
+				colors,
+				maxWidth,
+				showDefault
+			}));
+		}
 	}
 	if (aboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
 		colors,

package/dist/facade.d.cts

@@ -1,3 +1,4 @@
+import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferValue, Parser } from "./parser.cjs";
 
@@ -117,6 +118,24 @@ interface RunOptions<THelp, TError> {
    * @default `console.log`
    */
   readonly stdout?: (text: string) => void;
+  /**
+   * Brief description shown at the top of help text.
+   *
+   * @since 0.4.0
+   */
+  readonly brief?: Message;
+  /**
+   * Detailed description shown after the usage line.
+   *
+   * @since 0.4.0
+   */
+  readonly description?: Message;
+  /**
+   * Footer text shown at the bottom of help text.
+   *
+   * @since 0.4.0
+   */
+  readonly footer?: Message;
 }
 /**
  * Runs a parser against command-line arguments with built-in help and error

package/dist/facade.d.ts

@@ -1,3 +1,4 @@
+import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferValue, Parser } from "./parser.js";
 
@@ -117,6 +118,24 @@ interface RunOptions<THelp, TError> {
    * @default `console.log`
    */
   readonly stdout?: (text: string) => void;
+  /**
+   * Brief description shown at the top of help text.
+   *
+   * @since 0.4.0
+   */
+  readonly brief?: Message;
+  /**
+   * Detailed description shown after the usage line.
+   *
+   * @since 0.4.0
+   */
+  readonly description?: Message;
+  /**
+   * Footer text shown at the bottom of help text.
+   *
+   * @since 0.4.0
+   */
+  readonly footer?: Message;
 }
 /**
  * Runs a parser against command-line arguments with built-in help and error

package/dist/facade.js

@@ -289,7 +289,7 @@ function run(parser, programName, args, options = {}) {
 	const onVersion = options.version?.onShow ?? (() => ({}));
 	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log } = options;
+	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
 	const help = options.help ? helpMode : "none";
 	const version = options.version ? versionMode : "none";
 	const helpParsers = help === "none" ? {
@@ -334,11 +334,19 @@ function run(parser, programName, args, options = {}) {
 				else helpGeneratorParser = parser;
 			} else helpGeneratorParser = parser;
 			const doc = getDocPage(helpGeneratorParser, classified.commands);
-			if (doc != null) stdout(formatDocPage(programName, doc, {
-				colors,
-				maxWidth,
-				showDefault
-			}));
+			if (doc != null) {
+				const augmentedDoc = {
+					...doc,
+					brief: brief ?? doc.brief,
+					description: description ?? doc.description,
+					footer: footer ?? doc.footer
+				};
+				stdout(formatDocPage(programName, augmentedDoc, {
+					colors,
+					maxWidth,
+					showDefault
+				}));
+			}
 			try {
 				return onHelp(0);
 			} catch {
@@ -350,11 +358,19 @@ function run(parser, programName, args, options = {}) {
 	if (aboveError === "help") {
 		const doc = getDocPage(args.length < 1 ? augmentedParser : parser, args);
 		if (doc == null) aboveError = "usage";
-		else stderr(formatDocPage(programName, doc, {
-			colors,
-			maxWidth,
-			showDefault
-		}));
+		else {
+			const augmentedDoc = {
+				...doc,
+				brief: brief ?? doc.brief,
+				description: description ?? doc.description,
+				footer: footer ?? doc.footer
+			};
+			stderr(formatDocPage(programName, augmentedDoc, {
+				colors,
+				maxWidth,
+				showDefault
+			}));
+		}
 	}
 	if (aboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
 		colors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.4.0-dev.56+2ae81fd7",
+  "version": "0.4.0-dev.58+657dc3fa",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",