ArguMints
GitHub
A Powerful Command Line Arguments Preprocessor and Data Mining Tool
Benefits
CLI
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 -
var myArgs = new require('argumints').ArguMints();
Basic Examples
NOTE: Examples all from test materials included with ArguMints package!
Options, Flags, and Argv
myArgs.retort(["-xz", "--op1","--op2", "arg0", "arg1"]);
console.log(myArgs.opt("op1"));
console.log(myArgs.opt("op2"));
console.log(myArgs.flag("x"));
console.log(myArgs.flag("z"));
console.log(myArgs.argv(0));
console.log(myArgs.argv(1));
console.log(myArgs.argc());
The Key=Value Store
myArgs.retort(["x=2","y=3"]);
console.log(myArgs.keyValue("x"));
console.log(myArgs.keyValue("y"));
Advanced Examples
Text File Expansion
myArgs.retort(["@test/test.txt"]);
console.log(myArgs.argv(0));
Test Materials:
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??).
myArgs.retort(["{\"aProperty\":\"testValue\"}"]);
console.log(myArgs.keyValue("aProperty"));
myArgs.retort(["key=\"{\"aProperty\":\"testValue\"}\""]);
console.log(myArgs.keyValue("key").aProperty);
myArgs.retort(["[1,2,3,4]"]);
console.log(myArgs.argv(0)[2]);
JSON File Expansion
myArgs.retort(["@test/testargs1.json"]);
console.log(myArgs.keyValue("aNumber"));
console.log(myArgs.keyValue("aBool"));
console.log(myArgs.keyValue("anArray")[2]);
console.log(myArgs.keyValue("anObject").prop);
console.log(myArgs.keyValue("nullValue"));
Test Materials:
Recursive JSON File Expansion
myArgs.retort(["@test/testargs2.json"]);
console.log(myArgs.keyValue("fromFile1"));
console.log(myArgs.keyValue("fromFile2"));
Test Materials:
Recursive JSON File Expansion and Mining (Advanced)
myArgs.retort(["@test/testargs3.json"]);
console.log(myArgs.keyValue("testArgs1"));
console.log(myArgs.keyValue("testArgs2"));
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;
myArgs.retort([["@test/test.txt","@test/testargs1.json" ]]);
Test Materials:
Expansion as a Key=Value store
ArguMints.verbose = true;
myArgs.retort(["x=@test/test.txt","y=@test/testargs1.json"]);
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"]);
Test Materials:
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
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"
]
);
console.log(myArgs.matches());
Test Materials:
From File
You can save a regExp in a file and readily use it as a JavaScript RegExp() object.
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
myArgs.retort(["--minty-match-kv", "search=This is an email: myemail@address.com", "exp=@test/regExp.txt"]);
console.log(myArgs.matches());
var regExp = myArgs.keyValue("exp");
console.log("this is my email: myemail@address.com ok?".match(regExp));
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,
treatNullStringsAsNull:true,
treatRegExStringsAsRegEx:true,
treatNumberStringsAsNumbers:true,
treatUndefinedStringsAsUndefined:true,
enableArgFileLoading:true,
ignoreJson:false
};
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");
}
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)
console.log(myArgs.retort().getUserArgs());
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).
console.log(myArgs.retort().getScriptArgs());
.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.
console.log(myArgs.retort().argv(1));
console.log(myArgs.retort().argv());
.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.
console.log(myArgs.retort().opt("verbose"));
console.log(myArgs.retort().opt());
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).
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)
myArgs.retort(["--minty-append-dup-keys", "key1=some text", "key1=", more text", "key1=", even more"]);
console.log(myArgs.keyValue('key1');
myArgs.retort(["--minty-append-dup-keys", "key1=2","key1=2","key1=6"]);
console.log(myArgs.keyValue('key1'));
myArgs.retort(["--minty-append-dup-keys", "key1=221","key1=B","key1= Baker Street"]);
myArgs.keyValue('key1'));
myArgs.retort(["--minty-append-dup-keys", "key1=0x000000","key1=0xFFF000","key2=0x000FFF"]);
console.log(myArgs.keyValue('key1') == myArgs.keyValue('key2'));
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"]);
--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){
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.
console.log(myArgs.retort().matches());
.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.
console.log(myArgs.retort().keyValue("x"));
.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.
console.log(myArgs.retort().matches());
.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.
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);
.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.
var sum = 0;
var t = 15;
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.
myArgs.reset();
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.