Commits

Mathias Panzenböck committed d08888d

forgot to add README.md

  • Participants
  • Parent commits c7ee703

Comments (0)

Files changed (1)

parseopt/README.md

+parseopt
+========
+
+Parseopt is a command line optionparser loosely inspired by Python's optparse
+module. This module was written for node.js but should work with any other
+JavaScript framework. Only when some certain parameters are not provided,
+parseopt uses node.js specific code in order to lookup meaningful defaults.
+
+Used node.js API:
+
+ * `process.argv`: array of strings
+ * `process.stdout`: object with a `write` method that accepts a string argument
+ * `process.exit`: method that accepts a number argument
+
+See the demo folder the end of this file for example usage.
+
+API Reference
+-------------
+
+### Option Definition ###
+
+Option definitions are objects that specify an option. You use them to specify
+the name(s), type and severall parameters of an option.
+
+Option types:
+
+ * `float`
+ * `integer`
+ * `string`
+ * `boolean`
+ * `object`
+ * `option`
+ * `enum`
+ * `flag`
+ * `record`
+ * `custom`
+
+Option definition object:
+
+	{
+	   // Only when passed to the OptionParser constructor:
+	   name:        string or array
+	   names:       string or array, alias of name
+	                Only one of both may be used at the same time.
+
+	                Names can be long options (e.g. '--foo') and short options
+	                (e.g. '-f'). The first name is used to indentify the option.
+	                Names musst be unique and may not contain '='.
+
+	                Short options may be combined when passed to a programm. E.g.
+	                the options '-f' and '-b' can be combined to '-fb'. Only one
+	                of these combined options may require an argument.
+
+	                Short options are separated from ther arguments by space,
+	                long options per '='. If a long option requires an argument
+	                and none is passed using '=' it also uses the next commandline
+	                argument as it's argument (like short options).
+
+	                If '--' is encountered all remaining arguments are treated as
+	                arguments and not as options.
+
+	   // General fields:
+	   target:      string, per deflault inferred from first name
+	                This defines the name used in the returned options object.
+	                Multiple options may have the same target.
+	   default:     any, default: undefined
+	                The default value associated with a certain target and is
+	                overwritten by each new option with the same target.
+	   type:        string, default: 'string', see below
+	   required:    boolean, default: false
+	   redefinable: boolean, default: true
+	   help:        string, optional
+	   details:     array, optional
+	                short list of details shown in braces after the option name
+	                e.g. integer type options add 'base: '+base if base !== undefined
+	   metavar:     string or array, per deflault inferred from type
+	   onOption:    function (value) -> boolean, optional
+	                Returning true canceles any further option parsing
+	                and the parse() method returns null.
+
+	   // Type: string  (alias: str)
+	   // Type: boolean (alias: bool)
+	   // Type: object  (alias: obj)
+
+	   // Type: integer (alias: int)
+	   min:         integer, optional
+	   max:         integer, optional
+	   NaN:         boolean, default: false
+	   base:        integer, optional
+
+	   // Type: float   (alias: number)
+	   min:         float, optional
+	   max:         float, optional
+	   NaN:         boolean, default: false
+
+	   // Type: flag
+	   value:       boolean, default: true
+	   default:     boolean, default: false
+
+	   // Type: option
+	   value:       any, per default inferred from first name
+
+	   // Type: enum
+	   ignoreCase:  boolean, default: true
+	   values:      array or object where the user enteres the field name of
+	                the object and you get the value of the field
+
+	   // Type: record
+	   create:      function () -> object, default: Array
+	   args:        array of type definitions (type part of option definitions)
+
+	   // Type: custom
+	   argc:        integer, default: -1
+	                Number of required arguments.
+	                -1 means one optional argument.
+	   parse:       function (string, ...) -> value
+	   stringify:   function (value) -> string, optional
+	}
+
+#### Type: `float` ####
+
+**Arguments:** `1`
+
+**Alias:** `number`
+
+Parse a `float` option argument. You can optionally specify `min` and `max`
+parameters to the option definition in order to limit the range of allowed
+values. Using the boolean `NaN` parameter it can be controlled if `NaN'
+values are allowed (default: `false`).
+
+Example:
+
+	parser.add(['-n','-d','--float'], {
+		type: 'float',
+		min: 0
+	});
+
+#### Type: `integer` ####
+
+**Arguments:** `1`
+
+**Alias:** `int`
+
+Parse an `integer` option argument. You can optionally specify `min` and `max`
+parameters to the option definition in order to limit the range of allowed
+values. Using the boolean `NaN` parameter it can be controlled if `NaN'
+values are allowed (default: `false`). The `base` parameter controlls the
+base of the parsed number. Per default integers are parsed like JavaScript
+integer lieterals, meaning a `0x` prefix specifies a hexadecimal number, a
+`0` prefix an octal number and otherwise it is interpreted as a decimal number.
+
+Example:
+
+	parser.add('--int32', {
+		type: 'integer',
+		min: -2147483648,
+		max: 2147483647,
+		metavar: 'INT32'
+	});
+
+#### Type: `string` ####
+
+**Arguments:** `1`
+
+**Alias:** `str`
+
+This is the default type. It doesn't do any parsing but just passes through
+the string option argument.
+
+Example:
+
+	parser.add('--foo', {type: 'string'});
+
+#### Type: `boolean` ####
+
+**Arguments:** `1`
+
+**Alias:** `bool`
+
+Parse a `boolean` option argument.
+
+Values accepted as `true` (case is ignored):
+
+ * `true`
+ * `on`
+ * `1`
+ * `yes`
+
+Values accepted as `false` (case is ignored):
+
+ * `false`
+ * `off`
+ * `0`
+ * `no`
+
+Example:
+
+	parser.add('--bar', {type: 'boolean'});
+
+#### Type: `object` ####
+
+**Arguments:** `1`
+
+**Alias:** `obj`
+
+Parse option argument as JSON string.
+
+Example:
+
+	parser.add('--obj', {
+		type: 'object',
+		default: {
+			foo: 'bar',
+			baz: [23, 42]
+		}
+	});
+
+#### Type: `enum` ####
+
+**Arguments:** `1`
+
+With this option type you can define a list of option `values` as the allowed
+option arguments. The `values` parameter can either be an array of strings or
+a object, where the property names are used as the values for the allowed
+option arguments. The value stored to the parsed parameter object will be the
+according property value. The boolean `ignoreCase` parameter specifies whether
+the case of the option argument is ignored (default: `true`).
+
+Example:
+
+	parser.add('--enum1', {
+		type: 'enum',
+		values: ['foo', 'bar', 'baz']
+	});
+	
+	parser.add('--enum2', {
+		type: 'enum',
+		values: {
+			foo: 'FOO',
+			bar: [23, 42],
+			baz: null
+		}
+	});
+
+#### Type: `option` ####
+
+**Arguments:** `0`
+
+With the `option` type you can specify an option with a fixed value. It makes
+most sense if you have several options without argument that write the same
+`target`.
+
+See also: `flag`
+
+Example:
+
+	parser.add('--opt1', {
+		type: 'option',
+		target: 'what',
+		value: 555
+	});
+
+#### Type: `flag` ####
+
+**Arguments:** `0-1`
+
+Like `option` but only for boolean values. If no option argument is provided
+the value specified by the `value` parameter is used.
+
+Example:
+
+	parser.add('--use-something', {type: 'falg'});
+
+#### Type: `record` ####
+
+**Arguments:** `*`
+
+A `record` option accepts several option arguments. How many and which types
+is specified through the `args` parameter. This parameter accepts an array of
+option definitions (some parameters of these option definietions are ignored:
+`name`, `default`, `required`, `redefinable`, `help`, `details`, `onOption`).
+The type ot the record itself can be provided through the `create` parameter
+(function, default: Array).
+
+Example:
+
+	parser.add('--record', {
+		type: 'record',
+		default: ['bla', [10, 'bleh']],
+		args: [
+			{type: 'string'},
+			{type: 'record', args: [
+				{type: 'integer'},
+				{type: 'string'},
+			]}
+		]
+	});
+	
+	parser.add('--named', {
+		type: 'record',
+		create: Object,
+		default: {a: 0.5, b: 300, c: 'bla'},
+		args: [
+			{type: 'float',   target: 'a'},
+			{type: 'integer', target: 'b'},
+			{type: 'string',  target: 'c'}
+	]});
+
+#### Type: `custom` ####
+
+**Arguments:** `*`
+
+Example:
+
+	parser.add('--b64', {
+		type: 'custom',
+		argc: 1,
+		metavar: 'BASE64-STRING',
+		parse: function (s) {
+			return new Buffer(s, 'base64');
+		},
+		stringify: function (buffer) {
+			return buffer.toString('base64');
+		},
+		help: 'Pass binary data as a base64 encoded string.'
+	});
+
+### OptionParser ###
+
+#### Constructor ####
+
+**Arguments:**
+
+ * `params`: object, optional
+
+
+##### params #####
+
+	{
+	   minargs: integer, optional
+	   maxargs: integer, optional
+	   program: string, per default inferred from process.argv
+	   strings: object, optional
+	            Table of strings used in the output. See below.
+	   options: array, optional
+	            Array of option definitions. See below.
+	}
+
+##### strings #####
+
+	{
+	   help:      string, default: 'No help available for this option.'
+	   usage:     string, default: 'Usage'
+	   options:   string, default: 'OPTIONS'
+	   arguments: string, default: 'ARGUMENTS'
+	   required:  string, default: 'required'
+	   default:   string, default: 'default'
+	   base:      string, default: 'base'
+	   metavars:  object, optional
+	              Table of default metavar names per type.
+	              Per default the type name in capital letters or derived
+	              from the possible values.
+	}
+
+#### Properties ####
+
+Don't modifiy the properties unless you really know what you are doing.
+
+##### optionsPerName #####
+
+**Type:** `Object`
+
+Map of option definitions. Option definitions may occur multiple times when
+there are name aliases.
+
+##### options #####
+
+**Type:** `Array`
+
+Array of option definitions.
+
+##### defaultValues #####
+
+**Type:** `Object`
+
+Map of default values.
+
+#### Methods ####
+
+##### parse #####
+
+**Arguments:** 
+
+ * `args`: array of strings, default: `process.argv`
+
+##### add #####
+
+**Arguments:**
+
+ * `names`: string or array of strings, optional
+ * `optdef`: option definition, optional
+
+##### error #####
+
+**Arguments:**
+
+ * `msg`: string
+ * `out`: `WriteStream`, default: `process.stdout`
+ 
+##### usage #####
+
+**Arguments:**
+
+ * `help`: string
+ * `out`: `WriteStream`, default: `process.stdout`