command-line-usage - npm Package Compare versions

Comparing version 1.0.0 to 1.1.0

bin/cli.js

 #!/usr/bin/env node
 "use strict";
 var usage = require("../");
+var os = require("os");
+var fs = require("fs");
 var path = require("path");
+var ansi = require("ansi-escape-sequences");
 
-process.argv.splice(0, 2);
-var file = process.argv.shift();
-var cliOptions = require(path.resolve(file));
+var tmpPath = path.join(os.tmpDir(), Date.now() + "-clu.js");
 
-console.log(usage(cliOptions, { 
-    viewWidth: process.stdout.columns
-}));
+process.stdin
+    .pipe(fs.createWriteStream(tmpPath))
+    .on("close", getUsage);
+    
+function getUsage(){
+    var cliOptions = require(tmpPath);
+    fs.unlinkSync(tmpPath);
+    console.log(usage(cliOptions));
+}
+
+function halt(msg){
+    console.error(ansi.format(msg, "red"));
+    process.exit(1);
+}

example/my-app.js

@@ -5,6 +5,8 @@ module.exports = {
         description: "Generates something useful",
-        forms: [
-            "$ cat input.json | my-app [<options>]",
-            "$ my-app <files>"
-        ],
+        usage: {
+            forms: [
+                "$ cat input.json | my-app [<options>]",
+                "$ my-app <files>"
+            ]
+        },
         groups: {
@@ -11,0 +13,0 @@ main: {

lib/command-line-usage.js

 "use strict";
 var columnLayout = require("column-layout");
 var o = require("object-tools");
+var a = require("array-tools");
 var util = require("util");
 var ansi = require("ansi-escape-sequences");
-var a = require("array-tools");
 var t = require("typical");
+var UsageOptions = require("./usage-options");
+var arrayify = require("array-back");
 
 /**
+Generates [column-layout](http://github.com/75lb/column-layout) usage information for a command-line parser (e.g. [command-line-args](http://github.com/75lb/command-line-args)).
+
 @module command-line-usage
 */
-module.exports = usage;
+module.exports = getUsage;
 
 /**
-@param {cliOption[]} - the CLI options
-@param options {object} - Options
-@param [options.title] {string}
-@param [options.description] {string}
-@param [options.forms] {string|string[]}
-@param [options.groups] {object} - if you have groups, only names specified here will appear in the output
-@param [options.footer] {string}
-@param [options.hide] {string|string[]}
+@param {optionDefinition[]} - an array of [option definition](https://github.com/75lb/command-line-args/tree/rewrite#exp_module_definition--Definition) objects.
+@param options {module:usage-options} - Options
 @returns {string}
 @alias module:command-line-usage
+@example
+Some example usage output: 
+```
+
+  my-app
+  Generates something useful
+
+  Usage
+  $ cat input.json | my-app [<options>]
+  $ my-app <files>
+
+  Main options
+  This group contains the most important options.
+
+  -a, --one <string>     The first option
+  -b, --two <number>     The second option
+
+  Miscellaneous
+  -c, --three <string>   The third option
+  -d, --four <number>    The fourth option
+
+  Project home: https://github.com/me/my-app
+
+```
+
+..and the code to create it:
+```js
+var getUsage = require("command-line-usage");
+
+var optionDefinitions = [
+    { name: "help", alias: "h", type: Boolean, description: "Display this usage guide.", group: "main" },
+    { name: "files", alias: "f", type: String, multiple: true, defaultOption: true, description: "The input files to process", group: "main" },
+    { name: "timeout", alias: "t", type: Number, description: "Timeout value in ms", group: "main" },
+    { name: "custom", type: Custom, description: "A custom class instance"}
+];
+
+var options = {
+    title: "%bold{a typical app}",
+    description: "Generates something %yellow bg-black{wild and crazy}",
+    forms: [
+        "$ cat input.json | my-app [<options>]",
+        "$ my-app <files>"
+    ],
+    groups: {
+        main: {
+            title: "Main options",
+            description: "This group contains the most important options."
+        },
+        _none: "No group"
+    },
+    footer: "Project home: https://github.com/me/my-app",
+    hide: [ "files" ]
+};
+
+var usage = getUsage(optionDefinitions, options);
+```
 */
-function usage(cliOptions, options){
-    options = options || {};
-    options.hide = a.arrayify(options.hide);
-    cliOptions = cliOptions || [];
+function getUsage(definitions, options){
+    options = new UsageOptions(options);
+    definitions = definitions || [];
 
-    if (!Array.isArray(cliOptions)){
-        if (cliOptions.options && cliOptions.data){
-            options = o.extend(cliOptions.options, options);
-            cliOptions = cliOptions.data;
+    if (!Array.isArray(definitions)){
+        if (definitions.options && definitions.data){
+            options = o.extend(definitions.options, options);
+            definitions = definitions.data;
         }
@@ -40,3 +93,3 @@ }
     if (options.hide.length){
-        cliOptions = cliOptions.filter(function(option){
+        definitions = definitions.filter(function(option){
             return !a(options.hide).contains(option.name);
@@ -53,3 +106,3 @@ });
             option: getOptionNames(cliOption),
-            description: cliOption.description
+            description: getText(cliOption.description)
         });
@@ -62,16 +115,22 @@ };
     lines.addEmpty();
-    if (options.title) lines.addLine(ansi.format(options.title, "underline"));
-    if (options.description) lines.addLine(options.description);
+    if (options.title) lines.addLine(getText(options.title, "underline"));
+    if (options.description) lines.addLine(getText(options.description));
     if (options.title || options.description) lines.addEmpty();
 
-    if (options.forms){
-        options.forms = a.arrayify(options.forms);
-        lines.addLine(ansi.format("Usage", "underline"));
-        options.forms.forEach(function(form){
-            lines.addLine(form);
+    if (!options.usage && options.forms){
+        options.usage = {
+            forms: options.forms
+        };
+    }
+
+    if (options.usage){
+        options.usage.forms = arrayify(options.usage.forms);
+        lines.addLine(getText(options.usage.title || "Usage", "underline"));
+        options.usage.forms.forEach(function(form){
+            lines.addLine(getText(form));
         });
         lines.addEmpty();
     }
-    
-    if (cliOptions.length){
+
+    if (definitions.length){
         if (options.groups){
@@ -88,12 +147,16 @@ o.each(options.groups, function(val, group){
                 }
-                lines.addLine(ansi.format(title, "underline"));
+                lines.addLine(getText(title, "underline"));
                 if (description){
-                    lines.addLine(description);
+                    lines.addLine(getText(description));
                     lines.addEmpty();
                 }
-                a(cliOptions).where({ "+group": group }).forEach(lines.addRow);
+                if (group === "_none"){
+                    a(definitions).where({ group: undefined }).forEach(lines.addRow);
+                } else {
+                    a(definitions).where({ "+group": group }).forEach(lines.addRow);
+                }
                 lines.addEmpty();
             });
         } else {
-            cliOptions.forEach(lines.addRow);
+            definitions.forEach(lines.addRow);
             lines.addEmpty();
@@ -104,3 +167,3 @@ }
     if (options.footer){
-        lines.addLine(options.footer);
+        lines.addLine(getText(options.footer));
         lines.addEmpty();
@@ -133,1 +196,9 @@ }
 }
+
+function getText(text, styleArray){
+    if (t.isString(text)){
+        return ansi.format(text, styleArray)
+    } else if (t.isPlainObject(text)){
+        return ansi.format(text.text, text.format || styleArray);
+    }
+}

package.json

 {
   "name": "command-line-usage",
   "author": "Lloyd Brookes <[e-mail]>",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Generates command-line usage information",
@@ -26,7 +26,8 @@ "repository": "https://github.com/75lb/command-line-usage.git",
   "dependencies": {
-    "ansi-escape-sequences": "^2.1.0",
+    "ansi-escape-sequences": "^2.2.0",
+    "array-back": "^1.0.2",
     "array-tools": "^2",
     "column-layout": "^1.0.0",
     "object-tools": "^2",
-    "typical": "^2.2.0"
+    "typical": "^2.3.1"
   },
@@ -33,0 +34,0 @@ "devDependencies": {

README.md

 [![view on npm](http://img.shields.io/npm/v/command-line-usage.svg)](https://www.npmjs.org/package/command-line-usage)
 [![npm module downloads per month](http://img.shields.io/npm/dm/command-line-usage.svg)](https://www.npmjs.org/package/command-line-usage)
-[![Build Status](https://travis-ci.org/75lb/command-line-usage.svg?branch=rewrite)](https://travis-ci.org/75lb/command-line-usage)
+[![Build Status](https://travis-ci.org/75lb/command-line-usage.svg?branch=master)](https://travis-ci.org/75lb/command-line-usage)
 [![Dependency Status](https://david-dm.org/75lb/command-line-usage.svg)](https://david-dm.org/75lb/command-line-usage)
 
-# command-line-usage
+<a name="module_command-line-usage"></a>
+## command-line-usage
 Generates [column-layout](http://github.com/75lb/column-layout) usage information for a command-line parser (e.g. [command-line-args](http://github.com/75lb/command-line-args)).
 
-## Synopsis
-Where `example/my-app.js` looks like this
-```js
-module.exports = {
-    options: {
-        title: "my-app",
-        description: "Generates something useful",
-        forms: [
-            "$ cat input.json | my-app [<options>]",
-            "$ my-app <files>"
-        ],
-        groups: {
-            main: { 
-                title: "Main options",
-                description: "This group contains the most important options."
-            },
-            misc: "Miscellaneous"
-        },
-        footer: "Project home: https://github.com/me/my-app"
-    },
-    data: [
-        { name: "one", alias: "a", type: String, group: "main",
-          description: "The first option"
-        },
-        { name: "two", type: Number, alias: "b", group: "main",
-          description: "The second option"
-        },
-        { name: "three", alias: "c", type: String, group: "misc",
-          description: "The third option"
-        },
-        { name: "four", type: Number, alias: "d", group: "misc",
-          description: "The fourth option"
-        }
-    ]
-};
-```
-This command:
-```sh
-$ command-line-usage example/my-app.js
-```
+<a name="exp_module_command-line-usage--getUsage"></a>
+### getUsage(definitions, options) ⇒ <code>string</code> ⏏
+**Kind**: Exported function  
 
-Outputs this:
+| Param | Type | Description |
+| --- | --- | --- |
+| definitions | <code>Array.&lt;optionDefinition&gt;</code> | an array of [option definition](https://github.com/75lb/command-line-args/tree/rewrite#exp_module_definition--Definition) objects. |
+| options | <code>[usage-options](#module_usage-options)</code> | Options |
+
+**Example**  
+Some example usage output: 
 ```
@@ -71,25 +41,138 @@
   Project home: https://github.com/me/my-app
-  
+
 ```
 
-<a name="module_command-line-usage"></a>
-## command-line-usage
-<a name="exp_module_command-line-usage--usage"></a>
-### usage(cliOptions, options) ⇒ <code>string</code> ⏏
-**Kind**: Exported function  
+..and the code to create it:
+```js
+var getUsage = require("command-line-usage");
 
-| Param | Type | Description |
+var optionDefinitions = [
+    { name: "help", alias: "h", type: Boolean, description: "Display this usage guide.", group: "main" },
+    { name: "files", alias: "f", type: String, multiple: true, defaultOption: true, description: "The input files to process", group: "main" },
+    { name: "timeout", alias: "t", type: Number, description: "Timeout value in ms", group: "main" },
+    { name: "custom", type: Custom, description: "A custom class instance"}
+];
+
+var options = {
+    title: "%bold{a typical app}",
+    description: "Generates something %yellow bg-black{wild and crazy}",
+    forms: [
+        "$ cat input.json | my-app [<options>]",
+        "$ my-app <files>"
+    ],
+    groups: {
+        main: {
+            title: "Main options",
+            description: "This group contains the most important options."
+        },
+        _none: "No group"
+    },
+    footer: "Project home: https://github.com/me/my-app",
+    hide: [ "files" ]
+};
+
+var usage = getUsage(optionDefinitions, options);
+```
+
+
+<a name="exp_module_usage-options--UsageOptions"></a>
+## UsageOptions ⏏
+The class describes all valid options for the `getUsage` function. Inline formatting can be used within any text string supplied using valid [ansi-escape-sequences formatting syntax](https://github.com/75lb/ansi-escape-sequences#module_ansi-escape-sequences.format).
+
+**Kind**: Exported class  
+* [UsageOptions](#exp_module_usage-options--UsageOptions) ⏏
+  * _instance_
+    * [.title](#module_usage-options--UsageOptions+title) : <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code>
+    * [.description](#module_usage-options--UsageOptions+description) : <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code>
+    * [.usage](#module_usage-options--UsageOptions+usage) : <code>object</code>
+    * [.groups](#module_usage-options--UsageOptions+groups) : <code>object</code>
+    * [.footer](#module_usage-options--UsageOptions+footer) : <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code>
+    * [.hide](#module_usage-options--UsageOptions+hide) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
+  * _inner_
+    * [~textObject](#module_usage-options--UsageOptions..textObject)
+
+<a name="module_usage-options--UsageOptions+title"></a>
+### options.title : <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code>
+The title line at the top of the usage, typically the name of the app. By default it is underlined but this formatting can be overridden by passing a [textObject](#module_usage-options--UsageOptions..textObject).
+
+**Kind**: instance property of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+**Example**  
+```js
+{
+    title: {
+       text: "my-app",
+       format: [ "bold", "underline" ]
+    }
+}
+```
+<a name="module_usage-options--UsageOptions+description"></a>
+### options.description : <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code>
+A description to go underneath the title. For example, some words about what the app is for.
+
+**Kind**: instance property of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+<a name="module_usage-options--UsageOptions+usage"></a>
+### options.usage : <code>object</code>
+An array of strings highlighting the main usage forms of the app.
+
+**Kind**: instance property of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+**Properties**
+
+| Name | Type | Default |
 | --- | --- | --- |
-| cliOptions | <code>Array.&lt;cliOption&gt;</code> | the CLI options |
-| options | <code>object</code> | Options |
-| [options.title] | <code>string</code> |  |
-| [options.description] | <code>string</code> |  |
-| [options.forms] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> |  |
-| [options.groups] | <code>object</code> |  |
-| [options.footer] | <code>string</code> |  |
-| [options.hide] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> |  |
+| title | <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code> | <code>&quot;Usage&quot;</code> | 
+| format | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> |  | 
 
+**Example**  
+```js
+{
+    usage: {
+        title: "Synopsis",
+        forms: [
+            "$ my-app <options> <files>",
+            "$ my-app [-cvh]"
+        ]
+    }
+}
+```
+<a name="module_usage-options--UsageOptions+groups"></a>
+### options.groups : <code>object</code>
+Specify which groups to display in the output by supplying an object of key/value pairs, where the key is the name of the group to include and the value is a string or textObject. If the value is a string it is used as the group title. Alternatively supply an object containing a `title` and `description` string.
 
+**Kind**: instance property of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+**Example**  
+```js
+{
+    main: { 
+        title: "Main options",
+        description: "This group contains the most important options."
+    },
+    misc: "Miscellaneous"
+}
+```
+<a name="module_usage-options--UsageOptions+footer"></a>
+### options.footer : <code>string</code> &#124; <code>[textObject](#module_usage-options--UsageOptions..textObject)</code>
+Displayed at the foot of the usage output.
+
+**Kind**: instance property of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+<a name="module_usage-options--UsageOptions+hide"></a>
+### options.hide : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
+If you want to hide certain options from the output, specify their names here.
+
+**Kind**: instance property of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+<a name="module_usage-options--UsageOptions..textObject"></a>
+### options~textObject
+Contains text and formatting information.
+
+**Kind**: inner typedef of <code>[UsageOptions](#exp_module_usage-options--UsageOptions)</code>  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| text | <code>string</code> |  |
+| format | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | one or more ansi style names from [this list](https://github.com/75lb/ansi-escape-sequences#module_ansi-escape-sequences.style). |
+
+
+
 * * *
 
 &copy; 2015 Lloyd Brookes \<[e-mail]\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

23975

increased by83.7%

Number of package files

13

increased by30%

Lines of code

384

increased by125.88%

Number of lines in readme file

178

increased by87.37%

Worsened metrics

Dependency count

6

increased by20%

Number of low supply chain risk alerts

3

increased by50%

Dependency changes

• + Addedarray-back@^1.0.2

• Updatedansi-escape-sequences@^2.2.0

• Updatedtypical@^2.3.1