75lb / command-line-usage Goto Github PK

Hi, great library. I enjoy using it so far. However, the hide option as explained and demonstrated here does not work for me. Could it be because I reference optionList from a variable?

Small excerpt of my code:

const optionDefinitions = [
    // other options
    {
        name: 'debug',
        type: Boolean,
        hide: true // just tried it out of curiosity but doesn't work either; could perhaps be an alternative way of handling options that should be hidden
    }
]

const usageSections = [
    // other sections
    {
        header: 'Options',
        hide: [ 'debug ' ],
        optionList: optionDefinitions
    }
]

const commandLineArgs = require( 'command-line-args' )
const options = commandLineArgs( optionDefinitions, { camelCase: true } )

const commandLineUsage = require( 'command-line-usage' )
const usage = commandLineUsage( usageSections )
console.log( usage )

But as described, in the usage output in the Options section there appears a --debug entry.
Do I misuse the library?

Edit: Right after I posted this issue I found the added whitespace in hide: [ 'debug ' ]. Issue can be closed, sorry.

I have a Usage section that is quite wide (15 character desc and 80 character example). This is creating wrapping issues that are breaking my Jest snapshots when not running in a TTY (Jenkins CI). I have filed an issue in 75lb/table-layout as well.

I think that both issues could be resolved by allowing content.js to work with tableOptions like you have in option-list.js.

Thanks!

I can do:
console.log(JSON.stringify("output with printed \n and no line break"))
and get:
output with printed \n and no line break

I tried:

    optionList: [
      { 
        name: 'preload',
        type: Boolean, 
        description: JSON.stringify("initex.js '\n<fmt>' to dump core by with with format fmt"), 
        alias: 'p'
      },

and I get a linebreak which I don't want.

I get chaos if do
console.log(JSON.stringify("commandline_usage))
because all line breaks are removed.

Is there another way to do this?

might be nice to support some markdown constructs like _italics_, __bold__, code etc.

Hello,

Thank you for the very helpful library. I see her new use case. Well, I'm going to develop documentation using the Markdown format for our extensive CLI.

To this end, support for Markdown formatting would be useful.

I am asking for information in this regard, as well as in the scope of possible incorporation of changes to this library. I prefer to be sure about work on the topic before I start developing my own solution.

Kind regards,

Content documentation has no reference to this possible content declaration (object with options and data, both optionals but one required).

Reading the source code, I understand that the option object has the same type as table-layout options and data has the same type as an array of objects decribed into Content document (the same as table-layout data).

Are my assumptions correct?

is it possible to show default values automatically?
Thanks

I'm misunderstand the handling of these package.

How i can step into registred commands like these:

{
    header:		'Available Commands',
    content: [
      { name: 'check', summary: 'Check a given nickname' },
      { name: 'register', summary: 'Register a nickname with given informations' },
      { name: 'help', summary: 'Display help informations.' },
      { name: 'version', summary: 'Print the version.' },
    ]
  }

When i try to use node main.js check, on argv, each time help is present.

Currently, a section with a header but no content will not render. Fix it so the following will render, printing the header only.

{
  header: 'My title',
  content: ''
}

const cliUsage = require('command-line-usage')
const sections = [
  {
    header: 'web2js: compile.js, initex.js, tex.js',
    content: '{underline Generate WebAssembly {bold JSTEs} {italic (JavaScript Typesetting Engines)} and core.dump}'
  },

result:

• underline => OK
• bold => OK
• italic is not working

Why?

Windows 10 1803 64 bit node v11.10.1, comand-line-usage and chalk just installed.

Currently, if an string option is defined as lazyMultiple: true it shows --name string in the option list.

Like when multiple: true is set, it should show --name string[].

In command-line-args, if you omit the type on an OptionDefinition, it defaults to String.

Currently, if a definition does not have a type, in the usage optionList the typeLabel is empty. It should default to string, e.g. --name string or --name string[].

const sections = [
  {
    header: 'web2js: compile.js, initex.js, tex.js',
    content: 'Generate WebAssembly {bold JSTEs} (JavaScript Typesetting Engines) and core.dump'
  },

  {
    header:  'Untitled Arguments, Example',
    content: 'JSTE, fmt         node.exe JS/web2js/compile.js eTeX 01`' + 
           '\n-                 => JSTE = eTeX' +
           '\n-                 => fmt  = 01' +      
           '\n-                 node.exe ../JS/web2js/compile.js 01`' + 
           '\n-                 => JSTE:  derived from directory name' +
           '\n-                 => fmt  = 01' +                
           '\n-                 node.exe ../../JS/web2js/compile.js`' + 
           '\n-                 => JSTE:  derived from directory name' +
           '\n-                 => fmt:   derived from directory name'                  
  },

I want to code '\n...' without the minus sign but then everything moves to the left.

How can I get a layout as follows?

  JSTE, fmt         node.exe JS/web2js/compile.js eTeX 01`
                    => JSTE = eTeX
                    => fmt  = 01
                    node.exe ../JS/web2js/compile.js 01`
                    => JSTE:  derived from directory name
                    => fmt  = 01
                    node.exe ../../JS/web2js/compile.js`
                    => JSTE:  derived from directory name
                    => fmt:   derived from directory name

Hello,

I have installed 5.0.5 via npm. Whenever I add a group to ANY definition, the library produces and empty string when called. Commenting out the group property for the definition and rerunning causes all the content to be generated again.

At the moment sections is an array. Say we have three sections:

const sections = [
  {
    header: 'A typical app',
    content: 'Something.'
  },
  {
    header: 'Examples',
    content: [ ... ]
  },
  {
    content: 'Project home: [underline]{https://something.com}'
  }
]

If we want to override the Examples section we would access sections[1]. This would fail if the Examples section later moved to a different position. It would be more reliable to retrieve a named section from a Map.

Define the sections:

const sections = new Map()
sections.set('header', { header: 'A typical app', content: 'Something.' })
sections.set('examples', { header: 'Examples', content: '...' })
sections.set('footer', { content: 'Project home: [underline]{https://something.com}' })

Retrieve and override the examples:

sections.get('examples', { content: 'something different' })

However, Arrays are ordered and Maps are not. It's easier to insert new sections at specific index positions within an Array than it is within a Map. To get the best of both worlds (named sections of Maps with the ordered nature of Arrays) we could keep the existing Array-based structure with an id or name property on each individual section, to make them addressable by name.

Hi,

Great package!

Let's say you have some default args setup via commandLineArgs().

Why can't a rudimentary --help be automatically generated from that?

Or am I missing something?

Would be nice to have support for simple inline text color. Something like this:

[color=red]{This is some red coloured text.}\n
This is some normal coloured text.\n
[color=cyan]{Some cyan coloured words.}

Hello, I've been trying to understand how you implemented the {red text} api, but i'm struggling to figure it out, since I can't find any reference to raw in chalk.

This is the source:

function chalkFormat (str) {
  if (str) {
    str = str.replace(/`/g, '\\`')
    const chalk = require('chalk')
    return chalk(Object.assign([], {raw: [str]}))
  } else {
    return ''
  }
}

Which you can use like this

chalkFormat('hello {red friend}')

and outputs this:

which is a simpler equivalent of using chalk:

`hello ${chalk.red('friend')}`

Just for the sake of learning, could you please explain?
Thanks 😃

I think it'd be handy if you could provide an out-of-the-box solution for converting the usage options into Markdown, e.g., for inclusion in a README. I know it should not be too hard to parse it oneself, but it could be handy, e.g,. for italicizing, if this were all done for us... :)

Seems like CommonJS imports broke with the v7.0.0 release; there's no ./dist/index.cjs included with the published package.

node:internal/modules/cjs/loader:535
      throw e;
      ^

Error: Cannot find module '/abbreviated/node_modules/command-line-usage/dist/index.cjs'
    at createEsmNotFoundErr (node:internal/modules/cjs/loader:1022:15)
    at finalizeEsmResolution (node:internal/modules/cjs/loader:1015:15)
    at resolveExports (node:internal/modules/cjs/loader:529:14)
    at Function.Module._findPath (node:internal/modules/cjs/loader:569:31)
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:981:27)
    at Function.Module._load (node:internal/modules/cjs/loader:841:27)
    at Module.require (node:internal/modules/cjs/loader:1067:19)
    at require (node:internal/modules/cjs/helpers:103:18)
    at Object.<anonymous> (/<masked>/index.js:20:46)
    at Module._compile (node:internal/modules/cjs/loader:1165:14) {
  code: 'MODULE_NOT_FOUND',
  path: '/abbreviated/node_modules/command-line-usage/package.json'
}

Thanks for making this great tool-set! Is it still actively under maintenance?

Just noticed, the anchor links content and optionList links at top of the readme are broken.

Hi, changing this line:

only allows usage of:

Boolean
Number
String

but changing it to:

let type = typeof definition.type === "string" ? definition.type.toLowerCase() : definition.type ? definition.type.name.toLowerCase() : 'string'

would allow the usage of all of these:

Boolean
Number
String

"boolean"
"number"
"string"

The first three resolves to the second three anyway so it should not break anything.

This would make this library play perfectly with the meow library without any redundant code.

Thanks

The underlining of indented text does not wrap cleanly across lines, see attached screenshot
This was produced with the following

const commandLineHelp=[
	{
		header: 'DVB Central Service Registry',
		content: 'An implementaion of a DVB-I Service List Registry'
	},
	{
		header: 'Synopsis',
		content: '$ node csr <options>'
	},
	{
		header: 'Options',
		optionList: optionDefinitions
	},
	{
		header: 'Client Query',
		content: '{underline <host>}:{underline <port>}/query[?{underline arg}={underline value}(&{underline arg}={underline value})*]',
	},
	{
		content: [
			{header:'{underline arg}'},
			{name:'regulatorListFlag', summary:'Select only service lists that have the @regulatorListFlag set as specified (true|false)'},
			{name:'Delivery[]', summary:'Select only service lists that use the specified delivery system (dvb-t|dvb-dash|dvb-c|dvb-s|dvb-iptv)'},
			{name:'TargetCountry[]', summary:'Select only service lists that apply to the specified countries (form: {underline ISO3166 3-digit code})' },		
			{name:'Language[]', summary:'Select only service lists that use the specified language (form: {underline IANA 2 digit language code})'},		
			{name:'Genre[]', summary:'Select only service lists that match one of the given Genres'},		
			{name:'Provider[]', summary:'Select only service lists that match one of the specified Provider names'}
		]
	},
	{	content:'note that all query values except Provider are checked against constraints. An HTTP 400 response is returned with errors in the response body.'},
	{
		header: 'About',
		content: 'Project home: {underline https://github.com/paulhiggs/dvb-i-tools/}'
	}
];

Currently, the width of a content section is configurable. Here's an example of a content section with a maxWidth of 40:

const usage = commandLineUsage([
  {
    header: 'A typical app',
    content: {
      options: { maxWidth: 40 },
      data: [
        { col: 'Generates something [italic]{very} important. This is a rather long, but ultimately inconsequential description intended solely to demonstrate description appearance. ' }
      ]
    }
  }
])

Output:

A typical app

  Generates something very important.
  This is a rather long, but ultimately
  inconsequential description intended
  solely to demonstrate description
  appearance.

However, an optionList section currently has a fixed width of 80 columns which is an issue for some users.

Resolve this issue by making the maxWidth of an optionList section configurable, the same way as it is for a content section.

I don't see a way to show the default value.

Due to denoland/deno#13321, the library fails with

error: Uncaught TypeError: chalk.underline.bold is not a function
    at ContentSection.header (file:///Users/ulken/Library/Caches/deno/npm/registry.npmjs.org/command-line-usage/6.1.3/lib/section.js:23:32)

The version of chalk used is really old. Please consider upgrading to at least 4.X, where the issue above is fixed. If you want to take the step to ESM, you might want to take it to 5.X+ even.

If you're up for it, let me know if you want me to help out in any way.

PS. Even if you have no intention of supporting Deno, I think it would still be worth to upgrade Chalk to a more modern (and safer) version.

The lib/section/ folder is missing from the npm package in v6.0.0, which causes runtime errors such as below:

Error: Cannot find module './lib/section/option-list'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:582:15)
    at Function.Module._load (internal/modules/cjs/loader.js:508:25)
    at Module.require (internal/modules/cjs/loader.js:637:17)
    at require (internal/modules/cjs/helpers.js:22:18)
    at commandLineUsage (/Users/xxx/workspace/proj/node_modules/command-line-usage/index.js:15:24)

Verified the files are missing by downloading/unzipping from npm directly:

curl -O https://registry.npmjs.org/command-line-usage/-/command-line-usage-6.0.0.tgz

Reference

Consider running stuff through the chalk template function like this:

const chalk = require('chalk');
const chalkTemplate = require("chalk/templates");

const myString = "{red RED}";

console.log(chalkTemplate(chalk, myString));

Which is slightly less ugly, but still hacky.

Also see chalk/chalk#258

I've wanted to display my own logo (banner) in my project usage, yet it couldn't handle the "\"-characters properly.

Now I took the banner example from your Wiki and changed the previous logo with mine.

just removed const chalk = require('chalk') and replaced chalk.red( ... ) with header

The problem is - when I execute it:

green is a normal console.log() and normal is the one generated.

The banner is made with String.raw, so every "\" is replaced with "\\", that means it is written by eg. console.log(). Yet the libary does skip them anyway.
I brute forced a little bit and found out it takes 4 or in String.raw 2 (2*2) "\" to write one into the usage.
Maybe the formater refactors between strings and deletes some "\" or delets them by some replace functions?

EDIT:

Quick fix for users:
use Straing.raw methode as explained above and append .replaceAll("\\","\\\\") at the End.

File: test.js.zip

Hope I could help,
Jakabi

Could you please update the typescript definitions to add description to OptionDefinition and have the commandLineArgs function accept a Readonly array of options? The function definition could then look something like this:

declare function commandLineArgs(
	optionDefinitions: ReadonlyArray<commandLineArgs.OptionDefinition>,
	options?: commandLineArgs.ParseOptions
): commandLineArgs.CommandLineOptions;

Trying to run the example throws with:
NAME_MISSING: Invalid option definitions: the name property is required on each definition

https://github.com/75lb/command-line-usage/tree/f0403a942cb3178dfb28f17e60fac50ddccf432c#simple

The "simple" example no longer exists

Currently name property in optionList is required and it is rendered with -- prefix in the usage help text.

I'm trying to create a usage help in which some of the switches doesn't accept long forms and I want to render them like below:

  -l value              List all                     
  -f                    force description 
  -a, --append value    Appending some value

Hi,

How can I use both "command-line-args" and "command-line-usage" and write the definitions once? (No duplicate definitions).

Thanks

command-line-commands and command-line-args have support for @types/ in NPM: can this get type definition files added as well?