Commands

Configurator considers command-oriented applications a special arrangement of schema fields and children, with a few small "hints" provided to enhance command-line parsing.

• A simple field is used to store the command specified by the user, but is marked with command: true in the field options.
• A child schema is used to define each potential command. These child schemas are linked back to the command field using linkedParentFieldName.
• If the name of the child schema doesn't exactly match the command, the linkedParentFieldValue option can define the command text.
• Linked child schemas are only evaluated if their matching parent field has the required value.
• You can define sub-commands within a linked child schema to build a command hierarchy.
• The command line parser uses these field/child hints to produce simple options:

For example, here's an excerpt of an app defining a command schema:

spm.js

// ...
schema.field('action', {type: 'string', command: true})

schema.child('install', {linkedParentFieldName: 'action'})
      .field('packages', {type: '[string]', general: true, required: true})
      .field('save', {type: 'boolean'})
      .field('save-dev', {type: 'boolean'})
      .field('global', {type: 'boolean'})

schema.child('test', {linkedParentFieldName: 'action'})
      .field('ignore-scripts', {type: 'boolean'})

schema.child('run', {linkedParentFieldName: 'action'})
      .field('workspace', {type: 'string'})
      .field('if-present', {type: 'boolean'})
      .field('script', {type: 'string', general: true, required: true})
// ...

Running this with node spm.js --help produces:

Usage: spm [install|test|run [command-options]]

  install [options] <string...>
    --save (-s) [true|false]
    --save-dev (-S) [true|false]
    --global (-g) [true|false]

  test [options]
    --ignore-scripts (-i) [true|false]

  run [options] <string-value>
    --workspace (-w) <string-value>
    --if-present (-i) [true|false]

Running with node spm.js install --save foo bar yields

{
  "action": "install",
  "install": { 
    "packages": [ "foo", "bar" ], 
    "save": true
  }
}

The command line parser automatically creates "shortened" versions of command fields and parses them hierarchically, but the the entire configuration hierarchy is defined in the same way as regular fields and children; for example, the environment variables SPM_TEST_IGNORE_SCRIPTS and SPM_RUN_IF_PRESENT would be loaded (but ignored in this run because they are in disabled linked schemas.) The environment variable SPM_INSTALL_GLOBAL would however be evaluated, as it is under the install child schema.

In other words, Configurator commands don't actually "do" anything on their own; they simply provide structured hints for the command line to hierarchically assemble the configuration in a friendly manner. The actual work of interpreting what a command "means" is up to the application.

See the API documentation for ConfigurationSchema for more information on defining commands.

(For a higher-level abstraction that builds on Configurator to provide executable code modules, see ModuleManager).