jsbatchrun

batchrun javascript commands

While grunt.js is a great tool for managing vertical tasks within a project, its capabilities to do the same jobs automated and repeatedly for more than one project are limited.
jsbatchrun is a cli for running horizontal jobs, which means repeatedly calling predefined tasks for a number of projects (directories with a package.json file).
All of jsbatchruns predefined tasks are packaged into 'plugins' which are simply called with options and arguments, that can be passed in to jsbatchrun manually or they can be read from a configuration file or 'generated' on the fly.
Currently all jsbatchrun plugins utilize grunt.js to be platform independent.

content

• Usage (see further down this page)

  • Getting started guide
  • Usage and examples
  • Using confguration files
  • Commandline options and arguments
  • Plugins

• Developers

  • Testing jsbatchrun
  • Code coverage of tests for jsbatchrun
  • Build jsbatchrun from scratch
  • NPM integration of jsbatchrun
  • Frameworks used for testing, building, etc.
  • API of package jsbatchrun (self generated with jsbatchrun)

• Changelog

getting started

install

This guide assumes, that you are familiar with the use of npm.

npm install jsbatchrun --save

prerequisites

jsbatchrun and its plugins utilize grunt plugins.
In case your own projects make use of grunt as well, it's not recommended to install jsbatchrun globally. You might be better off creating a jsbatchrun project.

usage

syntax

All jobs follow one scheme:

# Note: jsbr is an alias for 'jsbatchrun'
> jsbr [command] [options and flags] [--] [ argument, ...]

commands

The first value in the list of process.argv is interpreted as command.
It will be used for looking up a "matching" plugin.

# lookup plugin 'npm'
> jsbr npm

There is (as always) one exception: 'help'
Help is a valid command, but it's no plugin. Instead 'help' is used to invoke help on a plugin (which must be named next in the list of process.argv).

# invoke help on 'nothing' => this will list all registered 'plugins' (aka commands)
> jsbr help

# invoke help on plugin 'npm' => this will list all subcommands of plugin 'npm'
> jsbr help npm

using configuration files

Configuration files provide a way to

• load plugins (more commands)
• provide properties that can be used with options or arguments

--config path

path may be an absolute path to a configuration file or it must be relative to the current working directory (cwd) or (cwd)/.conf/jsbatchrun/

Read more on configuration files (Follow the link)

options and flags

Parsing of options and flags is done by invoking minimist on the 'rest' of process.argv after all commands have been stripped away.

Tip:
Pass in 'flags' (options with no values) first, to avoid interference with arguments or use the "--" switch to signal the end of options and the beginning of arguments to 'minimist'

# will result in args.flag === "path1" and args._ === [ "path2", "path3" ]
> jsbr command subcommand --flag path1 path2 path3

# will result in args.flag === true and args._ === [ "path1", "path2", "path3" ]
> jsbr command subcommand --flag -- path1 path2 path3

injecting options

You might want to look at the list of special options

jsbatchrun aims to reduce manual work with monkeyjobs. Therefor it provides a way to inject options (create them on the fly) with predefined values:

--env:opt:[propertyname]:[optionname]

# in case there is a configfile at 'path1' which provides a property named 'foo'
# that has a value 'douchebag', the following will result in calling the
# 'subcommand' of 'command' with the option --bar "douchebag"
> jsbr command subcommand --env:opt:foo:bar --config path1

# The above would be equal to:
> jsbr command subcommand --bar "douchebag"

This shows its true power in conjunction with jsbatchruns capability to inject arguments from properties, defined in a configuration file.

arguments

All values which are no commands and no options are passed to commands as part of the list of arguments. Simple as that, jsbatchrun provides special options to 'narrow down' or 'widen' the list of arguments.

injecting arguments

You might want to look at the list of special options
jsbatchrun provides three ways of injecting values as arguments.

1. inject arguments if no arguments are provided via the commandline:

--env:args:use:[propertyname]

# this expects the default configuration file to exist and to provide a
# property named 'directorylist'. All values of 'directorylist' will be
# passed as arguments to subcommand.
> jsbr command subcommand --env:args:use:directorylist

# The following will fail, because arguments are already provided!
> jsbr command subcommand --env:args:use:directorylist -- ~/projects/project-00 ...

2. append arguments to the list of arguments:

--env:args:append:[propertyname]

# this expects the default configuration file to exist and to provide a
# property named 'directorylist'. All values of 'directorylist' will be
# passed as arguments to subcommand.
> jsbr command subcommand --env:args:append:directorylist

# The following will not fail. All values of 'directorylist' will follow
# after the arguments already provided
> jsbr command subcommand --env:args:append:directorylist -- ~/projects/project-00 ...

3. prepend arguments to the list of arguments:

--env:args:prepend:[propertyname]

# this expects the default configuration file to exist and to provide a
# property named 'directorylist'. All values of 'directorylist' will be
# passed as arguments to subcommand.
> jsbr command subcommand --env:args:append:directorylist

# All values of 'directorylist' will be inserted before the arguments already
# provided
> jsbr command subcommand --env:args:prepend:directorylist -- ~/projects/project-00 ...

narrowing of arguments

In case your previous command failed with argument (project) no. X in your list of arguments. Would you like to retype your command with the remaining number of n arguments?

To avoid that, arguments can be narrowed, no matter how many arguments have been prepended to, used by or appended to your list of arguments.

You might want to look at the list of special options

1. Start argument processing at a given position:

--args:from

# this will pass all arguments to subcommand, starting with and including the
# seventh argument, up to the last argument of the list of arguments.
> jsbr command subcommand --args:from 7 --env:args:[type]:[property] [more arguments]

# Note: in case there are less then "7" arguments, nothing will happen ;-)

2. Stop processing arguments at a given position:

--args:to

# this will pass all arguments to subcommand, starting with the first argument of the
# list of arguments and stopping at but including the seventh argument.
> jsbr command subcommand --args:to 7 --env:args:[type]:[property] [more arguments]

# Note: in case there are less then "7" arguments, only the available number of arguments
#       can and will be processed.

3. Start and stop processing arguments at a given position:

> jsbr command subcommand --args:from 3 --args:to 7 --env:args:[type]:[property] [more arguments]

4. Process an argument at a given position:

> jsbr command subcommand --args:index 3 --env:args:[type]:[property] [more arguments]