# getopt # Description # Usually already loaded, otherwise use "require('utility/getopt')". # Parameters are described below, resulting object{} will be set (or (Object.merge())'d # if already existing) in 'process.args', which also includes the following 'RESERVED'- # elements: [ ARGV, KEY, INDEX, ITEM, GROUP, VECTOR, COUNT, CALL, RESULT, RESERVED ]; .. # By default it'll use (if 'process.args' already exists) 'process.args.ARGV' as input # command line arguments, so multiple 'getopt()'-calls will perfectly work, too! ;-) # Multiple calls via 'getopt.prepare()' (same arguments as 'getopt()' itself) are also # possible.. for a description see below. # Getopt 'VECTOR' key elements: .. # long normally the vector key itself, but can also be defined this way. # short these are the SHORT keys with '-' prefix (instead of LONG '--'). # env checks the environment variables for the key you specify here. set to _env value if unset, or sets _env '.. env-key=value' (w/o dash). # args how many arguments for the getopt item? BTW: a NEGATIVE value will set Math.abs()-value, BUT additionally it'll set '.last = true'. The 'last'-feature is aware of multiple .args, btw.. If no or too less values given, the rest will be filled by (DEFAULT_FILL) (by default (undefined)); # default by default values are always set to this value (if not overridden). # undefined like default, but only if really not being set in the command line. # null also like default, but only set to the value if key available w/o value. # help some description for your cmdline switches.. shown when help called.. Can be a String, but can also be an Array which fits to 'String.printf()'! ^_^ # call functions or strings for 'getopt.call[*]'.. will only be called if it's vector item key is defined, and if (result !== undefined) => set it. # last when multiple values are defined in an array: (bool) or int-index (see ..getIndex()). # parse String.parse() can be called for values, to bring them to their js objects or parse lists! # list 'abc,def' is a list.. e.g. .. by default the same value as 'parse'. # group Group elements together in 'result.GROUP{}'. Maybe useful (test case: 'test.js/util/getopt/group.js').. # unescape Defaults to .parse.. see 'String.prototype.unescapeAll()'.. # unescapeHex Defaults to .parse.. String.prototype.unescapeHex(). # unescapeCTRL Defaults to .parse.. String.prototype.unescapeCTRL(). # unescapeISO Defaults to .parse.. String.prototype.unescapeISO(). # unescapeC Defaults to .parse.. String.prototype.unescapeC(). # Usually called 'getopt()' function base parameters (recommendation is to use at least the first argument): ... # _vector An object with all getopt keys and their options. See 'getopt.check()' and the passage above. # _last Can be an Integer or a Boolean type, and is used as default for the 'last' vector element (see above). # _parse Default value for all vector items w/o own .parse Boolean. # _parse_argv Additionally, to distinct vector items from rest cmdline argv[].. defaults to _parse. # _list Parsing lists/arrays by ',' separator? # _list_argv Nearly same as _parse_argv, but for lists.. defaults to _list. # _call_func The default for all '.call' getopt vector items.. so here's a global "function" (or string). # _argv Using 'process.ARGV[]' if not already 'process.args[.ARGV]' has been defined before(!). # Multiple calls via 'getopt.prepare()'.. # You can combine multiple getopt vectors and calls via 'getopt.prepare()', whereas your last real 'getopt()' # (possibly even w/o vector or any other argument) will 'flush()' all previous ones. # The vectors are combined via 'Object.assign()'. Your last real _argv[]-Array is chosen (if any), and also the # last _parse_argv and _list_argv parameters are taken. # Intention was mainly that I could use a base 'main.js' (for my 'baseutils') with defined getopt({ json }), # and to extend this in every concrete 'utils/*.js' (as every util has special cmdline args, but all utils have # --help output and --json format output mode). # See 'test.js/util/getopt/multiple-calls.js'. And see 'getopt.reset()' and more in 'lib.js/util/getopt.js'! ;-) # HELP # By default (see DEFAULT_HELP), and ONLY IF NOT ALREADY defined something similar (see 'vectorContainsHelp()'), # the '--help' or '-?' vector items will be enabled. # I've included a sweet looking help output for this reason. # If your vector items contain the 'help' attribute, also this one is printed in the help output (as description); # whereas you can either set a string for this, or even an array, so 'String.printf()' is being used (which mainly # makes colorization mich easier, etc.). # Additional explanation # (describe the possibilities of cmdline arguments in here) //TODO/. # tests / examples # see 'test.js/util/getopt/'; and take a look at an use case for the 'GROUP' feature: 'test.js/util/getopt/group.js', # the 'RESULT' feature at 'test.js/util/getopt/RESULT.js', and the 'CALL' feature at 'test.js/util/getopt/calls.js'.. # TODO # more description in here, etc... ETC. PP.! ^_^