Extensions can define their own commands with the help of the Roc object. This is a powerful feature of Roc that makes it easy to add new commands that can be used with the CLI.
Roc expects that the commands are either a string or a function. See example below for a valid structure.
module.exports = {
commands: {
command1: someFunction,
command2: `${require.resolve('eslint/bin/eslint.js')} .`,
}
}The name of the key will be the name of the command. Meaning that the example above would run by typing roc command1 or roc command2. See more here about how commands are managed.
Important!
The property name command is reserved and should not be used as the name for a command group or command.
A string command is a string that will managed as if it was typed into the terminal directly. Great for creating aliases to other commands. Uses spawn-command internally meaning that the command will be launched in either cmd.exe or /bin/sh. The node_modules/.bin for a extension will be added by default making it easy to proxy CLI tools to Roc projects.
This feature is experimental in it’s current state and will be improved going forward.
String commands uses execute internally.
Tip: You can provide additional arguments to a command in Roc that is using a string command by using --.
The function will be invoked with an object called commandObject.
Example
(commandObject) => { /* do stuff */ }Object that is built when running the command line interface and what command functions get as their first argument, called commandObject.
Object structure
{
context: context,
info: {
name: 'roc',
version: '1.0.0'
},
arguments: {
managed: {}
unmanaged: []
},
options: {
managed: {}
unmanaged: {}
},
extraArguments: []
}The context object in Roc.
Read more about the context object here.
An object containing information about the name and the version as strings for the CLI that was invoked.
An object with the arguments that were passed to the command.
An object with values matching the defined arguments from the commands meta information as key-value.
An array with the arguments that were not managed by Roc.
An object with the options that were passed to the command. Will not include options from the settings.
An object with options matching the defined options from the commands meta information as key-value.
An object with options that were not managed by Roc.
An array with the arguments that are defined after -- on the command line.
To define new commands that extension will need to either use the command property on the Roc object or return a command property from the init function.
Example
commands: {
command0: commandFunction0,
group: {
__meta: {
...
},
command1: {
command: commandFunction1,
description: 'Explaining what the command does.'
},
command2: commandFunction2
}
}Groups are used to group commands and other groups. A group can contain other groups and one to several commands.
Used for groups to define additional meta data.
Example
group: {
description: 'A description for what the group does',
markdown: 'A __markdown__ description for the what the group does',
name: 'My Group',
override: 'roc-package-example'
}Description that will be shown when using --help for the group and when generating documentation by default.
Markdown formatted text that will be used, if available, when using roc meta docs, will be used over description if defined.
A string with the name for the group, can be used to show something over the property name that is the default.
A string or a boolean that is to be used if the group already exists. The override will need to be set to either the name of the extension that defined it previously or true for always overriding.
A command can be either a string, a function or an object. It’s recommended to use objects since it will allow both string and function commands to be used along with additional meta information.
Example
command1: 'eslint .',
command2: commandFunction2,
command3: {
arguments: [],
command: commandFunction3,
description: 'A description for the command',
help: 'A help text for the command, longer than the description.'
markdown: 'A __markdown__ text for the command.',
options: [],
override: 'roc-package-example',
settings: ['dev']
}An object where the keys are the names for the arguments. The order of the keys matter, they are parsed in the same order as they are listed.
The key will be used in the CLI for information and as the name of the value in commandObject.arguments.managed.
Internally Object.getOwnPropertyNames is used to guarantee the order as they are created.
Example
arguments: {
feature: {
converter: toBoolean,
default: false
description: 'If something should be enabled or not',
validator: isBoolean
}
}converter
A converter to be used to convert the input to some other format. Should match the following format (input) => output.
For convenience several types of converters exists in roc that can be imported from roc/converters. See here for a complete list of them along with more information on how they work..
default
The value that the argument will hold if nothing is provided to the CLI.
description
A text that describes how the argument can be used.
validator
Roc assumes that the validators used is either a RegExp or a function that will return true if it's valid or false/error string if it's not.
For convenience several types of validators exists in roc that can be imported from roc/validators. See here for a complete list of them along with more information on how they work..
A string that describes what the command does. Used when printing general information about all the possible commands.
Used when printing information about a specific command. The input is reindented and starting/ending newlines are trimmed which means you can use a template literal without having to care about using the correct amount of indent. If no help is provided the description will be used instead.
Used when generating documentation for the commands. The input is reindented and starting/ending newlines are trimmed which means you can use a template literal without having to care about using the correct amount of indent. If no markdown is provided the help will be used instead.
An object where the keys are the names for the options.
The key will be used for in the CLI for information and as the name of the value in commandObject.options.managed.
All properties on the object is optional.
Example
options: {
feature: { // Will be used as '--feature'
alias: 'f', // Will be used as '-f'
converter: toBoolean,
default: false
description: 'If something should be enabled or not',
validator: isBoolean
}
}
alias
The alias for the option. Should be a single character long.
converter
A converter to be used to convert the input to some other format. Should match the following format (input) => output.
For convenience several types of converters exists in roc that can be imported from roc/converters. See here for a complete list of them along with more information on how they work..
default
The value that the option will hold if nothing is provided to the CLI.
description
A text that describes how the option can be used.
validator
Roc assumes that the validators used is either a RegExp or a function that will return true if it's valid or false/error string if it's not.
For convenience several types of validators exists in roc that can be imported from roc/validators. See here for a complete list of them along with more information on how they work..
A string or a boolean that is to be used if the group already exists. The override will need to be specified to either the extension name that defined it previously or true for always overriding.
What roc settings the command uses, can either be true or an array with strings of the groups to use. Will determine what information the cli outputs, what it parses and what it validates.
Extensions can both modify and remove commands from other extensions. The most common use case is to modify a command that that can simply be done by just letting to Roc manage the merge, will require that a correct value for override is provided.