yargs 15.3.1 → 15.4.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [15.4.0](https://www.github.com/yargs/yargs/compare/v15.3.1...v15.4.0) (2020-06-30)
+
+
+### Features
+
+* adds deprecation option for commands ([027a636](https://www.github.com/yargs/yargs/commit/027a6365b737e13116811a8ef43670196e1fa00a))
+* support array of examples ([#1682](https://www.github.com/yargs/yargs/issues/1682)) ([225ab82](https://www.github.com/yargs/yargs/commit/225ab8271938bed3a48d23175f3d580ce8cd1306))
+
+
+### Bug Fixes
+
+* **docs:** describe usage of `.check()` in more detail ([932cd11](https://www.github.com/yargs/yargs/commit/932cd1177e93f5cc99edfe57a4028e30717bf8fb))
+* **i18n:** Japanese translation phrasing ([#1619](https://www.github.com/yargs/yargs/issues/1619)) ([0894175](https://www.github.com/yargs/yargs/commit/089417550ef5a5b8ce3578dd2a989191300b64cd))
+* **strict mode:** report default command unknown arguments ([#1626](https://www.github.com/yargs/yargs/issues/1626)) ([69f29a9](https://www.github.com/yargs/yargs/commit/69f29a9cd429d4bb99481238305390107ac75b02))
+* **usage:** translate 'options' group only when displaying help ([#1600](https://www.github.com/yargs/yargs/issues/1600)) ([e60b39b](https://www.github.com/yargs/yargs/commit/e60b39b9d3a912c06db43f87c86ba894142b6c1c))
+
+
+### Reverts
+
+* Revert "chore(deps): update dependency eslint to v7 (#1656)" (#1673) ([34949f8](https://www.github.com/yargs/yargs/commit/34949f89ee7cdf88f7b315659df4b5f62f714842)), closes [#1656](https://www.github.com/yargs/yargs/issues/1656) [#1673](https://www.github.com/yargs/yargs/issues/1673)
+
 ### [15.3.1](https://www.github.com/yargs/yargs/compare/v15.3.0...v15.3.1) (2020-03-16)
 
 

package/LICENSE

@@ -1,7 +1,6 @@
-Copyright 2010 James Halliday (mail@substack.net)
-Modified work Copyright 2014 Contributors (ben@npmjs.com)
+MIT License
 
-This project is free software released under the MIT/X11 license:
+Copyright 2010 James Halliday (mail@substack.net); Modified work Copyright 2014 Contributors (ben@npmjs.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -44,16 +44,16 @@ npm i yargs@next
 
 ### Simple Example
 
-````javascript
+```javascript
 #!/usr/bin/env node
-const argv = require('yargs').argv
+const {argv} = require('yargs')
 
 if (argv.ships > 3 && argv.distance < 53.5) {
   console.log('Plunder more riffiwobbles!')
 } else {
   console.log('Retreat from the xupptumblers!')
 }
-````
+```
 
 ```bash
 $ ./plunder.js --ships=4 --distance=22
@@ -136,5 +136,5 @@ Having problems? want to contribute? join our [community slack](http://devtoolsc
 [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
 [slack-url]: http://devtoolscommunity.herokuapp.com
 [type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs
-[coverage-image]: https://img.shields.io/badge/dynamic/json?color=brightgreen&label=coverage&query=branches&suffix=%25&url=https%3A%2F%2Fraw.githubusercontent.com%2Fyargs%2Fyargs%2Fmaster%2F.nycrc&cacheSeconds=3600
-[coverage-url]: https://github.com/yargs/yargs/blob/master/.nycrc
+[coverage-image]: https://img.shields.io/nycrc/yargs/yargs
+[coverage-url]: https://github.com/yargs/yargs/blob/master/.nycrc

package/build/lib/apply-extends.d.ts

@@ -0,0 +1,2 @@
+import { Dictionary } from './common-types';
+export declare function applyExtends(config: Dictionary, cwd: string, mergeExtends?: boolean): Dictionary;

package/build/lib/apply-extends.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyExtends = void 0;
+const fs = require("fs");
+const path = require("path");
+const yerror_1 = require("./yerror");
+let previouslyVisitedConfigs = [];
+function checkForCircularExtends(cfgPath) {
+    if (previouslyVisitedConfigs.indexOf(cfgPath) > -1) {
+        throw new yerror_1.YError(`Circular extended configurations: '${cfgPath}'.`);
+    }
+}
+function getPathToDefaultConfig(cwd, pathToExtend) {
+    return path.resolve(cwd, pathToExtend);
+}
+function mergeDeep(config1, config2) {
+    const target = {};
+    function isObject(obj) {
+        return obj && typeof obj === 'object' && !Array.isArray(obj);
+    }
+    Object.assign(target, config1);
+    for (const key of Object.keys(config2)) {
+        if (isObject(config2[key]) && isObject(target[key])) {
+            target[key] = mergeDeep(config1[key], config2[key]);
+        }
+        else {
+            target[key] = config2[key];
+        }
+    }
+    return target;
+}
+function applyExtends(config, cwd, mergeExtends = false) {
+    let defaultConfig = {};
+    if (Object.prototype.hasOwnProperty.call(config, 'extends')) {
+        if (typeof config.extends !== 'string')
+            return defaultConfig;
+        const isPath = /\.json|\..*rc$/.test(config.extends);
+        let pathToDefault = null;
+        if (!isPath) {
+            try {
+                pathToDefault = require.resolve(config.extends);
+            }
+            catch (err) {
+                // most likely this simply isn't a module.
+            }
+        }
+        else {
+            pathToDefault = getPathToDefaultConfig(cwd, config.extends);
+        }
+        // maybe the module uses key for some other reason,
+        // err on side of caution.
+        if (!pathToDefault && !isPath)
+            return config;
+        if (!pathToDefault)
+            throw new yerror_1.YError(`Unable to find extended config '${config.extends}' in '${cwd}'.`);
+        checkForCircularExtends(pathToDefault);
+        previouslyVisitedConfigs.push(pathToDefault);
+        defaultConfig = isPath ? JSON.parse(fs.readFileSync(pathToDefault, 'utf8')) : require(config.extends);
+        delete config.extends;
+        defaultConfig = applyExtends(defaultConfig, path.dirname(pathToDefault), mergeExtends);
+    }
+    previouslyVisitedConfigs = [];
+    return mergeExtends ? mergeDeep(defaultConfig, config) : Object.assign({}, defaultConfig, config);
+}
+exports.applyExtends = applyExtends;

package/build/lib/argsert.d.ts

@@ -0,0 +1,2 @@
+export declare function argsert(callerArguments: any[], length?: number): void;
+export declare function argsert(expected: string, callerArguments: any[], length?: number): void;

package/build/lib/argsert.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.argsert = void 0;
+const yerror_1 = require("./yerror");
+const parse_command_1 = require("./parse-command");
+const positionName = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth'];
+function argsert(arg1, arg2, arg3) {
+    function parseArgs() {
+        return typeof arg1 === 'object'
+            ? [{ demanded: [], optional: [] }, arg1, arg2]
+            : [parse_command_1.parseCommand(`cmd ${arg1}`), arg2, arg3];
+    }
+    // TODO: should this eventually raise an exception.
+    try {
+        // preface the argument description with "cmd", so
+        // that we can run it through yargs' command parser.
+        let position = 0;
+        let [parsed, callerArguments, length] = parseArgs();
+        const args = [].slice.call(callerArguments);
+        while (args.length && args[args.length - 1] === undefined)
+            args.pop();
+        length = length || args.length;
+        if (length < parsed.demanded.length) {
+            throw new yerror_1.YError(`Not enough arguments provided. Expected ${parsed.demanded.length} but received ${args.length}.`);
+        }
+        const totalCommands = parsed.demanded.length + parsed.optional.length;
+        if (length > totalCommands) {
+            throw new yerror_1.YError(`Too many arguments provided. Expected max ${totalCommands} but received ${length}.`);
+        }
+        parsed.demanded.forEach((demanded) => {
+            const arg = args.shift();
+            const observedType = guessType(arg);
+            const matchingTypes = demanded.cmd.filter(type => type === observedType || type === '*');
+            if (matchingTypes.length === 0)
+                argumentTypeError(observedType, demanded.cmd, position);
+            position += 1;
+        });
+        parsed.optional.forEach((optional) => {
+            if (args.length === 0)
+                return;
+            const arg = args.shift();
+            const observedType = guessType(arg);
+            const matchingTypes = optional.cmd.filter(type => type === observedType || type === '*');
+            if (matchingTypes.length === 0)
+                argumentTypeError(observedType, optional.cmd, position);
+            position += 1;
+        });
+    }
+    catch (err) {
+        console.warn(err.stack);
+    }
+}
+exports.argsert = argsert;
+function guessType(arg) {
+    if (Array.isArray(arg)) {
+        return 'array';
+    }
+    else if (arg === null) {
+        return 'null';
+    }
+    return typeof arg;
+}
+function argumentTypeError(observedType, allowedTypes, position) {
+    throw new yerror_1.YError(`Invalid ${positionName[position] || 'manyith'} argument. Expected ${allowedTypes.join(' or ')} but received ${observedType}.`);
+}

package/build/lib/command.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="node" />
+import { Dictionary } from './common-types';
+import { Middleware } from './middleware';
+import { Positional } from './parse-command';
+import { RequireDirectoryOptions } from 'require-directory';
+import { UsageInstance } from './usage';
+import { ValidationInstance } from './validation';
+import { YargsInstance, Options, OptionDefinition, Context, Arguments, DetailedArguments } from './yargs';
+export declare function command(yargs: YargsInstance, usage: UsageInstance, validation: ValidationInstance, globalMiddleware?: Middleware[]): CommandInstance;
+/** Instance of the command module. */
+export interface CommandInstance {
+    addDirectory(dir: string, context: Context, req: NodeRequireFunction, callerFile: string, opts?: RequireDirectoryOptions<any>): void;
+    addHandler(handler: CommandHandlerDefinition): void;
+    addHandler(cmd: string | string[], description: CommandHandler['description'], builder?: CommandBuilderDefinition | CommandBuilder, handler?: CommandHandlerCallback, commandMiddleware?: Middleware[], deprecated?: boolean): void;
+    cmdToParseOptions(cmdString: string): Positionals;
+    freeze(): void;
+    getCommandHandlers(): Dictionary<CommandHandler>;
+    getCommands(): string[];
+    hasDefaultCommand(): boolean;
+    reset(): CommandInstance;
+    runCommand(command: string | null, yargs: YargsInstance, parsed: DetailedArguments, commandIndex?: number): Arguments | Promise<Arguments>;
+    runDefaultBuilderOn(yargs: YargsInstance): void;
+    unfreeze(): void;
+}
+export interface CommandHandlerDefinition extends Partial<Pick<CommandHandler, 'deprecated' | 'description' | 'handler' | 'middlewares'>> {
+    aliases?: string[];
+    builder?: CommandBuilder | CommandBuilderDefinition;
+    command?: string | string[];
+    desc?: CommandHandler['description'];
+    describe?: CommandHandler['description'];
+}
+export declare function isCommandHandlerDefinition(cmd: string | string[] | CommandHandlerDefinition): cmd is CommandHandlerDefinition;
+export interface CommandBuilderDefinition {
+    builder?: CommandBuilder;
+    deprecated?: boolean;
+    handler: CommandHandlerCallback;
+    middlewares?: Middleware[];
+}
+export declare function isCommandBuilderDefinition(builder?: CommandBuilder | CommandBuilderDefinition): builder is CommandBuilderDefinition;
+export interface CommandHandlerCallback {
+    (argv: Arguments): any;
+}
+export interface CommandHandler {
+    builder: CommandBuilder;
+    demanded: Positional[];
+    deprecated?: boolean;
+    description?: string | false;
+    handler: CommandHandlerCallback;
+    middlewares: Middleware[];
+    optional: Positional[];
+    original: string;
+}
+export declare type CommandBuilder = CommandBuilderCallback | Dictionary<OptionDefinition>;
+interface CommandBuilderCallback {
+    (y: YargsInstance): YargsInstance | void;
+}
+export declare function isCommandBuilderCallback(builder: CommandBuilder): builder is CommandBuilderCallback;
+interface Positionals extends Pick<Options, 'alias' | 'array' | 'default'> {
+    demand: Dictionary<boolean>;
+}
+export interface FinishCommandHandler {
+    (handlerResult: any): any;
+}
+export {};