yargs-module-contracts.md

yargs module contracts

command

• index function accepts yargs instance, usage instance, and validation instance; returns command instance
• addHandler(cmd, description, builder, handler) accepts the following; returns undefined
  • command string or full object/module
  • optional help text description as string (or false for hidden command)
  • optional options object or builder function that accepts a yargs instance; optionally returns yargs or yargs.argv
  • optional handler function that accepts argv; returns anything (currently ignored)
• addDirectory(dir, context, req, callerFile, opts) accepts the following; returns undefined
  • relative directory as string
  • context object containing commands array and files array
  • require function
  • path (absolute) to file of calling module (1st dir argument is relative to this)
  • optional object containing require-directory options
• getCommands() returns array of previously configured command strings (equivalent to Object.keys(getCommandHandlers()))
• getCommandHandlers() returns object mapping parsed command strings to command objects; command objects contain:
  • original unparsed command string
  • demanded parsed required positional args
  • optional parsed optional positional args
  • builder options object or function
  • handler function
• runCommand(command, yargs, parsed) accepts the following; returns inner parsed argv
  • parsed command string (positional args removed)
  • yargs instance
  • object returned from parser containing argv object and aliases object
• reset() returns command instance

completion

i18n

assumptions

• based on y18n
• module encapulates locales dir with json file per supported locale
• index function accepts opts; returns i18n instance
• yargs should wrap instance to provide default impl and to pass to other modules/plugins

optional API

• getLocale() returns locale as string, e.g. 'en' or 'en_US'
• setLocale(locale) accepts locale string; returns undefined
• updateLocale(obj) accepts object of locale string overrides; returns undefined

required API

• __() accepts msg key as string, msg args as any, and optional errorback function for writes; returns formatted localized msg as string
• __n() accepts the following; returns formatted localized msg as string
  • singular msg key as string
  • plural msg key as string
  • quantity to determine singular or plural, as integer
  • arbitrary number of msg args as any
  • optional errorback function for writes

msg keys/defaults

• 'Commands:'
• 'Options:'
• 'Examples:'
• 'boolean'
• 'count'
• 'string'
• 'number'
• 'array'
• 'required'
• 'default:'
• 'choices:'
• 'generated-value'
• 'Not enough non-option arguments: got %s, need at least %s'
• 'Too many non-option arguments: got %s, maximum of %s'
• 'Missing argument value: %s' (object containing 'one' and 'other' keys)
• 'Missing required argument: %s' (object containing 'one' and 'other' keys)
• 'Unknown argument: %s' (object containing 'one' and 'other' keys)
• 'Invalid values:'
• 'Argument: %s, Given: %s, Choices: %s'
• 'Argument check failed: %s'
• 'Implications failed:'
• 'Not enough arguments following: %s'
• 'Invalid JSON config file: %s'
• 'Path to JSON config file'
• 'Show help'
• 'Show version number'
• 'Did you mean %s?'

parser

• static detailed(args, options)

  accepts:

  • args array of strings
  • yargs configuration object

  returns object containing:

  • argv parsed args object
  • error any error encountered during parsing
  • aliases extended aliases object/mapping
  • newAliases object for aliases added due to camelCasing
  • configuration given options.configuration object

usage

validation