Improvements for extending & help template overwriting

[cravler]

Example

const { Command } = require('./index');
const nunjucks = require('nunjucks');

nunjucks.configure({ autoescape: false });

class MyCommand extends Command {
  createCommand(name) {
    return new this.constructor(name);
  };

  helpInformation() {
    const help = this.helpData({ baseIndent: 2 });

    const res = nunjucks.renderString(`
>>> Usage:

  {{ usage }}
{% if description %}
{{ description }}
{% endif %}
{%- if args | length %}
>>> Arguments:

{{ args | join("\n") }}
{% endif -%}
{%- if options | length %}
>>> Options:

{{ options | join("\n") }}
{% endif -%}
{%- if commands | length %}
>>> Commands:

{{ commands | join("\n") }}
{% endif -%}
`, help);

    return res.replace(/^/gm, '  ').trimEnd() + '\n\n';
  };
}

const program = new MyCommand('example');

program.version('0.0.1');

program
  .command('test <cmd> [env] [val]')
  .description(Array(100).join('long description '), {
    cmd: 'cmd description',
    env: 'env description',
    val: Array(50).join('val description ')
  })
  .action(function(cmd, env, options){});

program.parse(process.argv);

[shadowspawn]

I see issues about people wanting to disable the built-in help, but not issues about what people are replacing it with, or requests to make more support routines public to let people build their own. We might get more interest if #1296 lands and it is easier to override the help.

The code uses arrays of strings internally to build up the help in an efficient and convenient way. I don't think that is a very natural form to return to the user for building custom help though. Some different ideas for what to expose could be:

• the text blocks, say because I just want to rearrange the order or customise the headings (i.e. rather than return an array of strings, return a single string)
• array of visible options including help option for custom processing
• array of visible commands including help command for custom processing

The help code is a bit of a historical mess! I do like that you have tidied it up while making the changes.

[cravler]

With my changes I can do something like this:

but with #1296 I do not see this ability

[shadowspawn]

Nice example of fancy help! Thanks.

#1296 just provides hooks for before and after and overriding the built-in help, it does not provide any assistance doing the fancy help.

[cravler]

May be instead of:

function padDetails(value, description) {
  if (description) {
    return [pad(value, width), optionalWrap(description, descriptionWidth, width + separatorWidth)];
  }
  return [value];
};

you prefer:

const utils = {
  pad: val => pad(val, width),
  wrap: val => optionalWrap(val, descriptionWidth, width + separatorWidth)
};

const renderDetails = params.renderDetails || ((value, description, utils) => {
  const data = description ? [utils.pad(value), utils.wrap(description)] : [value];
  return data.join(separatorStr).replace(/^/gm, valueIndentStr);
});

function prepareDetails(value, description) {
  return renderDetails(value, description, utils);
};

[shadowspawn]

The code uses arrays of strings internally to build up the help in an efficient and convenient way. I don't think that is a very natural form to return to the user for building custom help though.

I see running the code and dumping helpData() that options and commands are not just an array of the strings, but an array of [entry, description]. That is closer to what I had in mind as building blocks.

[cravler]

pushed the changes, now helpData() response:

{
  usage: 'string',
  description: 'string',
  args: ['string'],
  options: ['string'],
  commands: ['string']
}

[shadowspawn]

I am wondering about what approach to take. This is just an idea.

There is already access to some of the content that is displayed in the help. There is .usage() and .description() and option.flags. Much of the help code is just joining the parts together with headings.

There are a few pieces of logic that are buried in code. e.g.

const help = this.options.map((option) => {
  const fullDesc = option.description +
    ((!option.negate && option.defaultValue !== undefined) ? ' (default: ' + JSON.stringify(option.defaultValue) + ')' : '');
  return padOptionDetails(option.flags, fullDesc);
});

I wonder how it would go separating the construction and the formatting, and making the constructed parts available directly? So the built-in formatting code would look like (say):

const help = this.options.map((option) => {
  return padOptionDetails(option.flags, option.fullDescription());
});

[shadowspawn]

Thanks @cravler
FYI I am working on a couple of other PR, and likely to be a while before I dig into this one.

[shadowspawn]

Experimenting in #1346 with refactoring and making help building blocks accessible.

[cravler]

Closing this in favour of #1365