@clerc/plugin-help 0.0.2 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/dist/index.cjs +120 -10
  2. package/dist/index.d.ts +15 -1
  3. package/dist/index.mjs +117 -11
  4. package/package.json +4 -3
package/dist/index.cjs CHANGED
@@ -3,23 +3,133 @@
3
3
  Object.defineProperty(exports, '__esModule', { value: true });
4
4
 
5
5
  var clerc = require('clerc');
6
+ var pc = require('picocolors');
7
+
8
+ function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
9
+
10
+ var pc__default = /*#__PURE__*/_interopDefaultLegacy(pc);
11
+
12
+ const mustArray = (a) => Array.isArray(a) ? a : [a];
13
+ const gracefulFlagName = (n) => n.length <= 1 ? `-${n}` : `--${n}`;
14
+ function generateNameAndAliasFromCommands(commands) {
15
+ return Object.fromEntries(
16
+ Object.entries(commands).map(([name, command]) => [name, [name, ...mustArray(command.alias || "")].join(", ")])
17
+ );
18
+ }
19
+ function generateFlagNameAndAliasFromCommand(command) {
20
+ return Object.fromEntries(
21
+ Object.entries(command.flags || {}).map(([name, flag]) => [name, [name, ...mustArray(flag.alias || "")].map(gracefulFlagName).join(", ")])
22
+ );
23
+ }
24
+ function getPadLength(strings) {
25
+ const maxLength = Math.max(...strings.map((n) => n.length));
26
+ return Math.floor((maxLength + 4) / 4) * 4;
27
+ }
6
28
 
7
29
  const newline = () => {
8
- console.log("\n");
30
+ console.log();
9
31
  };
10
- const helpPlugin = clerc.definePlugin({
32
+ const defaultOptions = {
33
+ command: true,
34
+ examples: [],
35
+ notes: []
36
+ };
37
+ const helpPlugin = (_options) => clerc.definePlugin({
11
38
  setup(cli) {
12
- return cli.command("help", "Show help").on("help", (_ctx) => {
13
- console.log(cli._description);
14
- newline();
15
- console.log("Usage: %s [OPTIONS] [NAME] [COMMAND]", cli._name);
16
- newline();
17
- console.log("Commands:");
18
- for (const command of Object.values(cli._commands)) {
19
- console.log(" %s %s", command.name, command.description);
39
+ const { command, ...rest } = { ...defaultOptions, ..._options };
40
+ if (command) {
41
+ cli = cli.command("help", "Show help").on("help", (ctx) => {
42
+ showHelp(cli, ctx, rest);
43
+ });
44
+ }
45
+ cli = cli.inspector((_ctx, next) => {
46
+ const ctx = _ctx;
47
+ if (ctx.flags.h || ctx.flags.help) {
48
+ if (ctx.name === "help") {
49
+ showSubcommandHelp(cli, {
50
+ ...ctx,
51
+ name: "help"
52
+ });
53
+ return;
54
+ }
55
+ if (ctx.resolved) {
56
+ showSubcommandHelp(cli, ctx);
57
+ } else {
58
+ showHelp(cli, ctx, rest);
59
+ }
60
+ return;
20
61
  }
62
+ next();
21
63
  });
64
+ return cli;
22
65
  }
23
66
  });
67
+ function showHelp(cli, ctx, { examples, notes }) {
68
+ if (ctx.parameters.length > 0) {
69
+ showSubcommandHelp(cli, ctx);
70
+ return;
71
+ }
72
+ cli._name && console.log(`${pc__default["default"].green(cli._name)} ${cli._version}`);
73
+ if (cli._description) {
74
+ console.log(cli._description);
75
+ newline();
76
+ }
77
+ console.log(pc__default["default"].yellow("USAGE:"));
78
+ console.log(` ${cli._name} <SUBCOMMAND> [OPTIONS]`);
79
+ newline();
80
+ console.log(pc__default["default"].yellow("COMMANDS:"));
81
+ const commandNameAndAlias = generateNameAndAliasFromCommands(cli._commands);
82
+ const commandsPadLength = getPadLength(Object.values(commandNameAndAlias));
83
+ for (const [name, nameAndAlias] of Object.entries(commandNameAndAlias)) {
84
+ console.log(` ${pc__default["default"].green(nameAndAlias.padEnd(commandsPadLength))}${cli._commands[name].description}`);
85
+ }
86
+ if (examples.length > 0) {
87
+ newline();
88
+ console.log(pc__default["default"].yellow("EXAMPLES:"));
89
+ const examplesPadLength = getPadLength(examples.map((e) => e[0]));
90
+ for (const [exampleCommand, exampleDescription] of examples) {
91
+ console.log(` ${exampleCommand.padEnd(examplesPadLength)}${exampleDescription}`);
92
+ }
93
+ }
94
+ if (notes.length > 0) {
95
+ newline();
96
+ console.log(pc__default["default"].yellow("NOTES:"));
97
+ for (const note of notes) {
98
+ console.log(` ${note}`);
99
+ }
100
+ }
101
+ }
102
+ function showSubcommandHelp(cli, ctx) {
103
+ const commandName = String(ctx.name || ctx.parameters[0]);
104
+ const commandToShowHelp = clerc.resolveCommand(cli._commands, commandName);
105
+ if (!commandToShowHelp) {
106
+ throw new clerc.NoSuchCommandsError(`No such command: ${commandName}`);
107
+ }
108
+ console.log(`${pc__default["default"].green(`${cli._name} ${commandToShowHelp.name}`)} ${cli._version}`);
109
+ commandToShowHelp.description && console.log(commandToShowHelp.description);
110
+ newline();
111
+ console.log(pc__default["default"].yellow("USAGE:"));
112
+ console.log(` ${cli._name} ${commandToShowHelp.name} [PARAMETERS] [FLAGS]`);
113
+ const parameters = commandToShowHelp.parameters || {};
114
+ const parameterKeys = Object.keys(parameters);
115
+ if (parameterKeys.length > 0) {
116
+ newline();
117
+ console.log(pc__default["default"].yellow("PARAMETERS:"));
118
+ const parametersPadLength = getPadLength(parameterKeys);
119
+ for (const [name, param] of Object.entries(parameters)) {
120
+ const resuired = param.required ? pc__default["default"].red(" (required)") : "";
121
+ console.log(` ${pc__default["default"].green(name.padEnd(parametersPadLength))}${param.description}${resuired}`);
122
+ }
123
+ }
124
+ const flagNameAndAlias = generateFlagNameAndAliasFromCommand(commandToShowHelp);
125
+ if (Object.keys(flagNameAndAlias).length > 0) {
126
+ newline();
127
+ console.log(pc__default["default"].yellow("FLAGS:"));
128
+ const flagsPadLength = getPadLength(Object.values(flagNameAndAlias));
129
+ for (const [name, nameAndAlias] of Object.entries(flagNameAndAlias)) {
130
+ console.log(` ${pc__default["default"].green(nameAndAlias.padEnd(flagsPadLength))}${commandToShowHelp.flags[name].description}`);
131
+ }
132
+ }
133
+ }
24
134
 
25
135
  exports.helpPlugin = helpPlugin;
package/dist/index.d.ts CHANGED
@@ -1,6 +1,20 @@
1
1
  import * as clerc from 'clerc';
2
2
  import { Clerc } from 'clerc';
3
3
 
4
- declare const helpPlugin: clerc.Plugin<Clerc<{}>, Clerc<{}>>;
4
+ interface Options {
5
+ /**
6
+ * Register a help command or not.
7
+ */
8
+ command?: boolean;
9
+ /**
10
+ * [example command, description]
11
+ */
12
+ examples?: [string, string][];
13
+ /**
14
+ * notes
15
+ */
16
+ notes?: string[];
17
+ }
18
+ declare const helpPlugin: (_options?: Options) => clerc.Plugin<Clerc<{}>, Clerc<{}>>;
5
19
 
6
20
  export { helpPlugin };
package/dist/index.mjs CHANGED
@@ -1,21 +1,127 @@
1
- import { definePlugin } from 'clerc';
1
+ import { definePlugin, resolveCommand, NoSuchCommandsError } from 'clerc';
2
+ import pc from 'picocolors';
3
+
4
+ const mustArray = (a) => Array.isArray(a) ? a : [a];
5
+ const gracefulFlagName = (n) => n.length <= 1 ? `-${n}` : `--${n}`;
6
+ function generateNameAndAliasFromCommands(commands) {
7
+ return Object.fromEntries(
8
+ Object.entries(commands).map(([name, command]) => [name, [name, ...mustArray(command.alias || "")].join(", ")])
9
+ );
10
+ }
11
+ function generateFlagNameAndAliasFromCommand(command) {
12
+ return Object.fromEntries(
13
+ Object.entries(command.flags || {}).map(([name, flag]) => [name, [name, ...mustArray(flag.alias || "")].map(gracefulFlagName).join(", ")])
14
+ );
15
+ }
16
+ function getPadLength(strings) {
17
+ const maxLength = Math.max(...strings.map((n) => n.length));
18
+ return Math.floor((maxLength + 4) / 4) * 4;
19
+ }
2
20
 
3
21
  const newline = () => {
4
- console.log("\n");
22
+ console.log();
23
+ };
24
+ const defaultOptions = {
25
+ command: true,
26
+ examples: [],
27
+ notes: []
5
28
  };
6
- const helpPlugin = definePlugin({
29
+ const helpPlugin = (_options) => definePlugin({
7
30
  setup(cli) {
8
- return cli.command("help", "Show help").on("help", (_ctx) => {
9
- console.log(cli._description);
10
- newline();
11
- console.log("Usage: %s [OPTIONS] [NAME] [COMMAND]", cli._name);
12
- newline();
13
- console.log("Commands:");
14
- for (const command of Object.values(cli._commands)) {
15
- console.log(" %s %s", command.name, command.description);
31
+ const { command, ...rest } = { ...defaultOptions, ..._options };
32
+ if (command) {
33
+ cli = cli.command("help", "Show help").on("help", (ctx) => {
34
+ showHelp(cli, ctx, rest);
35
+ });
36
+ }
37
+ cli = cli.inspector((_ctx, next) => {
38
+ const ctx = _ctx;
39
+ if (ctx.flags.h || ctx.flags.help) {
40
+ if (ctx.name === "help") {
41
+ showSubcommandHelp(cli, {
42
+ ...ctx,
43
+ name: "help"
44
+ });
45
+ return;
46
+ }
47
+ if (ctx.resolved) {
48
+ showSubcommandHelp(cli, ctx);
49
+ } else {
50
+ showHelp(cli, ctx, rest);
51
+ }
52
+ return;
16
53
  }
54
+ next();
17
55
  });
56
+ return cli;
18
57
  }
19
58
  });
59
+ function showHelp(cli, ctx, { examples, notes }) {
60
+ if (ctx.parameters.length > 0) {
61
+ showSubcommandHelp(cli, ctx);
62
+ return;
63
+ }
64
+ cli._name && console.log(`${pc.green(cli._name)} ${cli._version}`);
65
+ if (cli._description) {
66
+ console.log(cli._description);
67
+ newline();
68
+ }
69
+ console.log(pc.yellow("USAGE:"));
70
+ console.log(` ${cli._name} <SUBCOMMAND> [OPTIONS]`);
71
+ newline();
72
+ console.log(pc.yellow("COMMANDS:"));
73
+ const commandNameAndAlias = generateNameAndAliasFromCommands(cli._commands);
74
+ const commandsPadLength = getPadLength(Object.values(commandNameAndAlias));
75
+ for (const [name, nameAndAlias] of Object.entries(commandNameAndAlias)) {
76
+ console.log(` ${pc.green(nameAndAlias.padEnd(commandsPadLength))}${cli._commands[name].description}`);
77
+ }
78
+ if (examples.length > 0) {
79
+ newline();
80
+ console.log(pc.yellow("EXAMPLES:"));
81
+ const examplesPadLength = getPadLength(examples.map((e) => e[0]));
82
+ for (const [exampleCommand, exampleDescription] of examples) {
83
+ console.log(` ${exampleCommand.padEnd(examplesPadLength)}${exampleDescription}`);
84
+ }
85
+ }
86
+ if (notes.length > 0) {
87
+ newline();
88
+ console.log(pc.yellow("NOTES:"));
89
+ for (const note of notes) {
90
+ console.log(` ${note}`);
91
+ }
92
+ }
93
+ }
94
+ function showSubcommandHelp(cli, ctx) {
95
+ const commandName = String(ctx.name || ctx.parameters[0]);
96
+ const commandToShowHelp = resolveCommand(cli._commands, commandName);
97
+ if (!commandToShowHelp) {
98
+ throw new NoSuchCommandsError(`No such command: ${commandName}`);
99
+ }
100
+ console.log(`${pc.green(`${cli._name} ${commandToShowHelp.name}`)} ${cli._version}`);
101
+ commandToShowHelp.description && console.log(commandToShowHelp.description);
102
+ newline();
103
+ console.log(pc.yellow("USAGE:"));
104
+ console.log(` ${cli._name} ${commandToShowHelp.name} [PARAMETERS] [FLAGS]`);
105
+ const parameters = commandToShowHelp.parameters || {};
106
+ const parameterKeys = Object.keys(parameters);
107
+ if (parameterKeys.length > 0) {
108
+ newline();
109
+ console.log(pc.yellow("PARAMETERS:"));
110
+ const parametersPadLength = getPadLength(parameterKeys);
111
+ for (const [name, param] of Object.entries(parameters)) {
112
+ const resuired = param.required ? pc.red(" (required)") : "";
113
+ console.log(` ${pc.green(name.padEnd(parametersPadLength))}${param.description}${resuired}`);
114
+ }
115
+ }
116
+ const flagNameAndAlias = generateFlagNameAndAliasFromCommand(commandToShowHelp);
117
+ if (Object.keys(flagNameAndAlias).length > 0) {
118
+ newline();
119
+ console.log(pc.yellow("FLAGS:"));
120
+ const flagsPadLength = getPadLength(Object.values(flagNameAndAlias));
121
+ for (const [name, nameAndAlias] of Object.entries(flagNameAndAlias)) {
122
+ console.log(` ${pc.green(nameAndAlias.padEnd(flagsPadLength))}${commandToShowHelp.flags[name].description}`);
123
+ }
124
+ }
125
+ }
20
126
 
21
127
  export { helpPlugin };
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@clerc/plugin-help",
3
- "version": "0.0.2",
3
+ "version": "0.1.0",
4
4
  "author": "Ray <nn_201312@163.com> (https://github.com/so1ve)",
5
- "description": "Clerc",
5
+ "description": "Clerc plugin help",
6
6
  "keywords": [
7
7
  "cli",
8
8
  "clerc",
@@ -40,7 +40,8 @@
40
40
  "access": "public"
41
41
  },
42
42
  "dependencies": {
43
- "clerc": "0.0.2"
43
+ "clerc": "0.1.0",
44
+ "picocolors": "^1.0.0"
44
45
  },
45
46
  "scripts": {
46
47
  "build": "puild",