@clerc/plugin-help 0.3.4 → 0.5.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 +37 -19
  2. package/dist/index.d.ts +2 -1
  3. package/dist/index.mjs +33 -15
  4. package/package.json +3 -3
package/dist/index.cjs CHANGED
@@ -3,18 +3,16 @@
3
3
  Object.defineProperty(exports, '__esModule', { value: true });
4
4
 
5
5
  var clerc = require('clerc');
6
+ var utils = require('@clerc/utils');
6
7
  var pc = require('picocolors');
7
8
 
8
9
  function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
9
10
 
10
11
  var pc__default = /*#__PURE__*/_interopDefaultLegacy(pc);
11
12
 
12
- const mustArray = (a) => Array.isArray(a) ? a : [a];
13
- const gracefulFlagName = (n) => n.length <= 1 ? `-${n}` : `--${n}`;
14
- const gracefulVersion = (v) => v.startsWith("v") ? v : `v${v}`;
15
13
  function generateNameAndAliasFromCommands(commands) {
16
14
  return Object.fromEntries(
17
- Object.entries(commands).map(([name, command]) => [name, [name, ...command.alias ? mustArray(command.alias) : []].join(", ")])
15
+ Object.entries(commands).map(([name, command]) => [name, [name, ...command.alias ? utils.mustArray(command.alias) : []].join(", ")])
18
16
  );
19
17
  }
20
18
  function generateFlagNameAndAliasFromCommand(command) {
@@ -23,9 +21,9 @@ function generateFlagNameAndAliasFromCommand(command) {
23
21
  ([name, flag]) => {
24
22
  const nameAndAlias = [name];
25
23
  if (flag.alias) {
26
- nameAndAlias.push(...mustArray(flag.alias));
24
+ nameAndAlias.push(...utils.mustArray(flag.alias));
27
25
  }
28
- return [name, nameAndAlias.map(gracefulFlagName).join(", ")];
26
+ return [name, nameAndAlias.map(utils.gracefulFlagName).join(", ")];
29
27
  }
30
28
  )
31
29
  );
@@ -39,6 +37,11 @@ const mergeFlags = (ctx) => ({ ...ctx.flags, ...ctx.unknownFlags });
39
37
  const newline = () => {
40
38
  console.log();
41
39
  };
40
+ const getExamples = (cli) => [
41
+ [`${cli._name} help`, "Displays help of the cli"],
42
+ [`${cli._name} -h`, "Displays help of the cli"],
43
+ [`${cli._name} help help`, "Displays help of the help command"]
44
+ ];
42
45
  const defaultOptions = {
43
46
  command: true,
44
47
  examples: [],
@@ -49,11 +52,12 @@ const helpPlugin = (_options) => clerc.definePlugin({
49
52
  const { command, ...rest } = { ...defaultOptions, ..._options };
50
53
  cli.inspector((inspectorCtx, next) => {
51
54
  if (command && !inspectorCtx.isSingleCommand) {
52
- cli.command("help", "Show help").on("help", (ctx2) => {
55
+ cli = cli.command("help", "Show help", {
56
+ examples: getExamples(cli)
57
+ }).on("help", (ctx2) => {
53
58
  showHelp(ctx2, rest);
54
59
  });
55
60
  }
56
- next();
57
61
  const ctx = inspectorCtx;
58
62
  const flags = mergeFlags(ctx);
59
63
  if (flags.h || flags.help) {
@@ -62,10 +66,7 @@ const helpPlugin = (_options) => clerc.definePlugin({
62
66
  return;
63
67
  }
64
68
  if (ctx.name === "help") {
65
- showSubcommandHelp({
66
- ...ctx,
67
- name: "help"
68
- });
69
+ showSubcommandHelp(ctx);
69
70
  return;
70
71
  }
71
72
  if (ctx.resolved) {
@@ -90,7 +91,7 @@ function showHelp(ctx, { examples, notes }) {
90
91
  showSubcommandHelp(ctx);
91
92
  return;
92
93
  }
93
- cli._name && console.log(`${pc__default["default"].green(cli._name)} ${gracefulVersion(cli._version)}`);
94
+ cli._name && console.log(`${pc__default["default"].green(cli._name)} ${utils.gracefulVersion(cli._version)}`);
94
95
  if (cli._description) {
95
96
  console.log(cli._description);
96
97
  newline();
@@ -99,7 +100,7 @@ function showHelp(ctx, { examples, notes }) {
99
100
  console.log(` ${cli._name || "<CLI NAME>"} <SUBCOMMAND> [OPTIONS]`);
100
101
  newline();
101
102
  console.log(pc__default["default"].yellow("COMMANDS:"));
102
- const commandNameAndAlias = generateNameAndAliasFromCommands(cli._commands);
103
+ const commandNameAndAlias = generateNameAndAliasFromCommands(utils.generateCommandRecordFromCommandArray(clerc.resolveRootCommands(cli._commands)));
103
104
  const commandsPadLength = getPadLength(Object.values(commandNameAndAlias));
104
105
  for (const [name, nameAndAlias] of Object.entries(commandNameAndAlias)) {
105
106
  console.log(` ${pc__default["default"].green(nameAndAlias.padEnd(commandsPadLength))}${cli._commands[name].description}`);
@@ -112,7 +113,20 @@ function showHelp(ctx, { examples, notes }) {
112
113
  console.log(` ${exampleCommand.padEnd(examplesPadLength)}${exampleDescription}`);
113
114
  }
114
115
  }
115
- if (notes.length > 0) {
116
+ showCommandNotes(notes);
117
+ }
118
+ function showCommandExamples(examples) {
119
+ if (examples && examples.length > 0) {
120
+ newline();
121
+ console.log(pc__default["default"].yellow("EXAMPLES:"));
122
+ const examplesPadLength = getPadLength(examples.map((e) => e[0]));
123
+ for (const [exampleCommand, exampleDescription] of examples) {
124
+ console.log(` ${exampleCommand.padEnd(examplesPadLength)}${exampleDescription}`);
125
+ }
126
+ }
127
+ }
128
+ function showCommandNotes(notes) {
129
+ if (notes && notes.length > 0) {
116
130
  newline();
117
131
  console.log(pc__default["default"].yellow("NOTES:"));
118
132
  for (const note of notes) {
@@ -122,12 +136,12 @@ function showHelp(ctx, { examples, notes }) {
122
136
  }
123
137
  function showSubcommandHelp(ctx) {
124
138
  const { cli } = ctx;
125
- const commandName = String(ctx.name || ctx.parameters[0]);
139
+ const commandName = ctx.parameters.map(String);
126
140
  const commandToShowHelp = clerc.resolveCommand(cli._commands, commandName);
127
141
  if (!commandToShowHelp) {
128
- throw new clerc.NoSuchCommandError(`No such command: ${commandName}`);
142
+ throw new clerc.NoSuchCommandError(commandName.join(" "));
129
143
  }
130
- console.log(`${pc__default["default"].green(`${cli._name}.${commandToShowHelp.name}`)} ${gracefulVersion(cli._version)}`);
144
+ console.log(`${pc__default["default"].green(`${cli._name} ${commandToShowHelp.name}`)} ${utils.gracefulVersion(cli._version)}`);
131
145
  commandToShowHelp.description && console.log(commandToShowHelp.description);
132
146
  newline();
133
147
  console.log(pc__default["default"].yellow("USAGE:"));
@@ -141,11 +155,13 @@ function showSubcommandHelp(ctx) {
141
155
  console.log(` ${pc__default["default"].green(nameAndAlias.padEnd(flagsPadLength))}${commandToShowHelp.flags[name].description}`);
142
156
  }
143
157
  }
158
+ showCommandExamples(commandToShowHelp.examples);
159
+ showCommandNotes(commandToShowHelp.notes);
144
160
  }
145
161
  function showSingleCommandHelp(ctx) {
146
162
  const { cli } = ctx;
147
163
  const singleCommand = cli._commands[clerc.SingleCommand];
148
- console.log(`${pc__default["default"].green(`${cli._name} ${gracefulVersion(cli._version)}`)}`);
164
+ console.log(`${pc__default["default"].green(`${cli._name} ${utils.gracefulVersion(cli._version)}`)}`);
149
165
  singleCommand.description && console.log(singleCommand.description);
150
166
  newline();
151
167
  console.log(pc__default["default"].yellow("USAGE:"));
@@ -159,6 +175,8 @@ function showSingleCommandHelp(ctx) {
159
175
  console.log(` ${pc__default["default"].green(nameAndAlias.padEnd(flagsPadLength))}${singleCommand.flags[name].description}`);
160
176
  }
161
177
  }
178
+ showCommandExamples(singleCommand.examples);
179
+ showCommandNotes(singleCommand.notes);
162
180
  }
163
181
 
164
182
  exports.helpPlugin = helpPlugin;
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import * as clerc from 'clerc';
2
+ import { Clerc } from 'clerc';
2
3
 
3
4
  interface Options {
4
5
  /**
@@ -15,6 +16,6 @@ interface Options {
15
16
  */
16
17
  notes?: string[];
17
18
  }
18
- declare const helpPlugin: (_options?: Options) => clerc.Plugin<clerc.Clerc<{}>, clerc.Clerc<{}>>;
19
+ declare const helpPlugin: (_options?: Options) => clerc.Plugin<Clerc<{}>, Clerc<{}>>;
19
20
 
20
21
  export { helpPlugin };
package/dist/index.mjs CHANGED
@@ -1,9 +1,7 @@
1
- import { definePlugin, resolveCommand, NoSuchCommandError, SingleCommand } from 'clerc';
1
+ import { definePlugin, resolveRootCommands, resolveCommand, NoSuchCommandError, SingleCommand } from 'clerc';
2
+ import { mustArray, gracefulFlagName, gracefulVersion, generateCommandRecordFromCommandArray } from '@clerc/utils';
2
3
  import pc from 'picocolors';
3
4
 
4
- const mustArray = (a) => Array.isArray(a) ? a : [a];
5
- const gracefulFlagName = (n) => n.length <= 1 ? `-${n}` : `--${n}`;
6
- const gracefulVersion = (v) => v.startsWith("v") ? v : `v${v}`;
7
5
  function generateNameAndAliasFromCommands(commands) {
8
6
  return Object.fromEntries(
9
7
  Object.entries(commands).map(([name, command]) => [name, [name, ...command.alias ? mustArray(command.alias) : []].join(", ")])
@@ -31,6 +29,11 @@ const mergeFlags = (ctx) => ({ ...ctx.flags, ...ctx.unknownFlags });
31
29
  const newline = () => {
32
30
  console.log();
33
31
  };
32
+ const getExamples = (cli) => [
33
+ [`${cli._name} help`, "Displays help of the cli"],
34
+ [`${cli._name} -h`, "Displays help of the cli"],
35
+ [`${cli._name} help help`, "Displays help of the help command"]
36
+ ];
34
37
  const defaultOptions = {
35
38
  command: true,
36
39
  examples: [],
@@ -41,11 +44,12 @@ const helpPlugin = (_options) => definePlugin({
41
44
  const { command, ...rest } = { ...defaultOptions, ..._options };
42
45
  cli.inspector((inspectorCtx, next) => {
43
46
  if (command && !inspectorCtx.isSingleCommand) {
44
- cli.command("help", "Show help").on("help", (ctx2) => {
47
+ cli = cli.command("help", "Show help", {
48
+ examples: getExamples(cli)
49
+ }).on("help", (ctx2) => {
45
50
  showHelp(ctx2, rest);
46
51
  });
47
52
  }
48
- next();
49
53
  const ctx = inspectorCtx;
50
54
  const flags = mergeFlags(ctx);
51
55
  if (flags.h || flags.help) {
@@ -54,10 +58,7 @@ const helpPlugin = (_options) => definePlugin({
54
58
  return;
55
59
  }
56
60
  if (ctx.name === "help") {
57
- showSubcommandHelp({
58
- ...ctx,
59
- name: "help"
60
- });
61
+ showSubcommandHelp(ctx);
61
62
  return;
62
63
  }
63
64
  if (ctx.resolved) {
@@ -91,7 +92,7 @@ function showHelp(ctx, { examples, notes }) {
91
92
  console.log(` ${cli._name || "<CLI NAME>"} <SUBCOMMAND> [OPTIONS]`);
92
93
  newline();
93
94
  console.log(pc.yellow("COMMANDS:"));
94
- const commandNameAndAlias = generateNameAndAliasFromCommands(cli._commands);
95
+ const commandNameAndAlias = generateNameAndAliasFromCommands(generateCommandRecordFromCommandArray(resolveRootCommands(cli._commands)));
95
96
  const commandsPadLength = getPadLength(Object.values(commandNameAndAlias));
96
97
  for (const [name, nameAndAlias] of Object.entries(commandNameAndAlias)) {
97
98
  console.log(` ${pc.green(nameAndAlias.padEnd(commandsPadLength))}${cli._commands[name].description}`);
@@ -104,7 +105,20 @@ function showHelp(ctx, { examples, notes }) {
104
105
  console.log(` ${exampleCommand.padEnd(examplesPadLength)}${exampleDescription}`);
105
106
  }
106
107
  }
107
- if (notes.length > 0) {
108
+ showCommandNotes(notes);
109
+ }
110
+ function showCommandExamples(examples) {
111
+ if (examples && examples.length > 0) {
112
+ newline();
113
+ console.log(pc.yellow("EXAMPLES:"));
114
+ const examplesPadLength = getPadLength(examples.map((e) => e[0]));
115
+ for (const [exampleCommand, exampleDescription] of examples) {
116
+ console.log(` ${exampleCommand.padEnd(examplesPadLength)}${exampleDescription}`);
117
+ }
118
+ }
119
+ }
120
+ function showCommandNotes(notes) {
121
+ if (notes && notes.length > 0) {
108
122
  newline();
109
123
  console.log(pc.yellow("NOTES:"));
110
124
  for (const note of notes) {
@@ -114,12 +128,12 @@ function showHelp(ctx, { examples, notes }) {
114
128
  }
115
129
  function showSubcommandHelp(ctx) {
116
130
  const { cli } = ctx;
117
- const commandName = String(ctx.name || ctx.parameters[0]);
131
+ const commandName = ctx.parameters.map(String);
118
132
  const commandToShowHelp = resolveCommand(cli._commands, commandName);
119
133
  if (!commandToShowHelp) {
120
- throw new NoSuchCommandError(`No such command: ${commandName}`);
134
+ throw new NoSuchCommandError(commandName.join(" "));
121
135
  }
122
- console.log(`${pc.green(`${cli._name}.${commandToShowHelp.name}`)} ${gracefulVersion(cli._version)}`);
136
+ console.log(`${pc.green(`${cli._name} ${commandToShowHelp.name}`)} ${gracefulVersion(cli._version)}`);
123
137
  commandToShowHelp.description && console.log(commandToShowHelp.description);
124
138
  newline();
125
139
  console.log(pc.yellow("USAGE:"));
@@ -133,6 +147,8 @@ function showSubcommandHelp(ctx) {
133
147
  console.log(` ${pc.green(nameAndAlias.padEnd(flagsPadLength))}${commandToShowHelp.flags[name].description}`);
134
148
  }
135
149
  }
150
+ showCommandExamples(commandToShowHelp.examples);
151
+ showCommandNotes(commandToShowHelp.notes);
136
152
  }
137
153
  function showSingleCommandHelp(ctx) {
138
154
  const { cli } = ctx;
@@ -151,6 +167,8 @@ function showSingleCommandHelp(ctx) {
151
167
  console.log(` ${pc.green(nameAndAlias.padEnd(flagsPadLength))}${singleCommand.flags[name].description}`);
152
168
  }
153
169
  }
170
+ showCommandExamples(singleCommand.examples);
171
+ showCommandNotes(singleCommand.notes);
154
172
  }
155
173
 
156
174
  export { helpPlugin };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clerc/plugin-help",
3
- "version": "0.3.4",
3
+ "version": "0.5.0",
4
4
  "author": "Ray <nn_201312@163.com> (https://github.com/so1ve)",
5
5
  "description": "Clerc plugin help",
6
6
  "keywords": [
@@ -43,8 +43,8 @@
43
43
  "clerc": "*"
44
44
  },
45
45
  "dependencies": {
46
- "@clerc/utils": "0.3.4",
47
- "clerc": "0.3.4",
46
+ "@clerc/utils": "0.5.0",
47
+ "clerc": "0.5.0",
48
48
  "picocolors": "^1.0.0"
49
49
  },
50
50
  "scripts": {