defined-options

Define option properties with optional validation, filter and default value. Read, write, validate and merge option values as simple as possible.

---

README IN PROGRESS

• API
  • Options()
    • .defineOption()
      • Option definition
    • .defineOptions()
    • .removeOption()
    • .hasOption()
    • .getPlainObject()
    • .merge()
    • .mergeOptionValues()
    • .mergeOptions()
    • .getOptionDefinition()
    • .getOptionDefinitions()
    • .default()
    • .setDefaultOptionValue()
    • .setDefaultOptionValues()
    • .validate()
    • .validateOptionValue()
    • .validateOptionValues()
  • Option()
• License

API

See also tests and examples.

Options()

See lib/options.js.

Creates a new Options instance. Accepts an object with option definitions as optional argument.

var Options = require('defined-options');

var options = new Options({
        text: {
            validate: 'string!empty',
            default: 'foo'
        },
        answer: {
            validate: 'number>0',
            default: 42
        }
    });

console.log(options); // { text: [Getter/Setter], answer: [Getter/Setter] }
console.log(options.getPlainObject()); // { text: 'foo', answer: 42 }
console.log(options.text); // foo
console.log(options.answer); // 42

Options' properties have getters and setters defined via their descriptors. This way validation and filtering is done automagically:

// option 'text' only accepts non-empty strings
options.text = '';
console.log(options.text); // foo
options.text = 'bar';
console.log(options.text); // bar

// option 'answer' only accepts numbers > 0
options.answer = -7;
console.log(options.answer); // 42
options.answer = 5;
console.log(options.answer); // 5

.defineOption()

Creates a new option property or replaces an existing one with same name.

Accepts option definition as single argument or option name as first and option definition as second argument.

Returns current Options instance.

options.defineOption({name: 'text', validate: 'string'});
// or
options.defineOption('text', {validate: 'string'});

Option definition

An option definition object can have the following properties:

• name
  required
  a non-empty string defining the option name

• validate
  default: 'any'
  defines how to validate an options value; accepts validate-by-shorthand arguments:

  • a string defining a shorthand string
  • a regular rexpression for a match test
  • a function, receiving a value to test, returning a boolean result
  • an array of shorthand strings, regular expressions and/or functions; validating an option value if any of these tests returns true

• filter
  default: function(value) {return value;}
  defines a filter function, receiving the validated value, returning the filtered value

• default
  default: undefined
  defines an option's default value; if set to a function, it will be called to set the default value

Example with all properties:

options.defineProperty({
    name: 'shout',
    default: 'HELLO!',
    validate: 'string!empty',
    filter: function(value) {
        return value.toLowerCase();
    }
});

console.log(options.shout); // HELLO!
options.shout = 'bye!';
options.shout = 1;
console.log(options.shout); // BYE!

.defineOptions()

Creates new option properties or replaces existing ones with same name using defineOption().

Expects and object with option names as keys and option definitions as values.

Returns current Options instance.

options.defineOptions({
    name: {
        validate: 'string'
    },
    age: {
        validate: 'number>0'
    }
});

.removeOption()

Removes an option. Expects and option name. Returns current Options instance.

options.removeOption('foo');

.hasOption()

Tests is a option is defined. Expects an option name. Returns a boolean result.

options.hasOption('foo');

.getPlainObject()

Returns a plain object with option name as keys and option values as values, without described getters and setters.

console.log(options); // { text: [Getter/Setter], answer: [Getter/Setter] }
console.log(options.getPlainObject()); // { text: 'foo', answer: 42 }

.merge()

Alias for mergeOptionValues().

.mergeOptionValues()

Merges an new values into current Options instance and updates an option values if given value is valid.

Expects on or more objects containing option names as keys and option values as values.

Returns current Options instance.

var options = new Options({
        text: {
            validate: 'string!empty',
            default: 'foo'
        },
        answer: {
            validate: 'number>0',
            default: 42
        }
    });

console.log(options.getPlainObject()); // { text: 'foo', answer: 42 }

options.merge({
    text: bar,
    answer: -7,
    name: 'Han'
});

console.log(options.getPlainObject()); // { text: 'bar', answer: 42 }

.mergeOptions()

Merges one Options instance into another. Replaces options with same name.

Expects one or more Options instances.

Returns current Options instance.

console.log(options.getPlainObject()); // { text: 'foo', answer: 42 }

options.mergeOptions(new Options({
    name: {
        validate: 'string',
        default: 'Han'
    }
}));

console.log(options.getPlainObject()); // { text: 'foo', answer: 42, name: 'Han' }

.getOptionDefinition()

Returns an option definition as Option instance. Expects an option name.

.getOptionDefinitions()

Returns all option definitions as an object with option names as keys and the respective Option instance as values.

.default()

.setDefaultOptionValue()

.setDefaultOptionValues()

.validate()

.validateOptionValue()

.validateOptionValues()

Option()

License

MIT © 2015 Simon Lepel