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'
= KeyValueParser.new.parse(ARGV)
[:port] == 3000
[:host] == 'localhost'
[: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
= parser.parse(ARGV)
[:port] == 3000
[: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
= KeyValueParser.new.parse(ARGV)
[:port] == 3000
[:broadcast] == false
[: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"
= KeyValueParser.new.parse(ARGV)
[: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})
= parser.parse(ARGV)
['--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
= KeyValueParser.new.parse(ARGV)
[:heroes] == ['batman', 'robin']
[:ids] == [1, 2]
You can also disable this option:
# $ ruby my-script.rb heroes=batman=robin
parser = KeyValueParser.new({}, {array_values: false})
= parser.parse(ARGV)
[: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
= KeyValueParser.new.parse(ARGV)
[: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.
# settings.conf:
# author | Kevin Smith
# characters | Jay | Silent Bob
parser = KeyValueParser.new({stars: 5}, {separator: /\s*\|\s*/})
settings = parser.parse File.readlines('settings.conf')
settings[:author] == 'Kevin Smith'
settings[:characters] == ['Jay', 'Silent Bob']
settings[:stars] == 5