@optique/core 0.5.0-dev.63 → 0.5.0-dev.64

package/dist/index.cjs

@@ -12,6 +12,7 @@ exports.choice = require_valueparser.choice;
 exports.command = require_parser.command;
 exports.concat = require_parser.concat;
 exports.constant = require_parser.constant;
+exports.envVar = require_message.envVar;
 exports.flag = require_parser.flag;
 exports.float = require_valueparser.float;
 exports.formatDocPage = require_doc.formatDocPage;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.cjs";
+import { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.cjs";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
 import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
+import { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.js

@@ -1,8 +1,8 @@
-import { formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
+import { envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
 import { formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, WithDefaultError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { RunError, WithDefaultError, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/message.cjs

@@ -113,6 +113,19 @@ function values(values$1) {
 	};
 }
 /**
+* Creates a {@link MessageTerm} for an environment variable.
+* @param envVar The environment variable name, which is a string that represents
+*               an environment variable. For example, `"PATH"` or `"API_URL"`.
+* @returns A {@link MessageTerm} representing the environment variable.
+* @since 0.5.0
+*/
+function envVar(envVar$1) {
+	return {
+		type: "envVar",
+		envVar: envVar$1
+	};
+}
+/**
 * Formats a {@link Message} into a human-readable string for
 * the terminal.
 * @param msg The message to format, which is an array of
@@ -176,7 +189,13 @@ function formatMessage(msg, options = {}) {
 				width: value$1.length
 			};
 		}
-		else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+		else if (term.type === "envVar") {
+			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
+			yield {
+				text: useColors ? `\x1b[1;4m${envVar$1}\x1b[0m` : envVar$1,
+				width: envVar$1.length
+			};
+		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
 	}
 	let output = "";
 	let totalWidth = 0;
@@ -192,6 +211,7 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
+exports.envVar = envVar;
 exports.formatMessage = formatMessage;
 exports.message = message;
 exports.metavar = metavar;

package/dist/message.d.cts

@@ -89,6 +89,21 @@ type MessageTerm =
    * representations of consecutive values.  For example, `["42", "hello"]`.
    */
   readonly values: readonly string[];
+}
+/**
+ * An environment variable term in the message, which represents
+ * an environment variable name.
+ * @since 0.5.0
+ */ | {
+  /**
+   * The type of the term, which is `"envVar"` for an environment variable.
+   */
+  readonly type: "envVar";
+  /**
+   * The environment variable name, which is a string that represents
+   * an environment variable. For example, `"PATH"` or `"API_URL"`.
+   */
+  readonly envVar: string;
 };
 /**
  * Type representing a message that can include styled/colored values.
@@ -160,6 +175,14 @@ declare function value(value: string): MessageTerm;
  * @returns A {@link MessageTerm} representing the list of values.
  */
 declare function values(values: readonly string[]): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for an environment variable.
+ * @param envVar The environment variable name, which is a string that represents
+ *               an environment variable. For example, `"PATH"` or `"API_URL"`.
+ * @returns A {@link MessageTerm} representing the environment variable.
+ * @since 0.5.0
+ */
+declare function envVar(envVar: string): MessageTerm;
 /**
  * Options for the {@link formatMessage} function.
  */
@@ -196,4 +219,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values };
+export { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values };

package/dist/message.d.ts

@@ -89,6 +89,21 @@ type MessageTerm =
    * representations of consecutive values.  For example, `["42", "hello"]`.
    */
   readonly values: readonly string[];
+}
+/**
+ * An environment variable term in the message, which represents
+ * an environment variable name.
+ * @since 0.5.0
+ */ | {
+  /**
+   * The type of the term, which is `"envVar"` for an environment variable.
+   */
+  readonly type: "envVar";
+  /**
+   * The environment variable name, which is a string that represents
+   * an environment variable. For example, `"PATH"` or `"API_URL"`.
+   */
+  readonly envVar: string;
 };
 /**
  * Type representing a message that can include styled/colored values.
@@ -160,6 +175,14 @@ declare function value(value: string): MessageTerm;
  * @returns A {@link MessageTerm} representing the list of values.
  */
 declare function values(values: readonly string[]): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for an environment variable.
+ * @param envVar The environment variable name, which is a string that represents
+ *               an environment variable. For example, `"PATH"` or `"API_URL"`.
+ * @returns A {@link MessageTerm} representing the environment variable.
+ * @since 0.5.0
+ */
+declare function envVar(envVar: string): MessageTerm;
 /**
  * Options for the {@link formatMessage} function.
  */
@@ -196,4 +219,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values };
+export { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values };

package/dist/message.js

@@ -112,6 +112,19 @@ function values(values$1) {
 	};
 }
 /**
+* Creates a {@link MessageTerm} for an environment variable.
+* @param envVar The environment variable name, which is a string that represents
+*               an environment variable. For example, `"PATH"` or `"API_URL"`.
+* @returns A {@link MessageTerm} representing the environment variable.
+* @since 0.5.0
+*/
+function envVar(envVar$1) {
+	return {
+		type: "envVar",
+		envVar: envVar$1
+	};
+}
+/**
 * Formats a {@link Message} into a human-readable string for
 * the terminal.
 * @param msg The message to format, which is an array of
@@ -175,7 +188,13 @@ function formatMessage(msg, options = {}) {
 				width: value$1.length
 			};
 		}
-		else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+		else if (term.type === "envVar") {
+			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
+			yield {
+				text: useColors ? `\x1b[1;4m${envVar$1}\x1b[0m` : envVar$1,
+				width: envVar$1.length
+			};
+		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
 	}
 	let output = "";
 	let totalWidth = 0;
@@ -191,4 +210,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { formatMessage, message, metavar, optionName, optionNames, text, value, values };
+export { envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values };

package/dist/parser.cjs

@@ -532,7 +532,7 @@ function optional(parser) {
 * withDefault(option("--url", url()), () => {
 *   if (!process.env.INSTANCE_URL) {
 *     throw new WithDefaultError(
-*       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+*       message`Environment variable ${envVar("INSTANCE_URL")} is not set.`
 *     );
 *   }
 *   return new URL(process.env.INSTANCE_URL);

package/dist/parser.d.cts

@@ -286,7 +286,7 @@ declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parse
  * withDefault(option("--url", url()), () => {
  *   if (!process.env.INSTANCE_URL) {
  *     throw new WithDefaultError(
- *       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+ *       message`Environment variable ${envVar("INSTANCE_URL")} is not set.`
  *     );
  *   }
  *   return new URL(process.env.INSTANCE_URL);

package/dist/parser.d.ts

@@ -286,7 +286,7 @@ declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parse
  * withDefault(option("--url", url()), () => {
  *   if (!process.env.INSTANCE_URL) {
  *     throw new WithDefaultError(
- *       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+ *       message`Environment variable ${envVar("INSTANCE_URL")} is not set.`
  *     );
  *   }
  *   return new URL(process.env.INSTANCE_URL);

package/dist/parser.js

@@ -532,7 +532,7 @@ function optional(parser) {
 * withDefault(option("--url", url()), () => {
 *   if (!process.env.INSTANCE_URL) {
 *     throw new WithDefaultError(
-*       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+*       message`Environment variable ${envVar("INSTANCE_URL")} is not set.`
 *     );
 *   }
 *   return new URL(process.env.INSTANCE_URL);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.5.0-dev.63+48ac6884",
+  "version": "0.5.0-dev.64+84de5850",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",