Generate help by flag descriptions #140

ybiquitous · 2020-03-22T13:49:33Z

This fixes #80. Rechallenge of PR #82.

Example

  A useful command

  Options:
    --foo <string>

    --output <string>

    --input <string>  (default: stdin)

    -i <number>, --indent <number>  (default: 2)
      Indent level

    --enabled  (default: false)
      Enabled or not

    --lw <string>, --long-word <string>  (default: none)
      Very very long long word.
      This is the second line.

Welcome any feedback!

test.js

sindresorhus · 2020-04-07T05:46:19Z

I don't think helpOptions is a good option name. I think we should just automatically show the text if the help option (or argument) is not specified.

sindresorhus · 2020-04-07T05:46:36Z

Also look at how https://github.com/yargs/yargs solves this and how it presents the output. Also do some research on how other arguments parsers in Python and Ruby handles the config and output.

index.js

test.js

sindresorhus · 2020-04-07T05:47:25Z

There should probably also be a method to get the autogenerated help text in case you want to manually combine it with your own help text.

ybiquitous · 2020-04-09T16:55:07Z

Sorry for my late reply. I will work on your review this weekend.

ybiquitous · 2020-04-12T15:54:01Z

I looked at some command-line helpers and some command-line tools. For example:

As a result, I think the following format is better:

An awesome CLI tool

Usage: foo [options]

Options:
  --input <string>            Input source. [default: stdin]
  -o, --output <string>       Output file to be reported.
  -i, --indent <number>       Indent level. [default: 2]
  --quiet                     Suppress any output.
  --verbose                   Show verbose output.
                              See also --quiet.
  -h, --help                  Show help.

An option's name and description on a line.
First short-flag, last long-flag (all tools except yargs support this order).

What do you think?

sindresorhus · 2020-04-23T08:03:57Z

I agree with everything except the shortflag order. The shortflag should be last.

sindresorhus · 2020-04-23T08:05:05Z

Indent level. [default: 2]

Do any of the libraries put more than one space before [default? It feels a bit cramped into the description.

sindresorhus · 2020-04-23T08:05:15Z

Another good library for inspiration: https://github.com/apple/swift-argument-parser

ybiquitous · 2020-04-23T08:27:00Z

I agree with everything except the shortflag order. The shortflag should be last.

OK, I'll do it. 👍

Do any of the libraries put more than one space before [default? It feels a bit cramped into the description.

I have no strong opinion about it. How many spaces are appropriate?

sindresorhus · 2020-04-23T08:35:15Z

2

test/test.js

ybiquitous · 2020-05-18T05:18:15Z

Sorry for the late response... I've addressed all the review points except for the following one:

There should probably also be a method to get the autogenerated help text in case you want to manually combine it with your own help text.

About the comment above, what kind of API do you expect?

sindresorhus · 2020-05-24T08:48:12Z

generate-help.js

+	return lines;
+}
+
+module.exports = function ({description, help, flags}, pkg) {


Suggested change

module.exports = function ({description, help, flags}, pkg) {

module.exports = ({description, help, flags}, pkg) => {

sindresorhus · 2020-05-24T08:50:34Z

generate-help.js

+
+	lines = lines.map(line => trimNewlines(line));
+
+	const content = lines.join(EOL).replace(/^\t+/gm, '').replace(/[\t ]+[\r\n]*$/gm, '');


Instead of the regexes here, couldn't you use redent?

sindresorhus · 2020-05-24T08:51:00Z

generate-help.js

+
+	const maxNameLengh = Math.max(...entries.map(({name}) => name.length));
+
+	const lines = entries.map(({name, desc}) => {


Don't use abbreviations for variable/parameter names.

sindresorhus · 2020-05-24T08:51:31Z

generate-help.js

+	lines = lines.map(line => trimNewlines(line));
+
+	const content = lines.join(EOL).replace(/^\t+/gm, '').replace(/[\t ]+[\r\n]*$/gm, '');
+	return EOL + trimNewlines(redent(content, 2)) + EOL;


Use \n instead of EOL

sindresorhus · 2020-05-24T08:52:43Z

About the comment above, what kind of API do you expect?

Any suggestions?

ybiquitous · 2020-05-25T14:46:02Z

About the comment above, what kind of API do you expect?

Any suggestions?

For example:

const { generateHelp } = require("meow");
generateHelp({ help: "...", description: "...", flags: {...} }, packageJson);

ybiquitous · 2020-05-25T14:49:09Z

Edited:

const { generateHelp } = require("meow");
generateHelp({ help: "...", description: "...", defaultDescription: "...", flags: {...} });

sindresorhus · 2020-06-06T08:03:56Z

Thinking more about it, maybe instead of a free method, we could make the help option also accept a function, which would receive the full generated help text, generated each section (for example, the rendered help for flags, and other sections), and also the meow options. That should be flexible enough for the user to do anything they want. The function would be expected to return the final help text. Thoughts?

ybiquitous · 2020-06-08T00:31:35Z

Thanks for your advice.

make the help option also accept a function

It seems a better API than my suggestion! 👍
Do you expect the following use case, for example?

const cli = meow({
  help: (wholeText: string, flagsSection: string, description: string, options: meow.Options) => {
    return `...`;
  },
  flags: {
    input: {
      type: 'string',
      description: 'Input file path'
    }
  }
});

sindresorhus · 2020-06-08T05:57:17Z

Yes, but I think it’s better to make help accept a single object as argument instead of lots of arguments. Since many of them will probably not be used.

ybiquitous · 2020-06-08T05:59:49Z

Make sense. I'll try it, thanks!

ybiquitous · 2020-06-10T01:49:54Z

The help option can receive a function via 935911f.

ybiquitous · 2020-06-29T14:19:29Z

I'm ready to be reviewed again.

sindresorhus · 2020-08-10T20:40:26Z

index.d.ts

+	/**
+	Callback function to generate a help text you want.
+	*/
+	type GenerateHelp = (args: Readonly<{wholeText: string; flagLines: readonly string[]; description: string; options: Readonly<Options<AnyFlags>>}>) => string;


The args type should be a separate interface and each property should have a doc-comment.

args should have a better name too.

sindresorhus · 2020-08-10T20:41:26Z

index.d.ts

@@ -27,6 +28,11 @@ declare namespace meow {

 	type AnyFlags = {[key: string]: StringFlag | BooleanFlag | NumberFlag};

+	/**
+	Callback function to generate a help text you want.


This needs to be more verbose. Document the default behavior, etc.

readme.md

sindresorhus · 2020-08-10T20:43:23Z

Some things to keep in mind:

Review your own diff.
Try to refactor and simplify the implementation.
Try to add more tests.
More docs.

sindresorhus · 2020-09-30T12:41:48Z

Bump

ybiquitous · 2020-09-30T13:55:17Z

Sorry for the late response.

Try to refactor and simplify the implementation.

Try to add more tests.

I have no good ideas about the points above. Could you please help me?

sindresorhus · 2020-10-28T22:40:25Z

generate-help.js

@@ -0,0 +1,103 @@
+'use strict';


This file needs to be added to files in package.json.

sindresorhus · 2020-10-28T22:41:18Z

generate-help.js

+function buildFlagLines(flags) {
+	flags = {...flags, help: {type: 'boolean', description: 'Show help'}};
+
+	const entries = Object.entries(decamelizeKeys(flags, '-')).map(([name, def]) => {


Don't use abbreviations (regarding def, and other cases).

sindresorhus · 2020-10-28T22:43:21Z

index.d.ts

+	}
+
+	/**
+	Callback function to customize a help text you want.


sindresorhus · 2020-10-28T22:53:10Z

readme.md


 The input is reindented and starting/ending newlines are trimmed which means you can use a [template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/template_strings) without having to care about using the correct amount of indent.

 The description will be shown above your help text automatically.

+Also, you can customize the auto-generated help text by giving the function as follows:


The readme and index.d.ts should be in sync.

sindresorhus · 2020-10-28T22:53:12Z

Try to refactor and simplify the implementation.

The code is quite hard to follow. Some code comments could maybe help that too. I often comment "simplify" on PRs as honestly most PRs could be simplified. Nobody writes perfect code the first time around. It helps to come back to it and look it over and try to simplify/refactor it. That's what I'm asking.

Try to add more tests.

I'm just asking you to look over and try to add some more tests. I'm the one that will be stuck maintaining this for infinity, so I want to ensure it's as solid as possible.

sindresorhus · 2020-10-28T22:54:15Z

index.d.ts

@@ -28,6 +29,37 @@ declare namespace meow {
 	type AnyFlag = StringFlag | BooleanFlag | NumberFlag;
 	type AnyFlags = {[key: string]: AnyFlag};

+	interface GenerateHelpOptions {
+		/**
+		A whole help text generated by default.


sindresorhus · 2020-10-28T22:54:28Z

index.d.ts

+		description: string;
+
+		/**
+		A list of a line including each flag's name and description.


sindresorhus · 2020-10-28T22:54:45Z

index.d.ts

+		flagLines: readonly string[];
+
+		/**
+		An object including each flag information.


Not clear to the user what "flag information" means.

sindresorhus · 2020-10-28T22:56:00Z

This change needs more docs. There's not even a mention of the new behavior of generating flag docs by default.

armano2 · 2021-02-28T10:41:37Z

as for yargs, this is not fully true as they print in with a little better indentations

example:

@commitlint/cli@11.0.0 - Lint your commit messages

[input] reads from stdin if --edit, --env, --from and --to are omitted

Options:
  -c, --color          toggle colored output           [boolean] [default: true]
  -g, --config         path to the config file                          [string]
      --print-config   print resolved config          [boolean] [default: false]
  -d, --cwd            directory to execute in
                                         [string] [default: (Working Directory)]
      --edit           read last commit message from the specified file or
                       fallbacks to ./.git/COMMIT_EDITMSG               [string]
  -E, --env            check message in the file at path given by environment
                       variable value                                   [string]
  -x, --extends        array of shareable configurations to extend       [array]
  -H, --help-url       help url in error message                        [string]
  -f, --from           lower end of the commit range to lint; applies if
                       edit=false                                       [string]
  -o, --format         output format of the results                     [string]
  -p, --parser-preset  configuration preset to use for
                       conventional-commits-parser                      [string]
  -q, --quiet          toggle console output          [boolean] [default: false]
  -t, --to             upper end of the commit range to lint; applies if
                       edit=false                                       [string]
  -V, --verbose        enable verbose output for reports without problems
                                                                       [boolean]
  -v, --version        display version information                     [boolean]
  -h, --help           Show help                                       [boolean]

ybiquitous · 2021-03-05T16:16:51Z

I am very sorry for my too late response. I can no longer go any further with this PR due to my lack, in spite of many advice I have received. 🙇

I am so grateful for the kind review.
And, I hope this PR will be of some help when someone works on implementing this feature again. ☺️

Thank you.

Generate help by flag descriptions

bfdab34

ybiquitous marked this pull request as ready for review March 22, 2020 13:53

ybiquitous mentioned this pull request Mar 22, 2020

Autogenerate flag help when no helpMessage is given #80

Open

ybiquitous commented Mar 22, 2020

View reviewed changes

test.js Outdated Show resolved Hide resolved

sindresorhus requested changes Apr 7, 2020

View reviewed changes

index.js Outdated Show resolved Hide resolved

test.js Outdated Show resolved Hide resolved

ybiquitous marked this pull request as draft April 12, 2020 15:14

ybiquitous added 5 commits May 8, 2020 02:02

Merge branch 'master' into fix-80

8d788e3

Fix xo issues

5989825

Merge branch 'master' into fix-80

a4cacb0

Extract generate-help.js and fix help text

20ddb4c

Remove unused helpOptions

854419d

ybiquitous commented May 18, 2020

View reviewed changes

test/test.js Show resolved Hide resolved

ybiquitous marked this pull request as ready for review May 18, 2020 05:31

sindresorhus requested changes May 24, 2020

View reviewed changes

Address reviews

8b2c2eb

Improve generateHelp() interface

6893bac

Allow a help function to customize a help text

935911f

sindresorhus requested changes Aug 10, 2020

View reviewed changes

ybiquitous added 2 commits August 22, 2020 22:31

Merge branch 'master' into fix-80

fd33347

Fix npm test

daaecaf

raineorshine mentioned this pull request Sep 23, 2020

Unhandled exception when --target has unexpected value raineorshine/npm-check-updates#735

Closed

3 tasks

ybiquitous added 4 commits September 30, 2020 22:25

Merge branch 'master' into fix-80

8642dc1

Use tab indentation in readme

3081560

More docs and refactor types

dabb139

Remove .log/

a00c07e

sindresorhus requested changes Oct 28, 2020

View reviewed changes

sindresorhus reviewed Oct 28, 2020

View reviewed changes

index.d.ts

description: string;

/**

A list of a line including each flag's name and description.

Copy link

Owner

sindresorhus Oct 28, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo

sindresorhus reviewed Oct 28, 2020

View reviewed changes

Base automatically changed from master to main January 23, 2021 17:36

ybiquitous closed this Mar 5, 2021

	module.exports = function ({description, help, flags}, pkg) {
	module.exports = ({description, help, flags}, pkg) => {


		lines = lines.map(line => trimNewlines(line));

		const content = lines.join(EOL).replace(/^\t+/gm, '').replace(/[\t ]+[\r\n]*$/gm, '');


		const maxNameLengh = Math.max(...entries.map(({name}) => name.length));

		const lines = entries.map(({name, desc}) => {

Generate help by flag descriptions #140

Generate help by flag descriptions #140

Conversation

ybiquitous commented Mar 22, 2020 • edited

Example

sindresorhus commented Apr 7, 2020

sindresorhus commented Apr 7, 2020 • edited

sindresorhus commented Apr 7, 2020

ybiquitous commented Apr 9, 2020

ybiquitous commented Apr 12, 2020 • edited

sindresorhus commented Apr 23, 2020

sindresorhus commented Apr 23, 2020

sindresorhus commented Apr 23, 2020

ybiquitous commented Apr 23, 2020

sindresorhus commented Apr 23, 2020

ybiquitous commented May 18, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sindresorhus commented May 24, 2020

ybiquitous commented May 25, 2020

ybiquitous commented May 25, 2020

sindresorhus commented Jun 6, 2020

ybiquitous commented Jun 8, 2020

sindresorhus commented Jun 8, 2020

ybiquitous commented Jun 8, 2020

ybiquitous commented Jun 10, 2020

ybiquitous commented Jun 29, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sindresorhus commented Aug 10, 2020

sindresorhus commented Sep 30, 2020

ybiquitous commented Sep 30, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sindresorhus commented Oct 28, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sindresorhus commented Oct 28, 2020

armano2 commented Feb 28, 2021

ybiquitous commented Mar 5, 2021

ybiquitous commented Mar 22, 2020 •

edited

sindresorhus commented Apr 7, 2020 •

edited

ybiquitous commented Apr 12, 2020 •

edited