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.
~$ npm install --save clitoris
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"
// }
// }
// }
// }
//
Type: {Class}
Description: The main (and unique) class of the API.
It can be accessed like this:
const Clitoris = require("clitoris").Clitoris;
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:
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.
Numbers
can be generated with :number:1
or :n:-1.55
.
Negative and decimal numbers are also valid values.
Booleans
can only be generated by these 4 tokens:
:boolean:true
:b:true
:boolean:false
:b:false
Null
value can only be generated by this token: :null:
.
Undefined
value can only be generated by these 2 tokens:
:undefined:
:u:
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.
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.
Type: {Function}
Description: This method does the same as the static Clitoris.parse
.
Accessibility: **Internals**
Accessibility: **Internals**
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
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.