argpa - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

index.js

@@ -9,4 +9,4 @@ module.exports = class Argpa {
 
-  add (cmd, fn) {
-    this.cmds[cmd] = fn
+  add (commandName, fn) {
+    this.cmds[commandName] = fn
   }
@@ -47,3 +47,3 @@
 
-  parse (argv, opts = {}) {
+  parse (argv = process.argv.slice(2), opts = {}) {
     const { boolean = [], string = [], alias = {}, default: def = {}, validate = false } = opts
@@ -50,0 +50,0 @@ const valid = validate ? [...boolean, ...string, ...Object.values(alias).flat(), ...this.flags.map((str) => str.slice(2))] : null

package.json

 {
   "name": "argpa",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Like minimist, less mini",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

 # argpa
+
+**WARNING: this is a work in progress, the API might change significantly in future versions.**
+
+Middleweight arg parsing library.
+
+```
+npm install argpa
+```
+
+## Usage
+
+```js
+const Argpa = require('argpa')
+
+const cmd = new Argpa()
+const argv = '-a -b c'.split(' ')
+const { alpha, beta } = cmd.parse(argv, {
+  boolean: ['alpha'],
+  string: ['beta'],
+  alias: {
+    alpha: 'a',
+    beta: 'b'
+  }
+})
+console.log(alpha) // prints true
+console.log(beta)  // prints 'c'
+```
+
+## API
+
+The module exports a class, the constructor for it is 
+
+#### `const cmd = new Argpa(flags, help, teardown)`
+
+All three arguments are optional.
+
+`flags` defines the general flags that should be available to all commands and subcommands. 
+Defaults to `[]`
+
+`help` defines a helper function to run with `--help` in complex CLIs.
+It can be invoked with any command or subcommand, and it gets passed the `commandName` as argument.
+It's called by `cmd.run`
+Defaults to `function (commandName) { return commandName }`
+
+`teardown` defines a function that gets run at the end of `cmd.run()`as 
+```
+finally {
+  await this.teardown()
+}
+```
+It defaults to the noop `function () {}`
+
+#### `cmd.add(commandName, fn)`
+This method introduces a command with an associated function.
+When invoked via `cmd.run`, the function will be passed the flags and arguments that follow the command, for example
+
+```
+command subcommand -flag argument
+```
+
+will invoke the command `command subcommand` by calling its associated function and passing to it `['-flag', 'argument']`. You can parse that argument array inside the function, using `cmd.parse`
+
+#### `const x = await cmd.run(argv = argv = process.argv.splice(2))`
+This async method is probably going to be the starting point of the CLI, it will parse the argument array and select the correct command between the ones added. It also launches the help function if the array contains `--help`.
+
+
+#### `const result = cmd.parse(argv = process.argv.splice(2), opts = {})`
+This method is the main parser of the library.
+It parses the provided array of arguments and return an object that contains a key/value entry for each flag/argument, plus a `_` entry for an array of positional arguments, and  a `--` entry for an array of arguments passed down using `--`.
+The `opts` object can have the following properties:
+
+```
+{
+  boolean: [],
+  string: [],
+  alias: {},
+  default: {},
+  validate: true 
+}
+```
+`boolean` is an array of the flags you want to have a boolean value. 
+Boolean flags will be `true` by default, unless prepended with `no-`, in which case they will be `false`
+
+ `string` is an array of the flags you want to have a string value. 
+ 
+ `alias` is a key/value pairing of flags and their aliases.
+ 
+ `default`  is a key/value pairing of flags and their default values.
+ 
+ `validate` will make the parser throw an error if an unknown flag is called.
+ 
+ The arguments of list flags, like `--numbers=1,2,3`, will automatically be parsed as strings, in this case `1,2,3`
+ 
+ 
+## Summary
+
+If you don't need subcommands, you just construct your parser with `const cmd = new Argpa(...)` and use `cmd.parse`to parse the provided arguments.
+
+If you need something more complex
+-  construct your parser with `const cmd = new Argpa(...)`
+-  use  `cmd.add` to add commands & subcommands and associate them to functions
+-  use `cmd.parse` inside those functions to define specialized parsers for the flags&arguments of those commands
+-  launch the parser with `cmd.run`

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

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

Improved metrics

Total package byte prevSize

21710

increased by19.29%

Number of lines in readme file

105

increased by5150%

No dependency changes