1 2 node-getopt 3 ============== 4 5 Overview 6 -------- 7 8 node-getopt is a Node.js module providing an interface to the POSIX-defined 9 getopt() function, a general-purpose command line parser that follows the POSIX 10 guidelines for command-line utilities. Using these guidelines encourages 11 common conventions among applications, including use of: 12 13 o short option names (e.g., "-r") 14 o options with arguments (e.g., "-f filename or -ffilename") 15 o chaining short option names when options have no arguments (e.g., "-ra") 16 17 This implementation mirrors the Solaris getopt() implementation and supports 18 long option names (e.g., "--recurse"), potentially with values specified using 19 "=" (e.g., "--file=/path/to/file"). 20 21 Unlike other option parsers available for Node.js, the POSIX getopt() interface 22 supports using the same option multiple times (e.g., "-vvv", commonly used to 23 indicate level of verbosity). 24 25 For further reference on the relevant POSIX standards, see the following: 26 27 http://pubs.opengroup.org/onlinepubs/009695399/functions/getopt.html 28 http://pubs.opengroup.org/onlinepubs/009695399/utilities/getopts.html 29 30 The Utility Syntax Guidelines are described here: 31 32 http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html 33 34 35 Status 36 ------ 37 38 This module is considered complete except that 39 40 o test coverage is pretty minimal 41 o npm install has not been tested 42 o the source is not javascriptlint-clean 43 44 There are no known bugs, but the module has not been extensively tested. 45 46 47 Platforms 48 --------- 49 50 This module should work on all platforms that support node.js. The module is 51 tested on MacOS X 10.6.5 and OpenSolaris based on build 111b and Illumos build 52 147. 53 54 55 Installation 56 ------------ 57 58 As an npm package, node-getopt is installed in the usual way: 59 60 % npm install posix-getopt 61 62 63 API 64 --- 65 66 ### `new getopt.BasicParser(optstring, argv)` 67 68 Instantiates a new object for parsing the specified arguments using the 69 specified option string. This interface is closest to the traditional getopt() 70 C function. Callers first instantiate a BasicParser and then invoke the 71 getopt() method to iterate the options as they would in C. (This interface 72 allows the same option to be specified multiple times.) The first two arguments 73 in "argv" are ignored, since they generally denote the path to the node 74 executable and the script being run, so options start with the third element. 75 76 The option string consists of an optional leading ":" (see below) followed by a 77 sequence of option-specifiers. Each option-specifier consists of a single 78 character denoting the short option name, optionally followed by a colon if the 79 option takes an argument and/or a sequence of strings in parentheses 80 representing long-option aliases for the option name. 81 82 Example option strings: 83 ':r' Command takes one option with no args: -r 84 ':ra' Command takes two option with no args: -r and -a 85 ':raf:' Command takes two option with no args: -r and -a 86 and a single option that takes an arg: -f 87 ':f:(file)' Command takes a single option with an argument: -f 88 -f can also be specified as --file 89 90 The presence of a leading colon in the option string determines the behavior 91 when an argument is not specified for an option which takes an argument. See 92 getopt() below. Additionally, if no colon is specified, then error messages are 93 printed to stderr when invalid options, options with missing arguments, or 94 options with unexpected arguments are encountered. 95 96 97 ### `parser.optind()` 98 99 Returns the next argv-argument to be parsed. When options are specified as 100 separate "argv" arguments, this value is incremented with each option parsed. 101 When multiple options are specified in the same argv-argument, the returned 102 value is unspecified. This matches the variable "OPTIND" from the POSIX 103 standard, but is read-only. (If you want to reset OPTIND, you must create a new 104 BasicParser instance.) This is most useful after parsing has finished to 105 examine the non-option arguments. 106 107 This value starts at "2" as described under "Departures from POSIX" below. 108 109 110 ### `parser.getopt()` 111 112 Returns the next argument specified in "argv" (the object's constructor 113 argument). The returned value is either undefined or an object with at least 114 the following members: 115 116 option single-character option name 117 118 The following members may also be present: 119 120 optarg argument value, if any 121 122 optopt option character that caused the error, if any 123 124 error if true, this object represents an error 125 126 This function scans "argv" starting at the current value of "optind" and returns 127 an object describing the next argument based on the following cases: 128 129 o If the end of command line arguments is reached, an undefined value is 130 returned. The end of arguments is signified by a single '-' argument, a 131 single '--' argument, an argument that's neither an option nor a previous 132 option's argument, the end of argv, or an error. 133 134 o If an unrecognized command line option is found (i.e. an option character 135 not defined in "optstring"), the returned object's "option" member 136 is just "?". "optopt" is set to the unrecognized option letter. "error" 137 is set to a true value. 138 139 o If a known command line option is found and the option takes no arguments 140 then the returned object's "option" member is the option's short name 141 (i.e. the single character specifier in "optstring"). 142 143 o If a known command line option is found and that option takes an argument 144 and the argument is also found, then the returned object's "option" 145 member is the option's short name and the "optarg" member contains the 146 argument's value. 147 148 o If a known command line option is found and that option takes an argument 149 but the argument is not found, then the returned object's "option" member 150 is "?" unless the first character of "optstring" was a colon, in which 151 case the "option" member is set to ":". Either way, the "optopt" member 152 is set to the option character that caused the error and "error" is set to 153 a true value. 154 155 156 Departures from POSIX 157 -------- 158 159 o Global state in the C implementation (e.g., optind, optarg, and optopt) is 160 encapsulated in the BasicParser object. optind is available as a method 161 call on the parser object. optarg and optopt are returned directly by 162 getopt(). 163 164 o Rather than returning an integer or character, getopt() returns an object 165 with the "option" field corresponding to the processed option character 166 and possibly the additional "optarg" and "optopt" fields. If an error 167 occurs on a particular option, "error" is also set. If an error occurs on 168 no particular option or if the end of input is encountered, undefined is 169 returned. 170 171 o Long option forms are supported as described above. This introduces an 172 additional error case which is where an argument of the form 173 --option=value is encountered, where "option" does not take a value. 174 175 o POSIX starts "optind" at 1, since argv[0] is generally the name of the 176 command and options start at argv[1]. This implementation starts "optind" 177 at 2, since argv[0] is generally the path to the node binary and argv[1] 178 is the path to the script, so options start with argv[2]. 179 180 181 Examples 182 -------- 183 184 ### Example 1: simple short options 185 186 var mod_getopt = require('getopt') 187 var parser, option; 188 189 parser = new mod_getopt.BasicParser('la', 190 ['node', 'script', '-l', '-a', 'stuff']); 191 while ((option = parser.getopt()) !== undefined && !option.error) 192 console.error(option); 193 194 ### Example 2: invalid option specified 195 196 var mod_getopt = require('getopt') 197 var parser, option; 198 199 parser = new mod_getopt.BasicParser('la', 200 ['node', 'script', '-l', '-b', 'stuff']); 201 while ((option = parser.getopt()) !== undefined && !option.error) 202 console.error(option); 203 console.error(option); 204 205 ### Example 3: long options 206 207 var mod_getopt = require('getopt') 208 var parser, option; 209 210 parser = new mod_getopt.BasicParser('lar(recurse)', 211 ['node', 'script', '-l', '--recurse', 'stuff']); 212 while ((option = parser.getopt()) !== undefined && !option.error) 213 console.error(option); 214 215 ### Example 4: options with arguments 216 217 var mod_getopt = require('getopt') 218 var parser, option; 219 220 parser = new mod_getopt.BasicParser('f:lad:', 221 ['node', 'script', '-l', '-f', 'filename', '-dtype', 'stuff']); 222 while ((option = parser.getopt()) !== undefined && !option.error) 223 console.error(option); 224 225 ### Example 5: options with missing arguments 226 227 var mod_getopt = require('getopt') 228 var parser, option; 229 230 parser = new mod_getopt.BasicParser('f:la', 231 ['node', 'script', '-l', '-a', '-f']); 232 while ((option = parser.getopt()) !== undefined && !option.error) 233 console.error(option); 234 console.error(option); 235 236 ### Example 6: options specified multiple times 237 238 var mod_getopt = require('getopt') 239 var parser, option; 240 241 parser = new mod_getopt.BasicParser('la', 242 ['node', 'script', '-l', '-a', '-l']); 243 while ((option = parser.getopt()) !== undefined && !option.error) 244 console.error(option);