Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A tool to check a configuration against a specification
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
features
lib
test
.document
.gitignore
LICENSE
README.rdoc
Rakefile
VERSION
lazy_configtester.gemspec

README.rdoc

LazyConfigtester

Specification of Configurations

The basic idea is that a configuration consists of a (recursive) hash. The keys can be strings, numbers and symbols. The values can be the same plus subhashes, arrays and regexps.

The specification of the configuration has to ensure that all configurations for a program follow the semantical restrictions of the program. These restrictions are defined in the specification.

The specification is a (recursive) hash as well. The levels of recursion in the specification corresponds to the levels in the configuration file that is to be checked.

The specification has numbers strings and symbols to indicate fixed requirements in the configuration. e.g. if the specification has the symbol :name as key at a certain level in the hash, this means that in the configuration at that level the key :name is required (the same for numbers and strings).

The values of the hashes specify the possible values in the configuration hash at the level. The symbols :array, :hash, :number, :regexp, :string and :symbol check against the type / class of the configuration value. An array as value allows any of its entries as valid values. A regexp matches against the value converted into a string. Any other value matches with == against the value of the configuration. The value '*' has the special meaning, that it matches against everything.

There are some strings in the spec that have a special meaning when used as keys in a hash:

  • '?' means, that the hash there are only zero or 1 items allowed in the hash

  • '*' means, that there are zero or more items allowed in the hash

  • '+' means, that there are 1 or more items allowed in the hash

  • '{n,m}' means, that there are at least n at most m items allowed in the hash (n and m are optional)

The value of such a key is checked against all values of the configuration hash (at the same level).

If a regexp is the key of a specification hash, each key in the configuration that matches against the regexp is checked by its values againt the values of the regexp key.

If an array is the key of a specification hash, each key of the configuration that is included in the array is checked by its value against the value of the array.

'?', '*', '+', '{n,m}' are the only keys that check the whole hash of the configuration. Apart from them additional keys in the configuration are silently ignored.

Symbols in the specification are special in that the match against symbols as well as strings. This holds for keys as well as values, since for example if the configuration comes via json, there is no way to get a symbol. Since the configurations are ruby hashes you could easily transform them into json, yaml, xml or other languages, allowing you to use them as configuration and specification files.

Examples:

Specifications:

:name or 'name' is a mandatory key in the configuration whos value has to a string

{ :name => :string }

the keys 'a' and 'b' are allowed to have the value 'c' or 'd'

{ ['a', 'b'] => ['c', 'd'] }

there should be at least one entry in the hash and all values should match against /peter/

{'+' => /peter/}

the keys that matches to /peter/ can have zero or more subhash entries, but there values should be arrays. the keys that match to /paul/ should have at least 2 and at most 4 entries in their hash and their values could be true or false.

{ /peter/ => { '*' => :array }, /paul/ => { '{2,4}' => [true, false] } }

Validation:

In order to check if a config matches the spec, create an instance of LazyConfigtester and call check on it:

LazyConfigtester.new(spec).check(config1).check(config2).check(config3)

or

LazyConfigtester.new.check(config,spec)

You may check your spec as well:

LazyConfigtester.new(spec)

or

LazyConfigtester.new.check_spec(spec)

Before any configuration check the specification is checked anyway. In case of a specification error, it throws an LazySpecError, in case of a configuration error it throws an LazyConfigError. If everything is fine, it returns itself to allow method chaining.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright

Copyright © 2010 Marc Rene Arns. See LICENSE for details.

Something went wrong with that request. Please try again.