clitoris

Tool to bring complex parametrization to your CLI-based applications.

A simple utility that transforms (console-friendly) strings or (JavaScript) arrays of strings into complex JavaScript data: objects, arrays, numbers, strings, booleans (, null or undefined), nested or not.

1. Installation

~$ npm install --save clitoris

2. Usage

This is a full example, and it could be written in 1 line, as the command-line interface usually requires:

var data = require("clitoris").Clitoris.parse(`
{
 @key1 [ :string:value1 ":s:value 2 with spaces" ]
 @key2 [ :boolean:true :b:false ]
 @key3 [ :number:100 :n:-100.99 ]
 @key4 :null:
 @key5 [ :undefined: :u: ]
 @key6 [ [ [ :n:1 ] ] ]
 @key7 { @key7.1 { @key7.1.1 { "@key7.1.1.1 with spaces" "simple string" } }
}
`);

console.log(data);

// 
// data is now:
// 
// {
//   key1: [ "value1", "value 2 with spaces" ],
//   key2: [ true, false ],
//   key3: [ 100, -100.99 ],
//   key4: null,
//   key5: [ undefined, undefined ],
//   key6: [ [ [ 1 ] ] ],
//   key7: {
//     "key7.1": {
//       "key7.1.1": {
//         "key7.1.1.1 with spaces": "simple string"
//       }
//     }
//   }
// }
// 

3. API Reference

Clitoris

Type: {Class}

Description: The main (and unique) class of the API.

It can be accessed like this:

const Clitoris = require("clitoris").Clitoris;

Clitoris.parse(input:string|array)

Type: {Function}

Parameter: input {String | Array}. Data to be parsed. It can be a string, or an array of strings.

Syntax: The Clitoris.parse(~) parameter accepts a very specific syntax, but it will be enough to create rich JSON data for command-line applications.

First, the method will tokenize the string as a normal command-line interface from a console would do.

Then, the resulting array (which can be directly provided, instead of a String), which is simply the provided text but tokenized, will be parsed following the next syntax.

Syntax:

1. Strings = :string:~ | :s:~ | default

Strings can be generated with :string:someText or :s:whatever.

For spaced texts, one can wrap the token with ", like so: ":string:some spaced text" or ":s:some spaced text".

By default, any token that does not fit other type, will be automatically converted into String too.

That means that, for example, the token "This is some text" will be converted into String directly.

2. Numbers = :number:~ | :n:~

Numbers can be generated with :number:1 or :n:-1.55.

Negative and decimal numbers are also valid values.

3. Booleans = :boolean:true | :b:true | :boolean:false | :b:false

Booleans can only be generated by these 4 tokens:

:boolean:true

:b:true

:boolean:false

:b:false

4. Null = :null:

Null value can only be generated by this token: :null:.

5. Undefined = :undefined: | :u:

Undefined value can only be generated by these 2 tokens:

:undefined:

:u:

6. Arrays = [ value value ... ]

Arrays can be generated when a [ and later and coherently a ] are provided.

By "coherently", it means that if you open an array, you have to close it, and if you open 2 arrays, you have to close 2 arrays, and so on.

This implies that you can nest arrays.

The values of the array are directly specified inside of the [ and ]. Here, you can provide any type of value, so nested arrays are also valid, or mixing arrays and objects.

7. Objects = { @key value @key value ... }

Object can be generated when a { and later and coherently a } are provided.

By "coherently", it means that if you open an object, you have to close it, and if you open 2 objects, you have to close 2 objects, and so on.

This implies that you can nest objects.

The values of the object follow this simple syntax:

{ @key value @key value @key value ... }

Through @key we define the next property we want to set in the object. To provide spaced keys, wrap the key in ", like so: "@This is a spaced key".

Through value we define the next value of the previously specified property we want to put in the object. Here, you can provide any type of value, so nested objects are also valid, or mixing arrays and objects.

Returns: {Any}. Returns the input, but parsed.

Description: Takes a string (or an array of strings, like the one found at process.argv by default in Node.js), and returns the same, but transformed into real JavaScript data.

Clitoris#parse(input:string|array)

Type: {Function}

Description: This method does the same as the static Clitoris.parse.

Clitoris.tipifyValues(input:array)

Accessibility: **Internals**

Clitoris.changeValue(token:string, currentIndex:number, tokenList:array)

Accessibility: **Internals**

4. Tests and documentation

To run the tests and generate the corresponding code coverage analysis, you can:

~$ npm run test

To generate the new documentation, you can:

~$ npm run docs

5. Conclusion

If you want to have a flexible command-line-interface based application, with rich parametrization, and based on minimalistic approaches, this is a great tool for you.