Key Value Parser

The primary purpose of KeyValueParser is to have a simple class to be able to parse command line arguments which are all formated as key=value.

For example you could call a script like this:

$ ruby my-script.rb port=3000 host=localhost user=bob

Then in your script you would do:

# my-script.rb

require 'key_value_parser'

options = KeyValueParser.new.parse(ARGV)
options[:port] == 3000
options[:host] == 'localhost'
options[:user] == 'bob'

Since KeyValueParser is quite opinionated, it is absolutely not a replacement for OptionParser which aim is to be able to parse Unix style arguments.

Also KeyValueParser is not limited to command line arguments. It can potentially parse any array which is a list of Key/Value strings. For example you can parse a list of HTTP header lines.

The following sections are list of features in order to understand what KeyValueParser can and cannot do.

Default Values

When you create the parser instance, you can pass a Hash with default values.

# $ ruby my-script.rb host=www.domain.com
parser = KeyValueParser.new host: 'localhost', port: 3000
options = parser.parse(ARGV)
options[:port] == 3000
options[:host] == 'www.domain.com'

Typecasted Values

As you may have noticed in previous examples, values are typecasted. So far it does typecast integers, floats and booleans. Also if you don't give a value, the parser will interpret it as a flag and set it to true.

# $ ruby myscript.rb port=3000 broadcast=false running
options = KeyValueParser.new.parse(ARGV)
options[:port] == 3000
options[:broadcast] == false
options[:running] == true

If you don't want to cast values, you can use the second argument of KeyValueParse#parse which is a list of options. Just set typecast_values to false.

parser = KeyValueParser.new({}, {typecast_values: false})

Typecasting is still very basic and will most likely evolve, but it will move in this direction.

Normalized Keys

Keys of the resulting Hash are normalized. Dash in the middle of words are replaced by underscores. Double dash in front of a word are also removed. It allows you to have unix style double dash arguments.

# $ ruby my-script.rb --user-name="bob mould"
options = KeyValueParser.new.parse(ARGV)
options[:user_name] == 'bob'

Because of the way command line arguments are created for ARGV you can even surround an argument with quotes in order to have spaces in the argument's value.

There is nothing yet for unix style single dash arguments. I could remove the dash and treat it like a single letter key, but the true purpose of single letter arguments is to be an alternative to a longer argument name. If you have a simple idea to implement this without too much hassle, please send me a pull request.

If you don't want the keys to be normalized, there is an option for this.

# $ ruby my-script.rb --user-name=bob
parser = KeyValueParser.new({}, {normalize_keys: false})
options = parser.parse(ARGV)
options['--user-name'] == 'bob'

Array Arguments

You can have array values if you chain more than one =<value> after the key. And the values are still typecasted unless you disable it.

# $ ruby my-script.rb heroes=batman=robin ids=1=2
options = KeyValueParser.new.parse(ARGV)
options[:heroes] == ['batman', 'robin']
options[:ids] == [1, 2]

You can also disable this option:

# $ ruby my-script.rb heroes=batman=robin
parser = KeyValueParser.new({}, {array_values: false})
options = parser.parse(ARGV)
options[:heroes] == 'batman=robin'

Please note that so far this is the only way to make an array. Setting multiple times the same value would just result in the key being set to the last value.

# $ ruby my-script.rb heroes=batman heroes=robin
options = KeyValueParser.new.parse(ARGV)
options[:heroes] == 'robin'

Parsing More Than ARGV

By default, the separator allows you to have an equal sign = or a colon :. And the regexp allows spaces around the separator. The surrounded spaces are if you want to parse a list of keys/values from a file for example. Let say you have a file containing a key/value per line.

user: Bob Mould
number: 42

Which looks like a subset of YAML. Then you can parse the file for settings.

parser = KeyValueParser.new
settings = parser.parse File.readlines('settings.conf')

Everything works the same, typecasting, normalizing keys, defaults, arrays... You can also set another separator. Anything which works with String#split will do.