@villedemontreal/caporal 3.1.7

package/src/option/index.ts

@@ -0,0 +1,280 @@
+/**
+ * @packageDocumentation
+ * @module caporal/option
+ */
+
+import {
+  Option,
+  OptionValueType,
+  CreateOptionProgramOpts,
+  CreateOptionCommandOpts,
+  Action,
+  ActionParameters,
+  GlobalOptions,
+  ParserProcessedResult,
+} from "../types"
+import { checkValidator, isBoolValidator, getTypeHint } from "../validator/utils"
+import { parseOptionSynopsis } from "./utils"
+import { logger } from "../logger"
+import type { Command } from "../command"
+import type { Program } from "../program"
+import { getHelp } from "../help"
+import { installCompletion, uninstallCompletion } from "../autocomplete"
+
+/**
+ * Create an Option object
+ *
+ * @internal
+ * @param synopsis
+ * @param description
+ * @param options
+ */
+export function createOption(
+  synopsis: string,
+  description: string,
+  options: CreateOptionProgramOpts | CreateOptionCommandOpts = {},
+): Option {
+  // eslint-disable-next-line prefer-const
+  let { validator, required, hidden } = options
+
+  // force casting
+  required = Boolean(required)
+
+  checkValidator(validator)
+  const syno = parseOptionSynopsis(synopsis)
+  let boolean = syno.valueType === OptionValueType.None || isBoolValidator(validator)
+  if (validator && !isBoolValidator(validator)) {
+    boolean = false
+  }
+
+  const opt: Option = {
+    kind: "option",
+    default: boolean == true ? Boolean(options.default) : options.default,
+    description,
+    choices: Array.isArray(validator) ? validator : [],
+    ...syno,
+    required,
+    visible: !hidden,
+    boolean,
+    validator,
+  }
+
+  opt.typeHint = getTypeHint(opt)
+
+  return opt
+}
+
+export { showHelp }
+
+/**
+ * Display help. Return false to prevent further processing.
+ *
+ * @internal
+ */
+const showHelp: Action = async ({ program, command }: ActionParameters) => {
+    const help = await getHelp(program, command)
+    // eslint-disable-next-line no-console
+    console.log(help)
+    program.emit("help", help)
+    return false
+  },
+  /**
+   * Display program version. Return false to prevent further processing.
+   *
+   * @internal
+   */
+  showVersion: Action = ({ program }: ActionParameters) => {
+    // eslint-disable-next-line no-console
+    console.log(program.getVersion())
+    program.emit("version", program.getVersion())
+    return false
+  },
+  /**
+   * Disable colors in output
+   *
+   * @internal
+   */
+  disableColors: Action = ({ logger }: ActionParameters) => {
+    logger.disableColors()
+  },
+  /**
+   * Set verbosity to the maximum
+   *
+   * @internal
+   */
+  setVerbose: Action = ({ logger }: ActionParameters) => {
+    logger.level = "silly"
+  },
+  /**
+   * Makes the program quiet, eg displaying logs with level >= warning
+   */
+  setQuiet: Action = ({ logger }: ActionParameters) => {
+    logger.level = "warn"
+  },
+  /**
+   * Makes the program totally silent
+   */
+  setSilent: Action = ({ logger }: ActionParameters) => {
+    logger.silent = true
+  },
+  /**
+   * Install completion
+   */
+  installComp: Action = ({ program }: ActionParameters) => {
+    return installCompletion(program)
+  },
+  /**
+   * Uninstall completion
+   */
+  uninstallComp: Action = ({ program }: ActionParameters) => {
+    return uninstallCompletion(program)
+  }
+
+/**
+ * Global options container
+ *
+ * @internal
+ */
+let globalOptions: undefined | GlobalOptions
+
+/**
+ * Get the list of registered global flags
+ *
+ * @internal
+ */
+export function getGlobalOptions(): GlobalOptions {
+  if (globalOptions === undefined) {
+    globalOptions = setupGlobalOptions()
+  }
+  return globalOptions
+}
+
+/**
+ * Set up the global flags
+ *
+ * @internal
+ */
+function setupGlobalOptions(): GlobalOptions {
+  const help = createOption("-h, --help", "Display global help or command-related help."),
+    verbose = createOption(
+      "-v, --verbose",
+      "Verbose mode: will also output debug messages.",
+    ),
+    quiet = createOption(
+      "--quiet",
+      "Quiet mode - only displays warn and error messages.",
+    ),
+    silent = createOption(
+      "--silent",
+      "Silent mode: does not output anything, giving no indication of success or failure other than the exit code.",
+    ),
+    version = createOption("-V, --version", "Display version."),
+    color = createOption("--no-color", "Disable use of colors in output."),
+    installCompOpt = createOption(
+      "--install-completion",
+      "Install completion for your shell.",
+      { hidden: true },
+    ),
+    uninstallCompOpt = createOption(
+      "--uninstall-completion",
+      "Uninstall completion for your shell.",
+      { hidden: true },
+    )
+
+  return new Map([
+    [help, showHelp],
+    [version, showVersion],
+    [color, disableColors],
+    [verbose, setVerbose],
+    [quiet, setQuiet],
+    [silent, setSilent],
+    [installCompOpt, installComp],
+    [uninstallCompOpt, uninstallComp],
+  ])
+}
+
+export function resetGlobalOptions(): GlobalOptions {
+  return (globalOptions = setupGlobalOptions())
+}
+
+/**
+ * Disable a global option
+ *
+ * @param name Can be the option short/long name or notation
+ */
+export function disableGlobalOption(name: string): boolean {
+  const opts = getGlobalOptions()
+  for (const [opt] of opts) {
+    if (opt.allNames.includes(name) || opt.allNotations.includes(name)) {
+      return opts.delete(opt)
+    }
+  }
+  return false
+}
+
+/**
+ * Add a global option to the program.
+ * A global option is available at the program level,
+ * and associated with one given {@link Action}.
+ *
+ * @param a {@link Option} instance, for example created using {@link createOption()}
+ */
+export function addGlobalOption(opt: Option, action?: Action): GlobalOptions {
+  return getGlobalOptions().set(opt, action)
+}
+
+/**
+ * Process global options, if any
+ * @internal
+ */
+export async function processGlobalOptions(
+  parsed: ParserProcessedResult,
+  program: Program,
+  command?: Command,
+): Promise<boolean> {
+  const { options } = parsed
+  const actionsParams = { ...parsed, logger, program, command }
+  const promises = Object.entries(options).map(([opt]) => {
+    const action = findGlobalOptAction(opt)
+    if (action) {
+      return action(actionsParams)
+    }
+    return undefined
+  })
+  const results = await Promise.all(promises)
+  return results.some((r) => r === false)
+}
+
+/**
+ * Find a global Option action from the option name (short or long)
+ *
+ * @param name Short or long name
+ * @internal
+ */
+export function findGlobalOptAction(name: string): Action | undefined {
+  for (const [opt, action] of getGlobalOptions()) {
+    if (opt.allNames.includes(name)) {
+      return action
+    }
+  }
+  return undefined
+}
+
+/**
+ * Find a global Option by it's name (short or long)
+ *
+ * @param name Short or long name
+ * @internal
+ */
+export function findGlobalOption(name: string): Option | undefined {
+  for (const [opt] of getGlobalOptions()) {
+    if (opt.allNames.includes(name)) {
+      return opt
+    }
+  }
+  return undefined
+}
+
+export function isOptionObject(obj: unknown): obj is Option {
+  return typeof obj == "object" && obj !== null && (obj as Option).kind == "option"
+}

package/src/option/mapping.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Command } from "../command"
+import map from "lodash/map"
+import zipObject from "lodash/zipObject"
+import invert from "lodash/invert"
+import pickBy from "lodash/pickBy"
+
+export function getOptsMapping(cmd: Command): Record<string, string> {
+  const names = map(cmd.options, "name")
+  const aliases = map(cmd.options, (o) => o.shortName || o.longName)
+  const result = zipObject(names, aliases)
+  return pickBy({ ...result, ...invert(result) }) as Record<string, string>
+}

package/src/option/utils.ts

@@ -0,0 +1,141 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import camelCase from "lodash/camelCase"
+import kebabCase from "lodash/kebabCase"
+import { OptionSynopsisSyntaxError } from "../error"
+import { OptionValueType } from "../types"
+import type { OptionSynopsis, ParserTypes } from "../types"
+
+const REG_SHORT_OPT = /^-[a-z]$/i
+const REG_LONG_OPT = /^--[a-z]{2,}/i
+const REG_OPT = /^(-[a-zA-Z]|--\D{1}[\w-]+)/
+
+function isShortOpt(flag: string): boolean {
+  return REG_SHORT_OPT.test(flag)
+}
+
+function isLongOpt(flag: string): boolean {
+  return REG_LONG_OPT.test(flag)
+}
+
+/**
+ * Specific version of camelCase which does not lowercase short flags
+ *
+ * @param name Flag short or long name
+ */
+function camelCaseOpt(name: string): string {
+  return name.length === 1 ? name : camelCase(name)
+}
+
+export function getCleanNameFromNotation(str: string, camelCased = true): string {
+  str = str
+    .replace(/([[\]<>]+)/g, "")
+    .replace("...", "")
+    .replace(/^no-/, "")
+  return camelCased ? camelCaseOpt(str) : str
+}
+
+export function getDashedOpt(name: string): string {
+  const l = Math.min(name.length, 2)
+  return "-".repeat(l) + kebabCase(name)
+}
+
+export function isNumeric(n: string): boolean {
+  return !isNaN(parseFloat(n)) && isFinite(Number(n))
+}
+
+export function isOptionStr(str?: string): str is string {
+  return str !== undefined && str !== "--" && REG_OPT.test(str)
+}
+
+export function isConcatenatedOpt(str: string): string[] | false {
+  if (str.match(/^-([a-z]{2,})/i)) {
+    return str.substr(1).split("")
+  }
+  return false
+}
+
+export function isNegativeOpt(opt: string): boolean {
+  return opt.substr(0, 5) === "--no-"
+}
+
+export function isOptArray(flag: ParserTypes | ParserTypes[]): flag is ParserTypes[] {
+  return Array.isArray(flag)
+}
+
+export function formatOptName(name: string): string {
+  return camelCaseOpt(name.replace(/^--?(no-)?/, ""))
+}
+
+/**
+ * Parse a option synopsis
+ *
+ * @example
+ * parseSynopsis("-f, --file <path>")
+ * // Returns...
+ * {
+ *    longName: 'file',
+ *    longNotation: '--file',
+ *    shortNotation: '-f',
+ *    shortName: 'f'
+ *    valueType: 0, // 0 = optional, 1 = required, 2 = no value
+ *    variadic: false
+ *    name: 'file'
+ *    notation: '--file' // either the long or short notation
+ * }
+ *
+ * @param synopsis
+ * @ignore
+ */
+export function parseOptionSynopsis(synopsis: string): OptionSynopsis {
+  // synopsis = synopsis.trim()
+  const analysis: OptionSynopsis = {
+    variadic: false,
+    valueType: OptionValueType.None,
+    valueRequired: false,
+    allNames: [],
+    allNotations: [],
+    name: "",
+    notation: "",
+    synopsis,
+  }
+
+  const infos: Partial<OptionSynopsis> = synopsis
+    .split(/[\s\t,]+/)
+    .reduce((acc, value) => {
+      if (isLongOpt(value)) {
+        acc.longNotation = value
+        acc.longName = getCleanNameFromNotation(value.substring(2))
+        acc.allNames.push(acc.longName)
+        acc.allNotations.push(value)
+      } else if (isShortOpt(value)) {
+        acc.shortNotation = value
+        acc.shortName = value.substring(1)
+        acc.allNames.push(acc.shortName)
+        acc.allNotations.push(value)
+      } else if (value.substring(0, 1) === "[") {
+        acc.valueType = OptionValueType.Optional
+        acc.valueRequired = false
+        acc.variadic = value.substr(-4, 3) === "..."
+      } else if (value.substring(0, 1) === "<") {
+        acc.valueType = OptionValueType.Required
+        acc.valueRequired = true
+        acc.variadic = value.substr(-4, 3) === "..."
+      }
+      return acc
+    }, analysis)
+
+  if (infos.longName === undefined && infos.shortName === undefined) {
+    throw new OptionSynopsisSyntaxError(synopsis)
+  }
+
+  infos.name = infos.longName || (infos.shortName as string)
+  infos.notation = infos.longNotation || (infos.shortNotation as string)
+
+  const fullSynopsis = { ...infos } as OptionSynopsis
+
+  return fullSynopsis
+}

package/src/option/validate.ts

@@ -0,0 +1,80 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import reduce from "lodash/reduce"
+import { findOption } from "./find"
+import { MissingFlagError, UnknownOptionError, CommonError } from "../error"
+import { findGlobalOption } from "."
+import { validate } from "../validator/validate"
+
+import type { ParsedOption, ParsedOptions, Promisable, Option } from "../types"
+import type { Command } from "../command"
+
+function validateOption(opt: Option, value: ParsedOption): ReturnType<typeof validate> {
+  return opt.validator ? validate(value, opt.validator, opt) : value
+}
+
+export function checkRequiredOpts(cmd: Command, opts: ParsedOptions) {
+  return cmd.options.reduce((acc, opt) => {
+    if (opts[opt.name] === undefined && opt.required) {
+      acc.push(new MissingFlagError(opt, cmd))
+    }
+    return acc
+  }, [] as CommonError[])
+}
+
+function applyDefaults(cmd: Command, opts: ParsedOptions): ParsedOptions {
+  return cmd.options.reduce((acc, opt) => {
+    if (acc[opt.name] === undefined && opt.default !== undefined) {
+      acc[opt.name] = opt.default
+    }
+    return acc
+  }, opts)
+}
+
+type OptionsPromises = Record<string, Promisable<ParsedOption>>
+
+interface OptionsValidationResult {
+  options: ParsedOptions
+  errors: CommonError[]
+}
+
+export async function validateOptions(
+  cmd: Command,
+  options: ParsedOptions,
+): Promise<OptionsValidationResult> {
+  options = applyDefaults(cmd, options)
+  const errors: CommonError[] = []
+  const validations = reduce(
+    options,
+    (...args) => {
+      const [acc, value, name] = args
+      const opt = findGlobalOption(name) || findOption(cmd, name)
+      try {
+        if (opt) {
+          acc[name] = validateOption(opt, value)
+        } else if (cmd.strictOptions) {
+          throw new UnknownOptionError(name, cmd)
+        }
+      } catch (e) {
+        errors.push(e)
+      }
+      return acc
+    },
+    {} as OptionsPromises,
+  )
+  const result = await reduce(
+    validations,
+    async (prevPromise, value, key): Promise<ParsedOptions> => {
+      const collection = await prevPromise
+      collection[key] = await value
+      return collection
+    },
+    Promise.resolve({}) as Promise<ParsedOptions>,
+  )
+
+  errors.push(...checkRequiredOpts(cmd, result))
+  return { options: result, errors }
+}