main

main

Provides a 'main' function that is ran when the script is called directly (e.g. CLI):

require('main').run(module, ($) => {
  /*
        [ code to run here ]
  */
})

The above code will NOT run if imported into another module.

_{Note: The variable module is required.}

Install

npm i main --save

TOC

• Example: Getting Started (examples/foobar/*)
• Basic Argument Parsing
• Advanced Argument Parsing
• Example: Advanced Argument Parsing (examples/advanced)
• Doc Generation
• CLI helpers

Example: Getting Started (examples/foobar/*)

Let's take a look at HELLO.js:

#!/usr/bin/env node
// HELLO.js

exports.foo = () => 'foo'
exports.bar = () => 'bar'

require('main').run(module, ($) => {
  console.log('Hello ' + $('name'));
})

HELLO.js defines two functions, and a function to run if called from the CLI. The functions foo and bar can now be included in other modules.

Let's take a look at FOOBAR.js:

#!/usr/bin/env node
// FOOBAR.js

const { foo, bar } = require('./HELLO');

require('main').run(module, () => {
  console.log(`${foo()} ${bar()} baz`)
});

Notice how it requires HELLO.js and pulls out the exposed functions---easy enough.

Now let's play around a bit with what we've created:

$ ./HELLO.js
Hello undefined

$ ./HELLO.js --name World
Hello World

$ ./FOOBAR.js
foo bar baz

Notice how FOOBAR.js does not execute the main function within HELLO.js.

See the next section on how argument parsing works.

Basic Argument Parsing

By default parsing arguments works without configuration. In our first example, examples/foobar automatically parses the --name flag.

We did this by using $('name') in our code within the main function. Positional arguments can be fetched by referencing their position, e.g. $(0) or $(1) to get the first or second args.

Advanced Argument Parsing

If you want:

• flag aliases, e.g. -f & --foo to be the same.
• flag types, e.g. enforce 'always string'.
• default flag values from:
  • hard-coded defaults.
  • environment variables.
• specify required flags

You'll have to be okay with one fact:

• Markdown is used as configuration for the above.

By enforcing this rule, documentation becomes a key part of the CLI tool. This allows for some neat things such as automatic man page support and html doc generation (See Documentation) for your CLI tool. It will also keep the tools docs up to date when changes are made.

The next section covers an example markdown format that the parser expects, and how it's used in the 'main' module.

Example: Advanced Argument Parsing (examples/advanced)

Check out the contents of examples/advanced/demo.md.

To enable advanced argument parsing using this markdown file, simply pass the location of a properly formatted markdown document as the second argument to this module:

examples/advanced/demo.js

require('main').run(module, './demo.md', function($) {
  /*
      [ see: examples/advanced/demo.js ]
  */
});

Sample session with the above script enforcing the constraints:

$ ./demo.js
Error: Missing required option demand

$ ./demo.js --demand
Error: Missing required option pghost

$ PGHOST=localhost ./demo.js --demand hey hey you you
{ _: [ 'hey', 'hey', 'you', 'you' ],
  f: false,
  flag: false,
  home: '/home/jay',
  demand: true,
  default: 'foo',
  d: 'foo',
  pghost: 'localhost' }

Doc Generation

This is not a part of the 'main' module. This is a light overview of the module marked-man that allows us to easilly generate man pages and HTML dos for our package using the same exact markdown that specifies our tools advanced options.

In short:

1. npm install marked-man --save-dev
2. npx marked-man demo.md > man/demo.1
3. add "man" field to package.json: "man" : "./man/doc.1"

View the official npm docs on the "man" field for more information.

View marked-man repo for more output formats (HTML, etc.)

Note that man pages are only installed when the package is installed globally on a users system and can be accessed as usual.

CLI helpers

In addition to the argument fetching, a very minimal set of functions & getters have been attached to the $ object.

Arguments

• $.all - An object containing all the arguments given.
• $.pos - An array containing all the positional arguments given.

IO

• $.cout() - Alias for console.log, chainable.
• $.cerr() - Alias for console.error, chainable.
• $.out - Alias for process.stdout
• $.err - Alias for process.stderr

Assert

• $.assert

Exports Node's assert library to this variable. Useful for argument checking, argument lengths, etc.

Misc.

• $.exit() - Alias for process.exit