clipanion - npm Package Compare versions

Comparing version 2.0.0-rc.14 to 2.0.0-rc.15

lib/advanced/Cli.d.ts

@@ -12,13 +12,25 @@ /// <reference types="node" />
 };
-export declare class Cli<Context extends BaseContext = BaseContext> {
+export declare type MiniCli<Context extends BaseContext> = {
+    definitions(): Object;
+    error(error: Error, opts?: {
+        command?: Command<Context> | null;
+    }): string;
+    process(input: string[]): Command<Context>;
+    run(input: string[], context?: Partial<Context>): Promise<number>;
+    usage(command?: CommandClass<Context> | Command<Context> | null, opts?: {
+        detailed?: boolean;
+        prefix?: string;
+    }): string;
+};
+export declare class Cli<Context extends BaseContext = BaseContext> implements MiniCli<Context> {
     private readonly builder;
     private readonly registrations;
+    readonly binaryLabel?: string;
     readonly binaryName: string;
     readonly binaryVersion?: string;
-    constructor({ binaryName, binaryVersion }?: {
+    constructor({ binaryLabel, binaryName, binaryVersion }?: {
+        binaryLabel?: string;
         binaryName?: string;
         binaryVersion?: string;
     });
-    getUsageByRegistration(klass: CommandClass<Context>): string;
-    getUsageByIndex(n: number): string;
     register(commandClass: CommandClass<Context>): void;
@@ -28,3 +40,11 @@ process(input: string[]): Command<Context>;
     runExit(input: string[], context: Context): Promise<void>;
-    usage(command: CommandClass<Context> | Command<Context> | null, { detailed, prefix }?: {
+    definitions(): {
+        path: string;
+        usage: string;
+        category: string | undefined;
+        description: string | undefined;
+        details: string | undefined;
+        examples: string[][] | undefined;
+    }[];
+    usage(command?: CommandClass<Context> | Command<Context> | null, { detailed, prefix }?: {
         detailed?: boolean;
@@ -36,13 +56,4 @@ prefix?: string;
     }): string;
+    private getUsageByRegistration;
+    private getUsageByIndex;
 }
-export declare type MiniCli<Context extends BaseContext> = {
-    process(input: string[]): Command<Context>;
-    run(input: string[], context?: Partial<Context>): Promise<number>;
-    error(error: Error, opts?: {
-        command?: Command<Context> | null;
-    }): string;
-    usage(command: CommandClass<Context> | Command<Context> | null, opts?: {
-        detailed?: boolean;
-        prefix?: string;
-    }): string;
-};

lib/advanced/Cli.js

@@ -12,17 +12,9 @@ "use strict";
 class Cli {
-    constructor({ binaryName = `...`, binaryVersion } = {}) {
+    constructor({ binaryLabel, binaryName = `...`, binaryVersion } = {}) {
         this.registrations = new Map();
         this.builder = new core_2.CliBuilder({ binaryName });
+        this.binaryLabel = binaryLabel;
         this.binaryName = binaryName;
         this.binaryVersion = binaryVersion;
     }
-    getUsageByRegistration(klass) {
-        const index = this.registrations.get(klass);
-        if (typeof index === `undefined`)
-            throw new Error(`Assertion failed: Unregistered command`);
-        return this.getUsageByIndex(index);
-    }
-    getUsageByIndex(n) {
-        return this.builder.getBuilderByIndex(n).usage();
-    }
     register(commandClass) {
@@ -75,15 +67,7 @@ const commandBuilder = this.builder.command();
         command.cli = {
-            process: input => {
-                return this.process(input);
-            },
-            run: async (input, subContext) => {
-                const exitCode = await this.run(input, Object.assign({}, context, { subContext }));
-                return typeof exitCode !== `undefined` ? exitCode : 0;
-            },
-            usage: (command, opts) => {
-                return this.usage(command, opts);
-            },
-            error: (error, opts) => {
-                return this.error(error, opts);
-            },
+            definitions: () => this.definitions(),
+            error: (error, opts) => this.error(error, opts),
+            process: input => this.process(input),
+            run: (input, subContext) => this.run(input, Object.assign({}, context, { subContext })),
+            usage: (command, opts) => this.usage(command, opts),
         };
@@ -103,3 +87,26 @@ let exitCode;
     }
-    usage(command, { detailed = false, prefix = `$ ` } = {}) {
+    definitions() {
+        const data = [];
+        for (const [commandClass, number] of this.registrations) {
+            if (typeof commandClass.usage === `undefined`)
+                continue;
+            const path = this.getUsageByIndex(number, { detailed: false });
+            const usage = this.getUsageByIndex(number, { detailed: true });
+            const category = typeof commandClass.usage.category !== `undefined`
+                ? format_1.formatMarkdownish(commandClass.usage.category, false)
+                : undefined;
+            const description = typeof commandClass.usage.description !== `undefined`
+                ? format_1.formatMarkdownish(commandClass.usage.description, false)
+                : undefined;
+            const details = typeof commandClass.usage.details !== `undefined`
+                ? format_1.formatMarkdownish(commandClass.usage.details, true)
+                : undefined;
+            const examples = typeof commandClass.usage.examples !== `undefined`
+                ? commandClass.usage.examples.map(([label, cli]) => [format_1.formatMarkdownish(label, false), format_1.formatMarkdownish(cli, false)])
+                : undefined;
+            data.push({ path, usage, category, description, details, examples });
+        }
+        return data;
+    }
+    usage(command = null, { detailed = false, prefix = `$ ` } = {}) {
         // @ts-ignore
@@ -112,3 +119,2 @@ const commandClass = command !== null && typeof command.getMeta === `undefined`
             const commandsByCategories = new Map();
-            let maxPathLength = 0;
             for (const [commandClass, number] of this.registrations.entries()) {
@@ -133,3 +139,16 @@ if (typeof commandClass.usage === `undefined`)
             });
-            result += `${chalk_1.default.bold(prefix)}${this.binaryName} <command>\n`;
+            const hasLabel = typeof this.binaryLabel !== `undefined`;
+            const hasVersion = typeof this.binaryVersion !== `undefined`;
+            if (hasLabel || hasVersion) {
+                if (hasLabel && hasVersion)
+                    result += `${chalk_1.default.bold(`${this.binaryLabel} - ${this.binaryVersion}`)}\n\n`;
+                else if (hasLabel)
+                    result += `${chalk_1.default.bold(`${this.binaryLabel}`)}\n`;
+                else
+                    result += `${chalk_1.default.bold(`${this.binaryVersion}`)}\n`;
+                result += `  ${chalk_1.default.bold(prefix)}${this.binaryName} <command>\n`;
+            }
+            else {
+                result += `${chalk_1.default.bold(prefix)}${this.binaryName} <command>\n`;
+            }
             for (let categoryName of categoryNames) {
@@ -144,6 +163,5 @@ const commands = commandsByCategories.get(categoryName).slice().sort((a, b) => {
                 result += `${chalk_1.default.bold(`${header}:`)}\n`;
-                result += `\n`;
-                const pad = (str) => `${str}${` `.repeat(maxPathLength - str.length)}`;
                 for (let { commandClass, usage } of commands) {
                     const doc = commandClass.usage.description || `undocumented`;
+                    result += `\n`;
                     result += `  ${chalk_1.default.bold(usage)}\n`;
@@ -153,2 +171,4 @@ result += `    ${format_1.formatMarkdownish(doc, false)}`;
             }
+            result += `\n`;
+            result += format_1.formatMarkdownish(`You can also print more details about any of these commands by calling them after adding the \`-h,--help\` flag right after the command name.`, true);
         }
@@ -211,3 +231,12 @@ else {
     }
+    getUsageByRegistration(klass, opts) {
+        const index = this.registrations.get(klass);
+        if (typeof index === `undefined`)
+            throw new Error(`Assertion failed: Unregistered command`);
+        return this.getUsageByIndex(index, opts);
+    }
+    getUsageByIndex(n, opts) {
+        return this.builder.getBuilderByIndex(n).usage(opts);
+    }
 }
 exports.Cli = Cli;

lib/core.d.ts

@@ -278,3 +278,5 @@ export declare const NODE_INITIAL = 0;
     setContext(context: Context): void;
-    usage(): string;
+    usage({ detailed }?: {
+        detailed?: boolean;
+    }): string;
     compile(): {
@@ -281,0 +283,0 @@ machine: StateMachine;

lib/core.js

@@ -404,23 +404,24 @@ "use strict";
     }
-    usage() {
-        const segments = [
-            this.cliOpts.binaryName,
-        ];
+    usage({ detailed = true } = {}) {
+        const segments = [this.cliOpts.binaryName];
         if (this.paths.length > 0)
             segments.push(...this.paths[0]);
-        for (const { names, arity } of this.options) {
-            const args = [];
-            for (let t = 0; t < arity; ++t)
-                args.push(` #${t}`);
-            segments.push(`[${names.join(`,`)}${args.join(``)}]`);
+        if (detailed) {
+            for (const { names, arity } of this.options) {
+                const args = [];
+                for (let t = 0; t < arity; ++t)
+                    args.push(` #${t}`);
+                segments.push(`[${names.join(`,`)}${args.join(``)}]`);
+            }
+            for (let t = 0; t < this.arity.leading; ++t)
+                segments.push(`<arg>`);
+            if (this.arity.extra === Infinity)
+                segments.push(`...`);
+            else
+                for (let t = 0; t < this.arity.extra; ++t)
+                    segments.push(`[arg]`);
+            for (let t = 0; t < this.arity.trailing; ++t) {
+                segments.push(`<arg>`);
+            }
         }
-        for (let t = 0; t < this.arity.leading; ++t)
-            segments.push(`<arg>`);
-        if (this.arity.extra === Infinity)
-            segments.push(`...`);
-        else
-            for (let t = 0; t < this.arity.extra; ++t)
-                segments.push(`[arg]`);
-        for (let t = 0; t < this.arity.trailing; ++t)
-            segments.push(`<arg>`);
         return segments.join(` `);
@@ -427,0 +428,0 @@ }

package.json

 {
   "name": "clipanion",
-  "version": "2.0.0-rc.14",
+  "version": "2.0.0-rc.15",
   "main": "lib/advanced",
@@ -5,0 +5,0 @@ "license": "MIT",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

67003

increased by3.85%

Lines of code

1614

increased by2.74%

No dependency changes