@untool/yargs

@untool/yargs

@untool/yargs is a core mixin powering untool's command line interface and allowing other mixins to define their own commands. These custom commands will work exactly as those defined by untool's own modules and can be called using a local or global un executable.

Installation

$ yarn add @untool/yargs # OR npm install @untool/yargs

CLI

@untool/yargs can either be used with untool's own command line interface or with another CLI frontend. It does not define any commands of its own, but only takes care of basically setting up yargs.

API

@untool/yargs only has a couple of semi-private exports. Please check out untool, our main CLI package, to see how you can use them.

@untool/yargs exposes a couple of mixin hooks other mixins can implement, allowing them to alter or extend its functionality. These hooks will be called either by @untool/yargs itself or by others.

registerCommands(yargs) (pipe)

This is the most relevant hook provided by @untool/yargs: it enables other mixins to register their respective commands. Implementations of this mixin method will receive two arguments: a yargs instance and the command line arguments @untool/yargs received. Implementations need to return the yargs instance that they were called with.

const { Mixin } = require('@untool/core');

module.exports = class FooMixin extends Mixin {
  registerCommands(yargs) {
    return yargs.command(
      this.configureCommand({
        command: 'foo',
        builder: {},
        handler: (argv) => {},
      })
    );
  }
};

configureCommand(definition) (pipe)

By implemention this method, your mixin can intercept and alter command configuration. Its main purpose is to enable you to add arguments to commands defined by other mixins.

const { Mixin } = require('@untool/core');

module.exports = class FooBarMixin extends Mixin {
  configureCommand(definition) {
    if (definition.command === 'foo') {
      command.builder.bar = {
        alias: 'b',
        default: false,
        describe: 'Enable bar',
        type: 'boolean',
      };
    }
    return definition;
  }
};

handleArguments(argv) (sequence)

Your mixin's implementation of this method will receive the parsed CLI arguments passed to @untool/yargs. You may want to implement it if you need to alter mixin behaviour according to these args.

const { Mixin } = require('@untool/core');

module.exports = class FooMixin extends Mixin {
  handleArguments(argv) {
    this.options = { ...this.options, ...argv };
  }
};

handleError(error) (override)

By implementing this method, you can intercept uncaught errors and unhandled promise rejections. Make sure you terminate the process in which this method is being called.

const { Mixin } = require('@untool/core');
const { logError } = require('./logger');

module.exports = class FooMixin extends Mixin {
  handleError(error) {
    logError(error).then(() => process.exit(1));
  }
};