zod-args-parser 2.0.0-alpha.0 → 2.0.0-beta.1

package/src/help-message/format-arguments.ts

@@ -1,46 +1,70 @@
-import { concat, indent, insertAtEndOfFirstLine, ln } from "../utilities.js";
+import { indent, indentLines, insertAtEndOfFirstLine, ln, toKebabCase } from "../utilities.ts";
+import { terminalMarkdown } from "./terminal-markdown.ts";
 
-import type { ArgumentMetadata } from "../metadata/metadata-types.js";
-import type { HelpMessageStyle } from "../types.js";
+import type { ArgumentMetadata } from "../types/metadata-types.ts";
+import type { FormatOptions } from "./generate-for-cli.ts";
 
-export function formatHelpMessageArguments(
-  argumentsMetadata: ArgumentMetadata[],
-  c: HelpMessageStyle,
-  longest: number,
-): string {
+export function formatHelpMessageArguments(argumentsMetadata: ArgumentMetadata[], options: FormatOptions): string {
   if (argumentsMetadata.length === 0) return "";
 
-  let message = c.title(" ARGUMENTS") + ln(1);
+  const {
+    style,
+    indentBeforeName,
+    indentAfterName,
+    indentBeforePlaceholder,
+    newLineIndent,
+    longest,
+    argumentsTitle,
+    defaultKeyword,
+    optionalKeyword,
+    exampleKeyword,
+    emptyLines,
+    emptyLinesBeforeTitle,
+    emptyLinesAfterTitle,
+    markdownRenderer,
+    kebabCaseArgumentName,
+  } = options;
+
+  let message = ln(emptyLinesBeforeTitle) + indent(1) + style.title(argumentsTitle) + ln(1 + emptyLinesAfterTitle);
+
+  // the space from the beginning to the start of the next column.
+  const totalSpacing = longest + indentBeforeName + indentAfterName + indentBeforePlaceholder + newLineIndent;
 
   for (const metadata of argumentsMetadata) {
-    const defaultString = metadata.defaultValue === undefined ? "" : `(default: ${metadata.defaultValueAsString})`;
-
-    const spacing = longest + 2 - metadata.name.length;
-    const normalizeDesc = metadata.description.replace(/\n+/g, "\n" + indent(longest + 6) + c.punctuation("└"));
-    const defaultOrOptional = defaultString
-      ? c.default(defaultString)
-      : metadata.optional
-        ? c.optional("(optional)")
-        : "";
-
-    message += concat(
-      indent(2) + c.argument(metadata.name),
-      indent(spacing),
-      insertAtEndOfFirstLine(c.description(normalizeDesc), defaultOrOptional),
-      ln(1),
-    );
+    if (metadata.hidden) continue;
+
+    let description = metadata.description
+      ? style.description(metadata.description)
+      : terminalMarkdown(metadata.descriptionMarkdown, markdownRenderer, style.description);
+
+    description = indentLines(description, totalSpacing);
+
+    let defaultOrOptional = "";
+
+    if (metadata.defaultValueAsString) {
+      defaultOrOptional = style.default(defaultKeyword.replace("{{ value }}", metadata.defaultValueAsString));
+    }
+
+    if (metadata.optional && !defaultOrOptional) {
+      defaultOrOptional = style.optional(optionalKeyword);
+    }
+
+    const spacing = longest - metadata.name.length;
+
+    message +=
+      indent(indentBeforeName) +
+      style.argument(kebabCaseArgumentName ? toKebabCase(metadata.name) : metadata.name) +
+      indent(indentBeforePlaceholder + indentAfterName) +
+      indent(spacing) +
+      insertAtEndOfFirstLine(description, defaultOrOptional) +
+      ln(1 + emptyLines);
 
     if (metadata.example) {
-      const normalizeExample = metadata.example.replace(/\n+/g, "\n" + indent(longest + 16));
-      message += concat(
-        indent(longest + 5),
-        c.punctuation("└") + c.exampleTitle("Example:"),
-        c.example(normalizeExample) + ln(1),
-      );
+      const normalizeExample = indentLines(metadata.example, totalSpacing + exampleKeyword.length + 1); // +1 for the space after the keyword
+      message +=
+        indent(totalSpacing) + style.exampleTitle(exampleKeyword) + indent(1) + style.example(normalizeExample) + ln(1);
     }
   }
 
-  message += ln(1);
-
   return message;
 }

package/src/help-message/format-options.ts

@@ -1,51 +1,76 @@
-import { concat, indent, insertAtEndOfFirstLine, ln } from "../utilities.js";
+import { indent, indentLines, insertAtEndOfFirstLine, ln } from "../utilities.ts";
+import { terminalMarkdown } from "./terminal-markdown.ts";
 
-import type { OptionMetadata } from "../metadata/metadata-types.js";
-import type { HelpMessageStyle } from "../types.js";
+import type { OptionMetadata } from "../types/metadata-types.ts";
+import type { FormatOptions } from "./generate-for-cli.ts";
 
-export function formatHelpMessageOptions(
-  optionsMetadata: OptionMetadata[],
-  c: HelpMessageStyle,
-  longest: number,
-): string {
+export function formatHelpMessageOptions(optionsMetadata: OptionMetadata[], options: FormatOptions): string {
   if (optionsMetadata.length === 0) return "";
 
-  let message = c.title(" OPTIONS") + ln(1);
+  const {
+    style,
+    indentBeforeName,
+    indentAfterName,
+    indentBeforePlaceholder,
+    newLineIndent,
+    emptyLines,
+    longest,
+    exampleKeyword,
+    optionalKeyword,
+    defaultKeyword,
+    optionsTitle,
+    emptyLinesBeforeTitle,
+    emptyLinesAfterTitle,
+    markdownRenderer,
+  } = options;
+
+  let message = ln(emptyLinesBeforeTitle) + indent(1) + style.title(optionsTitle) + ln(1 + emptyLinesAfterTitle);
+
+  // the space from the beginning to the start of the next column.
+  const totalSpacing = longest + indentBeforeName + indentAfterName + indentBeforePlaceholder + newLineIndent;
 
   for (const metadata of optionsMetadata) {
-    const names = metadata.aliasesAsArgs.concat([metadata.nameAsArg]);
-    const normalizeDesc = metadata.description.replace(/\n+/g, "\n" + indent(longest + 6) + c.punctuation("└"));
-    const defaultString = metadata.defaultValue === undefined ? "" : `(default: ${metadata.defaultValueAsString})`;
+    if (metadata.hidden) continue;
 
-    const optLength = names.join(", ").length + metadata.placeholder.length;
-    const spacing = longest + 1 - optLength;
+    const names = [...metadata.aliasesAsArgs, metadata.nameAsArg];
+    const coloredNames = names.map(name => style.option(name)).join(style.punctuation(", "));
 
-    const coloredNames = names.map(name => c.option(name)).join(c.punctuation(", "));
+    let description = metadata.description
+      ? style.description(metadata.description)
+      : terminalMarkdown(metadata.descriptionMarkdown, markdownRenderer, style.description);
 
-    const defaultOrOptional = defaultString
-      ? c.default(defaultString)
-      : metadata.optional
-        ? c.optional("(optional)")
-        : "";
+    description = indentLines(description, totalSpacing);
 
-    message += concat(
-      indent(2) + coloredNames,
-      c.placeholder(metadata.placeholder),
-      indent(spacing),
-      insertAtEndOfFirstLine(c.description(normalizeDesc), defaultOrOptional),
-      ln(1),
-    );
+    let defaultOrOptional = "";
+
+    if (metadata.defaultValueAsString) {
+      defaultOrOptional = style.default(defaultKeyword.replace("{{ value }}", metadata.defaultValueAsString));
+    }
+
+    if (metadata.optional && !defaultOrOptional) {
+      defaultOrOptional = style.optional(optionalKeyword);
+    }
+
+    // space between the option and the description
+    const optLength = names.join(", ").length + metadata.placeholder.length;
+    const spacing = longest - optLength;
+
+    message +=
+      indent(indentBeforeName) +
+      coloredNames +
+      indent(indentBeforePlaceholder) +
+      style.placeholder(metadata.placeholder) +
+      indent(indentAfterName) +
+      indent(spacing) +
+      insertAtEndOfFirstLine(description, defaultOrOptional) +
+      ln(1 + emptyLines);
 
     if (metadata.example) {
-      const normalizeExample = metadata.example.replace(/\n+/g, "\n" + indent(longest + 16));
-      message += concat(
-        indent(longest + 6) + c.punctuation("└") + c.exampleTitle("Example:"),
-        c.example(normalizeExample) + ln(1),
-      );
+      const normalizeExample = indentLines(metadata.example, totalSpacing + exampleKeyword.length + 1); // + 1 for the space after the keyword
+      message +=
+        indent(totalSpacing) + style.exampleTitle(exampleKeyword) + indent(1) + style.example(normalizeExample) + ln(1);
     }
   }
 
-  message += ln(1);
-
   return message;
 }

package/src/help-message/format-subcommands.ts

@@ -1,36 +1,58 @@
-import { concat, indent, ln, subcommandPlaceholder } from "../utilities.js";
+import { indent, indentLines, ln, subcommandPlaceholder } from "../utilities.ts";
+import { terminalMarkdown } from "./terminal-markdown.ts";
 
-import type { SubcommandMetadata } from "../metadata/metadata-types.js";
-import type { HelpMessageStyle } from "../types.js";
+import type { SubcommandMetadata } from "../types/metadata-types.ts";
+import type { FormatOptions } from "./generate-for-cli.ts";
 
-export function formatHelpMessageCommands(
-  subcommandsMetadata: SubcommandMetadata[],
-  c: HelpMessageStyle,
-  longest: number,
-): string {
+export function formatHelpMessageCommands(subcommandsMetadata: SubcommandMetadata[], options: FormatOptions): string {
   if (subcommandsMetadata.length === 0) return "";
 
-  let message = c.title(" COMMANDS") + ln(1);
+  const {
+    style,
+    indentBeforeName,
+    indentAfterName,
+    indentBeforePlaceholder,
+    newLineIndent,
+    longest,
+    commandsTitle,
+    emptyLines,
+    emptyLinesBeforeTitle,
+    emptyLinesAfterTitle,
+    markdownRenderer,
+  } = options;
+
+  let message = ln(emptyLinesBeforeTitle) + indent(1) + style.title(commandsTitle) + ln(1 + emptyLinesAfterTitle);
+
+  // the space from the beginning to the start of the next column.
+  const totalSpacing = longest + indentBeforeName + indentAfterName + indentBeforePlaceholder + newLineIndent;
 
   for (const metadata of subcommandsMetadata) {
+    if (metadata.hidden) continue;
+
     const names = metadata.aliases.concat([metadata.name]);
     const placeholder = subcommandPlaceholder(metadata);
-    const normalizeDesc = metadata.description.replace(/\n+/g, "\n" + indent(longest + 6) + c.punctuation("└"));
 
-    const optLength = names.join(", ").length + placeholder.length;
-    const spacing = longest + 1 - optLength;
+    let description = metadata.description
+      ? style.description(metadata.description)
+      : terminalMarkdown(metadata.descriptionMarkdown, markdownRenderer, style.description);
 
-    const coloredNames = names.map(name => c.command(name)).join(c.punctuation(", "));
+    description = indentLines(description, totalSpacing);
 
-    message += concat(
-      indent(2) + coloredNames,
-      c.placeholder(placeholder),
-      indent(spacing),
-      c.description(normalizeDesc) + ln(1),
-    );
+    const optLength = names.join(", ").length + placeholder.length;
+    const spacing = longest - optLength;
+
+    const coloredNames = names.map(name => style.command(name)).join(style.punctuation(", "));
+
+    message +=
+      indent(indentBeforeName) +
+      coloredNames +
+      indent(indentBeforePlaceholder) +
+      style.placeholder(placeholder) +
+      indent(indentAfterName) +
+      indent(spacing) +
+      description +
+      ln(1 + emptyLines);
   }
 
-  message += ln(1);
-
   return message;
 }

package/src/help-message/generate-for-cli.ts

@@ -0,0 +1,114 @@
+import { getCliMetadata } from "../metadata/cli-metadata.ts";
+import { indent, indentLines, ln, subcommandPlaceholder } from "../utilities.ts";
+import { formatHelpMessageArguments } from "./format-arguments.ts";
+import { formatHelpMessageOptions } from "./format-options.ts";
+import { formatHelpMessageCommands } from "./format-subcommands.ts";
+import { setPrintHelpOptionsDefaults } from "./set-defaults.ts";
+import { helpMessageStyles } from "./styles.ts";
+import { terminalMarkdown } from "./terminal-markdown.ts";
+
+import type { Cli } from "../types/definitions-types.ts";
+import type { HelpMessageStyleImpl, PrintHelpOptions } from "../types/help-message-types.ts";
+
+export interface FormatOptions extends Required<PrintHelpOptions> {
+  style: HelpMessageStyleImpl;
+  longest: number;
+}
+
+export function generateCliHelpMessage(cliDefinition: Cli, printOptions: PrintHelpOptions = {}): string {
+  const options = setPrintHelpOptionsDefaults(printOptions);
+
+  const style = { ...helpMessageStyles.default, ...options.style };
+
+  const metadata = getCliMetadata(cliDefinition);
+
+  const formatTitle = (title: string) => indent(1) + style.title(title);
+
+  let message = "";
+
+  // CLI usage
+  let usage = metadata.usage;
+  if (!usage) {
+    usage = style.punctuation("$");
+    usage += metadata.name ? style.description("", metadata.name) : "";
+    usage += metadata.subcommands.length > 0 ? style.command("", "[command]") : "";
+    usage += metadata.options.length > 0 ? style.option("", "[options]") : "";
+    usage += metadata.arguments.length > 0 ? style.argument("", "<arguments>") : "";
+    usage += metadata.allowPositionals ? style.argument("", "<positionals>") : "";
+  }
+
+  message += formatTitle(options.usageTitle) + ln(1 + options.emptyLinesAfterTitle);
+  message += indent(options.indentBeforeName) + usage + ln(1);
+
+  // CLI description
+  if (metadata.description || metadata.descriptionMarkdown) {
+    message +=
+      ln(options.emptyLinesBeforeTitle) + formatTitle(options.descriptionTitle) + ln(1 + options.emptyLinesAfterTitle);
+
+    let description = metadata.description
+      ? style.description(metadata.description)
+      : terminalMarkdown(metadata.descriptionMarkdown, options.markdownRenderer, style.description);
+
+    description = indentLines(description, options.indentBeforeName);
+
+    message += indent(options.indentBeforeName) + description + ln(1);
+  }
+
+  let longest = 0;
+
+  // Prepare CLI options
+  const optionsMetadata = metadata.options;
+
+  let longestOptionTitle = 0;
+  for (const metadata of optionsMetadata) {
+    const names = [...metadata.aliasesAsArgs, metadata.nameAsArg].join(", ");
+    const optLength = names.length + metadata.placeholder.length;
+    longestOptionTitle = Math.max(optLength, longestOptionTitle);
+  }
+
+  longest = Math.max(longestOptionTitle, longest);
+
+  // Prepare CLI commands
+  const subcommandsMetadata = metadata.subcommands;
+
+  let longestSubcommandTitle = 0;
+  for (const metadata of subcommandsMetadata) {
+    const names = [...metadata.aliases, metadata.name].join(", ");
+    const placeholder = subcommandPlaceholder(metadata);
+    const optLength = names.length + placeholder.length;
+    longestSubcommandTitle = Math.max(optLength, longestSubcommandTitle);
+  }
+
+  longest = Math.max(longestSubcommandTitle, longest);
+
+  // Prepare CLI arguments
+  const argumentsMetadata = metadata.arguments;
+
+  let longestArgumentTitle = 0;
+  for (const argument of argumentsMetadata) {
+    longestArgumentTitle = Math.max(argument.name.length, longestArgumentTitle);
+  }
+
+  longest = Math.max(longestArgumentTitle, longest);
+
+  const formatOptions = Object.assign({ ...options }, { style, longest }) as FormatOptions;
+
+  // CLI options
+  message += formatHelpMessageOptions(optionsMetadata, formatOptions);
+
+  // CLI commands
+  message += formatHelpMessageCommands(subcommandsMetadata, formatOptions);
+
+  // CLI arguments
+  message += formatHelpMessageArguments(argumentsMetadata, formatOptions);
+
+  // CLI example
+  if (metadata.example) {
+    message +=
+      ln(options.emptyLinesBeforeTitle) + formatTitle(options.exampleTitle) + ln(1 + options.emptyLinesAfterTitle);
+    const normalizeExample = indentLines(metadata.example, options.indentBeforeName);
+    message += indent(options.indentBeforeName) + style.example(normalizeExample);
+  }
+
+  return message;
+}

package/src/help-message/generate-for-subcommand.ts

@@ -0,0 +1,32 @@
+import { generateCliHelpMessage } from "./generate-for-cli.ts";
+import { setPrintHelpOptionsDefaults } from "./set-defaults.ts";
+import { helpMessageStyles } from "./styles.ts";
+
+import type { Cli, Subcommand } from "../types/definitions-types.ts";
+import type { PrintHelpOptions } from "../types/help-message-types.ts";
+
+export function generateSubcommandHelpMessage(
+  commandDefinition: Subcommand,
+  options: PrintHelpOptions = {},
+  cliName = "",
+): string {
+  setPrintHelpOptionsDefaults(options);
+
+  const style = { ...helpMessageStyles.default, ...options.style };
+
+  const meta = commandDefinition.meta ?? {};
+
+  let usage = meta.usage;
+  if (!usage) {
+    usage = style.punctuation("$");
+    usage += cliName ? ` ${cliName}` : "";
+    usage += style.command("", commandDefinition.name);
+    usage += commandDefinition.options ? style.option(" [options]") : "";
+    usage += commandDefinition.arguments || commandDefinition.allowPositionals ? style.argument(" <arguments>") : "";
+  }
+
+  // convert to cli object without subcommands
+  const asCliDefinition: Cli = { ...commandDefinition, cliName: commandDefinition.name, meta: { usage, ...meta } };
+
+  return generateCliHelpMessage(asCliDefinition, options);
+}

package/src/help-message/print-help.ts

@@ -0,0 +1,13 @@
+import { generateCliHelpMessage } from "./generate-for-cli.ts";
+import { generateSubcommandHelpMessage } from "./generate-for-subcommand.ts";
+
+import type { Cli, Subcommand } from "../types/definitions-types.ts";
+import type { PrintHelpOptions } from "../types/help-message-types.ts";
+
+export function printCliHelp(cliDefinition: Cli, options: PrintHelpOptions = {}) {
+  console.log(generateCliHelpMessage(cliDefinition, options));
+}
+
+export function printSubcommandHelp(commandDefinition: Subcommand, options: PrintHelpOptions = {}, cliName = "") {
+  console.log(generateSubcommandHelpMessage(commandDefinition, options, cliName));
+}

package/src/help-message/set-defaults.ts

@@ -0,0 +1,34 @@
+import { helpMessageStyles } from "./styles.ts";
+
+import type { PrintHelpOptions } from "../types/help-message-types.ts";
+import type { FormatOptions } from "./generate-for-cli.ts";
+
+export function setPrintHelpOptionsDefaults(options: PrintHelpOptions) {
+  const clone = { ...options };
+
+  clone.style ??= helpMessageStyles.default;
+  clone.markdownRenderer ??= "terminal";
+  clone.kebabCaseArgumentName ??= true;
+
+  clone.indentBeforeName ??= 2;
+  clone.indentAfterName ??= 4;
+  clone.indentBeforePlaceholder ??= 1;
+  clone.newLineIndent ??= 0;
+
+  clone.emptyLines ??= 0;
+  clone.emptyLinesBeforeTitle ??= 1;
+  clone.emptyLinesAfterTitle ??= 0;
+
+  clone.exampleKeyword ??= "Example";
+  clone.optionalKeyword ??= "(optional)";
+  clone.defaultKeyword ??= "(default: {{ value }})";
+
+  clone.usageTitle ??= "USAGE";
+  clone.descriptionTitle ??= "DESCRIPTION";
+  clone.commandsTitle ??= "COMMANDS";
+  clone.optionsTitle ??= "OPTIONS";
+  clone.argumentsTitle ??= "ARGUMENTS";
+  clone.exampleTitle ??= "EXAMPLE";
+
+  return clone as Required<FormatOptions>;
+}