ArguMints

argumints!

GitHub

travis!

A Powerful Command Line Arguments Preprocessor and Data Mining Tool

Benefits

CLI

argv
opt
flags
argc
keyValue

Data Conversion

convert cli input (argv or keyValue) into JS primitives automatically.

Data Mining

Supports JSON input (in either argv or keyValue formats) which are converted into deep JS Objects, that you can mine.
aggregate file content using the '@' file marker
search argument input using regular expression arguments

Robustness

Uses Underscore JS for mining and copying / filtering / selection techniques.

Usage

Default ArguMints Instance

 
    var myArgs = require('argumints').myArguMints;

Roll your own instance

 
    var lib = require('argumints');
    var myArgs = new lib.ArguMints();

- or -

 
    // the one liner
    var myArgs = new require('argumints').ArguMints();

Basic Examples

NOTE: Examples all from test materials included with ArguMints package!

Options, Flags, and Argv

 
    // cmd line equivalent
    // C:\argumints> node argumints-test.js -xzfv --option arg0 arg1
    // NOTE: verbose is true here because failing a check for an option will 
    // revert to checking for the corresponding flag (usign first char of option name)
    myArgs.retort(["-xz", "--op1","--op2", "arg0", "arg1"]);
    console.log(myArgs.opt("op1"));                      // true
    console.log(myArgs.opt("op2"));                      // true
    console.log(myArgs.flag("x"));                       // true
    console.log(myArgs.flag("z"));                       // true
    console.log(myArgs.argv(0));                         // arg0
    console.log(myArgs.argv(1));                         // arg1
    console.log(myArgs.argc());                          // 2

The Key=Value Store

 
    // cmd line equivalent
    // C:\argumints> node argumints-test.js x=2 y=3
    myArgs.retort(["x=2","y=3"]);
    
    console.log(myArgs.keyValue("x"));
    console.log(myArgs.keyValue("y"));

Advanced Examples

Text File Expansion

 
    // cmd line equivalent
    // C:\argumints> node argumints-test.js @test/testargs2.json
    myArgs.retort(["@test/test.txt"]);
    
    console.log(myArgs.argv(0)); // output the text file content

Test Materials:

test.txt

JSON Expansion in line

JSON File Expansion works like regular File Expansion, with the additional benefit of grafting the resulting JSON Data into either the keyStore, or onto the argv list after expansion, depending on how you structured the input ArguMint (see what I did there??).

    
    // Ex. 1
    // cmd line equivalent
    // C:\argumints> node argumints-test.js '{\"aProperty\":\"testValue\"}'
    myArgs.retort(["{\"aProperty\":\"testValue\"}"]);
    console.log(myArgs.keyValue("aProperty"));               // testValue
    
    // Ex. 2
    myArgs.retort(["key=\"{\"aProperty\":\"testValue\"}\""]);
    console.log(myArgs.keyValue("key").aProperty);           // testValue
    
    // Ex. 3
    // cmd line equivalent
    // C:\argumints> node argumints-test.js [1,2,3,4]
    myArgs.retort(["[1,2,3,4]"]);
    console.log(myArgs.argv(0)[2]);    // 3

JSON File Expansion

 
    // cmd line equivalent
    // C:\argumints> node argumints-test.js @test/testargs1.json
    myArgs.retort(["@test/testargs1.json"]);
    
    console.log(myArgs.keyValue("aNumber"));             // 1
    console.log(myArgs.keyValue("aBool"));               // true
    console.log(myArgs.keyValue("anArray")[2]);          // buckle
    console.log(myArgs.keyValue("anObject").prop);       // aProperty
    console.log(myArgs.keyValue("nullValue"));           // null

Test Materials:

testargs1.json

Recursive JSON File Expansion

 
    // cmd line equivalent
    // C:\argumints> node argumints-test.js @test/testargs2.json
    myArgs.retort(["@test/testargs2.json"]);
    
    console.log(myArgs.keyValue("fromFile1"));
    console.log(myArgs.keyValue("fromFile2"));

Test Materials:

Recursive JSON File Expansion and Mining (Advanced)

    
    // cmd line equivalent
    // C:\argumints> node argumints-test.js @test/testargs3.json
    myArgs.retort(["@test/testargs3.json"]);
    
    console.log(myArgs.keyValue("testArgs1"));
    console.log(myArgs.keyValue("testArgs2"));
    
    // dig in to the values...
    console.log(myArgs.keyValue("testArgs1").aNumber);
    console.log(myArgs.keyValue("testArgs1").anArray[4]);
    console.log(myArgs.keyValue("testArgs2").fromFile1);
    console.log(myArgs.keyValue("testArgs2").fromFile2);

Test Materials: - all files below were loaded because of templatization starting with testargs3.json

Bulk File Expansion

Expansion in Array

 
    ArguMints.verbose = true;
    // append some more 'command line' args.
    myArgs.retort([["@test/test.txt","@test/testargs1.json" /*[,nextFile...]*/]]);
    
    //results
    //test.txt contents loaded into the first array slot.
    //testargs1.json contents loaded, expanded into a JSON object
    //           and placed into the second array slot.
    // the resulting array is placed in the first slot of
    // Argumints.commandTable.argList 
    // (since it has no key=value) format, and is not a flag.

Test Materials:

Expansion as a Key=Value store

 
    ArguMints.verbose = true;
    // append some more 'command line' args.
    myArgs.retort(["x=@test/test.txt","y=@test/testargs1.json"]);
    
    //results
    //test.txt contents are stored in the command table with key 'x'.
    //testargs1.json contents are expanded into a JSON Object, and stored 
    //           in the command table with key 'y'

Test Materials:

Circular Expansion Protection

If you accidentally circularly reference files during an expansion chain, you'll get an exception as show below. This avoids infinite loops and stack overflows when doing really crazy things with ArguMints.

 
    ArguMints.verbose = true;
    myArgs.retort(["x=@test/testarg_infinite.txt"]);
    
    //results
    // file refers to itself by having its contents be a valid url expansion, pointing to its own url.
    // an ArguMintsException is thrown due to Circular Expansion detection.
    // Each Argument is individually protected against circular expansion, so you CAN refer to the same file twice, as long as
    // its under different argument expansions.

Test Materials:

testarg_infinite.txt

Notes on File Expansion

Files are expanded using the '@' character to denote resource location. This is either an absolute or relative local resource. And can be a Windows or Linux Path. Windows paths that have Spaces in the name must be surrounded by quotes!

The Following Formats are acceptable.

 "@C:\Program Files\Blah"
 "@Program Files\Blah"
  @..\another\place\for\file.txt
  @my/file/is/relative.txt
  @/abs/linux/path/or/root/of/curr/win/drive
  @\root\of\curr\win\drive
  @relative\win\path

File contents can be in JSON format, which means their content will be expanded into a JavaScript object. Any properties of said object that are of String type, and follow the file expansion nomenclature will also be expanded. Circular Expansion is not allowed.

Regular Expressions

using '--minty-match-argv' option we perform aggregate data mining and data gathering.

NOTE: Regular expressions must be surrounded by `` backticks to alert ArguMints that this is indeed treated as RegEx (and not a file path like /hey/g).

CLI

 
    // match all instances of the substring 'ord' or 'famil' within the two textfiles provided.
    // matches are cumulative.
    myArgs.retort(
        [
            "--minty-match-argv", 
            "@test/testMatcher.txt", "@test/testMatcher2.txt", 
            "/([A-Za-z0-9]*(ord)[A-Za-z]*)|(famil[A-Za-z0-9]*)/igm"     // <--- NOTE Backticks around RegExp 
        ]                                                               // not rendering in markdown js sections. 
                                                                        // But they're there!!
    );                                                              
                                       
    console.log(myArgs.matches());
    
    // result
    /*
        [ 'ord',
            'word',
            'ordinal',
            'ordinary',
            'ordered',
            'ordained',
            'ford',
            'Nordic',
            'family',
            'Family',
            'families',
            'Familiar',
            'FaMiLy',
            'FaMiLiAr' 
        ]
    */

Test Materials:

From File

You can save a regExp in a file and readily use it as a JavaScript RegExp() object.

 
    // cmd line argumints-test.js --minty-match-argv @test/testMatcher.txt @test/testMatcher2.txt @test/regExpOrd.txt
    myArgs.retort(["--minty-match-argv","@test/regExpOrd.txt", "@test/testMatcher.txt", "@test/testMatcher2.txt"]);
    console.log(myArgs.matches());

Test Materials:

OR USING KEY VALUE STORE

 
    // cmd line argumints-test.js --minty-match-kv  @test/regExp.txt @test/testMatcher.txt @test/testMatcher2.txt
    myArgs.retort(["--minty-match-kv", "search=This is an email: myemail@address.com", "exp=@test/regExp.txt"]);
    console.log(myArgs.matches());
    
    // use the reg ex again and again!
    var regExp = myArgs.keyValue("exp");
    console.log("this is my email: myemail@address.com ok?".match(regExp));          //['myemail@address.com']

Test Materials:

The Options {} Object:

You may pass an options object to ArguMints so it will understand how to retort to your input. Below are the default values used by ArguMints should none be passed in. Also, the myArguMints object

 
    var options = {
        treatBoolStringsAsBoolean:true,         // argv of "true/false" are converted to boolean
        treatNullStringsAsNull:true,            // argv of "null" converted to null
        treatRegExStringsAsRegEx:true,          // argv of "/*.*/g" converted to RegEx("*.*","g");
        treatNumberStringsAsNumbers:true,       // argv of "1" converted to Number(1)
        treatUndefinedStringsAsUndefined:true,  // argv of "undefined" converted to undefined
        enableArgFileLoading:true,              // argv of @filename.txt will load contents of filename.txt (if true) otherwise, no change is made to value.
        ignoreJson:false                        // ignore json formatting and return the literal string value.
    };

Requirements

Node

Installation

npm install argumints

API

Methods

.retort(arrayOfArgs=null, onStartCb=null, onArgExpandCb=null)

Immediately analyzes the input arguments to the current running node process, as well as the additional arrayOfArgs passed in.

params

arrayOfArgs1 - an Array of 'string' values that will be expanded, or null

onStartCb - a function with signature function(userAgs) or null. If specified, the function will be called upon starting the retort, after gathering the input arguments.

onArgExpandCb - a function with signature function(argVal, expandedVal, idx, cnt) or null. If specified, the function will be called upon the processing of each individual argument in arrayOfArgs allowing you to act after each one. The arguments for the function are the original argument, the expanded value, the current argument idx, and,the count of arguments.

You Can call retort() multiple times, with an array of arguments, or with no arguments. Arguments will be treated the same as if they were passed in via command line.

 
    myArgs.retort([1,2,3], onStart, onRetortEach);
    
    function onStart(args){
        console.log("there are: " + args.length + " input args"); // 3    
    }
    function onRetortEach(arg, exp, idx, cnt){
        console.log(arg + "=>" + exp + ", is last one? " + (idx == cnt-1));
    }

getUserArgs()

Returns all arguments passed in originally by the user (prior to expansion)

    
    // node argumints-test.js arg1 arg2 --opt1 --opt2 -fxzy key1=val1 key2=val2
    console.log(myArgs.retort().getUserArgs());
    //output is   [arg1, arg2, --opt1, --opt2, -fxzy, key1=val1, key2=val2]

getScriptArgs()

Returns the script arguments which are either of length 1 or 2, depending on where you are running code from (node command line or windows command line via node executable).

 
    // node argumints-test.js arg1 arg2 --opt1 --opt2 key1=val1 key2=val2
    console.log(myArgs.retort().getScriptArgs());
    //output is   [C:\path\to\node.exe, C:\path\to\script.js]
    // OR         [C:\path\to\node.exe]  when running in Node Command Line.

.argc()

Returns the number of positional user arguments.

.argv(atIndex=null)

Returns the ordered argument passed into the Node Script at the specified index, or all items if the index is not specified.

 
    // node argumints-test.js helpMe! thank you -fx --opt1
    console.log(myArgs.retort().argv(1));            // output: helpMe!
    
    // get them all
    console.log(myArgs.retort().argv());            // output: [helpMe!,thank,you]

.opt(optName)

Returns true if the option at optName was set If no optName is specified, a copy of the internal _opt table is returned for inspection.

 
    // argumints-test --verbose
    console.log(myArgs.retort().opt("verbose"));    // output: true
    
    // get them all
    console.log(myArgs.retort().opt());             // output: {verbose:true}

In addition to using opt as a check, you can specify some 'built in' options to enhance the minty flavour of ArguMints.

Built in options

The Following Options will change the internal behavior of ArguMints

--minty-match-argv
--minty-match-kv
--minty-dump
--minty-append-dup-keys
--minty-op-add
--minty-op-sub
--minty-op-div
--minty-op-mul
--minty-op-sqrt
--minty-op-sqr
--minty-op-ln
--minty-no-cache
--minty-verbose
--minty-clear-opts
--minty-clear-flags

--minty-match-argv

setting this option will match all ordered arguments which aren't RegularExpressions against all ordered arguments which are regular expressions, and aggregate the matches. This is useful when spanning multiple files for patterns (i.e. email addresses, etc).

    
    // the first two positional arguments are files containing text blobs. 
    // the third positional argument is a text file containing a regular expression which
    // will expand to a RegExp instance, and match against the content of the files.
    myArgs.retort(["--minty-match-argv","@test/testMatcher.txt","@test/testMatcher2.txt", "@test/regExpOrd.txt"]);
    var matches = myArgs.matches();

--minty-match-kv

much like minty-match-argv, except this iterates through keyStore values rather than positional arguments. you must only set one of these two keys, they are mutually exclusive.

    
    myArgs.retort(["--minty-match-kv","file1=@test/testMatcher.txt","file2=@test/testMatcher2.txt", "searchRegExp=@test/regExpOrd.txt"]);
    var matches = myArgs.matches();

--minty-dump

Once retort completes, a minty-dump (of the commandTableData) will be displayed on console. smells great...

--minty-append-dup-keys

If the same key is set as a keyValue across one (or multiple) calls to retort(), the results are aggregated. This only works for Array (pushes or concatenates), Number (adds unless otherwise specified) and String types (concatenates)

    
    // node .\argumints-test.js --minty-append-dup-keys "key1=some text" "key1=, more text" "key1=, even more" --minty-dump
    myArgs.retort(["--minty-append-dup-keys", "key1=some text", "key1=", more text", "key1=", even more"]);
    console.log(myArgs.keyValue('key1');
    
    //output: some text, more text, even more
    
    
    // -- OR --
    
    myArgs.retort(["--minty-append-dup-keys", "key1=2","key1=2","key1=6"]);
    
    console.log(myArgs.keyValue('key1'));
    //output: 10
    
    
    // -- OR --
    
    myArgs.retort(["--minty-append-dup-keys", "key1=221","key1=B","key1= Baker Street"]);
    myArgs.keyValue('key1')); // output: 221B Baker Street
    // -- OR --
    
    myArgs.retort(["--minty-append-dup-keys", "key1=0x000000","key1=0xFFF000","key2=0x000FFF"]);
    console.log(myArgs.keyValue('key1') == myArgs.keyValue('key2')); // output: true

Mutually Exclusive Operation Modifiers

--minty-op-add

Use this with --minty-append-dup-keys, this will decide the current operation to be performed. this is enabled by default unless another type is specified.

--minty-op-div

Uses a divide operation when --minty-append-dup-keys is set.

--minty-op-sub

Uses a subtract operation when --minty-append-dup-keys is set.

--minty-op-mul

Uses a multiply operation when --minty-append-dup-keys is set.

--minty-op-sqrt

Uses a square root operation when --minty-append-dup-keys is set.

--minty-op-sqr

Uses a square operation when --minty-append-dup-keys is set.

--minty-op-ln

Uses a natural log operation when --minty-append-dup-keys is set.

--minty-op-tan

Uses a tangent (Math.tan(argAt)) operation--minty-append-dup-keys is set.

--minty-op-atan

Uses a tangent (Math.atan(argAt)) operation--minty-append-dup-keys is set.

--minty-op-sin

Uses a tangent (Math.sin(argAt)) operation--minty-append-dup-keys is set.

--minty-op-cos

Uses a tangent (Math.cos(argAt)) operation--minty-append-dup-keys is set.

--minty-op-exp

Agreggates (Math.exp(argAt)) or e^x operations on a key if set one or more times and --minty-append-dup-keys is set.

--minty-no-cache

File contents are not cached. Normally expanding a file will cache the file content, so further expansions in arguments using the same file will be faster. However, if your script modifies the file between retorts, or even while retorting, you can set this option to force it to reload upon each expansion request

 
    myArgs.retort(["--minty-no-cache", "@test/test1.txt", "key1="@test/test1.txt", "key2="@test/test1.txt"]);
    //result: test1.txt is reloaded 3 times

--minty-clear-opts and --minty-clear-flags

This allows you to change how minty works during a retort. For example, within the expansion callback (3rd parameter) if this is set, your flags/options are wiped clean and the next iteration will result in different behavior. Further more, you can push or insert arguments into minty as it is retorting as long as they are inserted after the current processing point.

 
    myArgs.retort(["--minty-clear-opts", "--opt"], null, function(a,e,i,c){
        // opts are now clear
        myArgs.insertArg("--minty-clear-opts");
        myArgs.pushArg("--opt2");
    });

.flag(flagName=undefined)

returns true if a flag by name is enabled. Flag names are a single character. If no flagName is passed, a copy of the internal _opt table is returned for inspection.

 
    // argumints-test --verbose
    console.log(myArgs.retort().matches());            // true

.keyValue(key=undefined)

Returns the value stored under key in the keyStore. The Key Store is populated using the format key=value when passing in arguments. you can also specify files, i.e. key=@test/test.txt If no key is specified, a copy of the entire keyStore is returned for your inspection.

 
    // argumints-test x=2
    console.log(myArgs.retort().keyValue("x"));            // 2

.matches(start=-1,end=-1)

Returns any matches after a retort with a regular expression and having --minty-match-argv or --minty-match-kv enagbled. if start or end are specified, it will return a 'slice' of the matches contained within.

 
    // argumints-test --minty-verbose --minty-match-argv @test/testMatcher2.txt @test/regExpOrd.txt
    console.log(myArgs.retort().matches());            // true

.insertArg(arg, xArgsFromHere);

This allows you to insert arguments directly in front of the current retort position. This means you can do fun things like factorials. NOTE: This is not meant to replace good old native code doing math, but its great for scripting and doing dynamic templated calculations and datamining.

 
     // the factorial function, ArguMints style!
    var fact = 1;
    defaultMints.retort( [3],null, function(arg, exp, idx, cnt){
        if( typeof exp == 'number' && exp > 0){
            fact *= exp;
            defaultMints.insertArg(arg-1, 0);
        }
    });
    
    console.log("Fact: " + fact);           // output 6

.pushArg(moreArgs)

Pushes additional arguments onto the user argument queue. This can only be done during a retort, thus you must call this from the retort callback you pass into retort. be careful that you have a way to stop pushing arguments to avoid an infinitely growing args list.

 
    // the summation function, ArguMints style!
    var sum = 0;
    var t = 15;  // first x numbers
    defaultMints.retort( [1],null, function(arg, exp, idx, cnt){
        if( typeof exp === 'number' ){
            sum += exp;
            
            t--;
            if(t > 0){
                defaultMints.pushArg(exp+1);
            }
        }
    });
    
    console.log("Sum: " + sum);

.reset(newOptions=undefined)

Resets the ArguMints instance. You must call retort() again to re-parse the argument inputs, however, this gives you the option to append new arguments onto the instance.

 
    // reset all data, keep current options
    myArgs.reset();
    
    // reset all data, and overwrite new options
    myArgs.reset({ignoreJson:true});

License

The MIT License (MIT)

Copyright (c) 2016 Decoded4620

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

argumints

ArguMints

Benefits

CLI

Data Conversion

Data Mining

Robustness

Usage

Default ArguMints Instance

Roll your own instance

Basic Examples

Options, Flags, and Argv

The Key=Value Store

Advanced Examples

Text File Expansion

JSON Expansion in line

JSON File Expansion

Recursive JSON File Expansion

Recursive JSON File Expansion and Mining (Advanced)

Bulk File Expansion

Expansion in Array

Expansion as a Key=Value store

Circular Expansion Protection

Notes on File Expansion

Regular Expressions

CLI

From File

OR USING KEY VALUE STORE

The Options {} Object:

Requirements

Installation

API

Methods

.retort(arrayOfArgs=null, onStartCb=null, onArgExpandCb=null)

params

getUserArgs()

getScriptArgs()

.argc()

.argv(atIndex=null)

.opt(optName)

Built in options

--minty-match-argv

--minty-match-kv

--minty-dump

--minty-append-dup-keys

--minty-op-add

--minty-op-div

--minty-op-sub

--minty-op-mul

--minty-op-sqrt

--minty-op-sqr

--minty-op-ln

--minty-op-tan

--minty-op-atan

--minty-op-sin

--minty-op-cos

--minty-op-exp

--minty-no-cache

--minty-clear-opts and --minty-clear-flags

.flag(flagName=undefined)

.keyValue(key=undefined)

.matches(start=-1,end=-1)

.insertArg(arg, xArgsFromHere);

.pushArg(moreArgs)

.reset(newOptions=undefined)

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads