Converters.md

Converters

Roc offers some converters that can be used to make sure some input has the correct form when using the command line. This since the command line will most often give string values for everything and sometimes that is not what is desired.

Table of Contents

• Where are converters used?
  • Commands
  • Meta Settings
• Default Converters
  • automatic
  • convert
  • toArray
  • toBoolean
  • toInteger
  • toObject
  • toRegExp
  • toString
• Custom Converters

Where are converters used?

Converters are used in two places in Roc:

1. Commands
2. Meta Settings

Commands

commands: {
    build: {
        // ...
        arguments: [{
            // ...
            default: 'Hello World',
            validator: isString,
            converter: toString
        }],
        options: [{
            // ...
            default: false,
            validator: isBoolean,
            converter: toBoolean
        }]
    }
}

The following strategy is used when trying to find the converter:

1. Use the converter that is defined directly on the object from the property.
2. Use the validator and try to find a converter from it since infoObject can return a converter.
3. Use the default value if present together with the automatic converter.
4. Do not convert.

This means that it is not mandatory to define a converter and Roc will do the best it can to select a fitting one if none is provided.

Meta Settings

settings: {
    build: {
        someValue: {
            // ...
            validator: isString,
            converter: toString
        }
    }
}

The following strategy is used when trying to find the converter:

1. Use the converter that is defined directly on the object.
2. Use the validator and try to find a converter from it since infoObject can return a converter.
3. Use the value that is defined in the non meta settings together with the automatic converter.

This means that it is not mandatory to define a converter and Roc will do the best it can to select a fitting one if none is provided.

Default Converters

All converters will have the same syntax.

// a converter
(input) => convertedValue

automatic

import { automatic } from 'roc/converters';

automatic(value) => converter

Takes in a value and returns a converter. Will most likely not be needed to be defined manually.

convert

import { convert } from 'roc/converters';

convert(...converters) => converter

Takes in a number of converters and returns a single converter.

Will convert to the first valid converter you pass to the function or undefined.

Example

import { convert, toBoolean, toInteger } from 'roc/converters';

convert(toBoolean, toInteger) => converter

toArray

import { toArray } from 'roc/converters';

toArray(/* possible converter */) => converter

Take in a possible converter and returns a converter that will transform the input to an array.

Example

import { toArray, toBoolean } from 'roc/converters';

// Will convert input to an array of booleans
toArray(isBoolean) => converter

toBoolean

import { toBoolean } from 'roc/converters';

Will convert the input to a boolean if possible or return undefined.

toInteger

import { toInteger } from 'roc/converters';

Will convert the input value to a number or return NaN if not valid.

toObject

import { toObject } from 'roc/converters';

Will convert the input value to an object by trying to do JSON.parse on it.

toRegExp

import { toObject } from 'roc/converters';

Will convert the input value to a RegExp.

toString

import { toString } from 'roc/converters';

Will convert the input value to a string.

Custom Converters

It is of course also possible to define custom converters if one of the default ones does not cover the specific use case.

A converter is just a function that takes in one value and returns the correct value. Custom converters can be combined with default converters for more complex behavior.

Example

import { convert, toBoolean } from 'roc/converters';

const customConverter => (input) => {
    if (input === 'something') {
        return true;
    }

    return false;
};

convert(customConverter, toBoolean) => converter