Configliere
This repository has moved: infodhimps-platform/configliere
All further code work and gems will take place in the above repo, not here.
Configliere provides discreet configuration for ruby scripts.
So, Consigliere of mine, I think you should tell your Don what everyone knows. â Don Corleone
Youâve got a script. Itâs got some settings. Some settings are for this module, some are for that module. Most of them donât change. Except on your laptop, where the paths are different. Or when youâre in production mode. Or when youâre testing from the command line.
Configliere manages settings from many sources: static constants, simple config files, environment variables, commandline options, straight ruby. You donât have to predefine anything, but you can ask configliere to type-convert, require, document or password-obscure any of its fields. Basically: Settings go in, the right thing happens.
Example
Hereâs a simple example, using params from a config file and the command line. In the script:
#/usr/bin/env ruby require 'configliere' Settings.use :commandline # Supply defaults inline. Settings({ :dest_time => '11-05-1955', :delorean => { :power_source => 'plutonium', :roads_needed => true, }, :username => 'marty', }) # Pre-defining params isn't required, but it's easy and expressive to do so: Settings.define :dest_time, :type => DateTime, :description => "Target date" # This defines a 'deep key': it controls Settings[:delorean][:roads_needed] Settings.define 'delorean.roads_needed', :type => :boolean # The settings in this file will be merged with the above Settings.read './examples/simple_script.yaml' # resolve! the settings: load the commandline, do type conversion, etc. Settings.resolve! p Settings
Weâll override some of the defaults with a config file, in this case ./examples/simple_script.yaml
# Settings for return :dest_time: 11-05-1985 :delorean: :power_source: 1.21 jiggawatts
Output, when run with commandline parameters as shown:
./time_machine.rb --username=doc_brown --delorean.roads_needed="" --delorean.power_source="Mr. Fusion" {:delorean => {:power_source=>"Mr. Fusion", :roads_needed=>nil}, :username=>"doc_brown", :dest_time=>#<DateTime: 1985-05-11T00:00:00+00:00>}
For an extensive usage in production, see the wukong gem.
Notice
Configliere 4.x now has 100% spec coverage, more powerful commandline handling, zero required dependencies. However, it also strips out several obscure features and much magical code, which breaks said obscure features and magic-dependent code. See the CHANGELOG. for details as you upgrade.
Design goals:
- Omerta (Code of Silence). Most commandline parsers force you to pre-define all your parameters in a centralized and wordy syntax. In configliere, you donât have to pre-define anything â commandline parameters map directly to values in the Configliere hash. Hereâs all you need to have full-fledged commandline params:
$ cat ./shorty.rb require 'configliere' Settings.use(:commandline).resolve! p [Settings, Settings.rest] $ ./shorty.rb --foo=bar go [{:foo=>"bar"}, ["go"]]
- Be willing to sit down with the Five Families. Takes settings from (at your option):
- Pre-defined defaults from constants
- Simple config files
- Environment variables
- Commandline options and git-style command runners
- Ruby block (called when all other options are in place)
- Donât go outside the family. Has no dependencies and requires almost no code in your script. Configliere makes no changes to standard ruby classes.
- Offer discreet counsel. Configliere offers many features, but only loads the code you request explicitly by calling
use
.
- Donât mess with my crew. Settings for a model over here can be done independently of settings for a model over there, and donât require asking the boss to set something up. You centralize configuration values while distributing configuration definition:
# In lib/handler/mysql.rb Settings.define :mysql_host, :type => String, :description => "MySQL db hostname", :default => 'localhost' # In app/routes/homepage.rb Settings.define :background_color, :description => "Homepage background color" # In config/app.yaml --- :background_color: '#eee' :mysql_host: 'brains.infochimps.com'
You can decentralize even more by giving modules their own config files or separate Configliere::Param objects.
- Can hide your assets. Rather than storing passwords and API keys in plain sight, configliere has a protection racket that can obscure values when stored to disk.
fuhgeddaboudit.
Settings structure
A Configliere settings object is just a (mostly-)normal hash.
You can define static defaults in your module
Settings({ :dest_time => '11-05-1955', :fluxcapacitor => { :speed => 88, }, :delorean => { :power_source => 'plutonium', :roads_needed => true, }, :username => 'marty', :password => '', })
All simple keys should be symbols. Retrieve the settings as:
# hash keys Settings[:dest_time] #=> '11-05-1955' # deep keys Settings[:delorean][:power_source] #=> 'plutonium' Settings[:delorean][:missing] #=> nil Settings[:delorean][:missing][:fail] #=> raises an error # dotted keys resolve to deep keys Settings['delorean.power_source'] #=> 'plutonium' Settings['delorean.missing'] #=> nil Settings['delorean.missing.fail'] #=> nil # method-like (no deep keys tho, and you have to #define the param; see below) Settings.dest_time #=> '11-05-1955'
Configuration files
Call Settings.read(filename)
to read a YAML config file.
# Settings for version II. :dest_time: 11-05-2015 :delorean: :power_source: Mr. Fusion :roads_needed: ~
If a bare filename (no â/â) is given, configliere looks for the file in Configliere::DEFAULT_CONFIG_DIR
(normally ~/.configliere). Otherwise it loads the given file.
Settings.read('/etc/time_machine.yaml') # looks in /etc/time_machine.yaml Settings.read('time_machine.yaml') # looks in ~/.configliere/time_machine.yaml
As you can see, youâre free to use as many config files as you like. Loading a config file sets values immediately, so later-loaded files win out over earlier-loaded ones.
You can save configuration too:
Settings.save!('/etc/time_machine.yaml') # overwrites /etc/time_machine.yaml Settings.save!('time_machine.yaml') # overwrites ~/.configliere/time_machine.yaml
Command-line parameters
# Head back time_machine --delorean.power_source='1.21 jiggawatt lightning strike' --dest_time=11-05-1985 # (in the time_machine script:) Settings.use(:commandline) Settings.resolve!
Interpretation of command-line parameters:
- name-val params:
--param=val
setsConfigliere[:param]
to val. You must use the â=â in there:./my_cmd --filename=bar
good,./my_cmd --filename bar
bad. - boolean params:
--param
setsConfigliere[:param]
to be true.--param=""
setsConfigliere[:param]
to be nil. - single-char flags: Define a flag for a variable:
Settings.define :filename, :flag => "f"
allows you to say./my_cmd -f=bar
. - scoped params: A dot within a parameter name scopes that parameter:
--group.sub_group.param=val
setsConfigliere[:group][:subgroup][:param]
to val (and similarly for boolean parameters).- Only
[\w\.]+
are accepted in parameter names. â-â is currently accepted but causes a warning.
- Only
- Settings.rest: anything else is stored, in order, in
Settings.rest
. - stop marker: a
--
alone stops parameter processing and tosses all remaining params (not including the--
) into Settings.rest.
Here are some things you donât get:
- Configliere doesnât complain about un-@define@âd commandline argvs. However, it does store each undefineâd argv (when resolve! is called) into
unknown_argvs
, so you can decide what to do about it. - Apart from converting
''
(an explicit blank string) tonil
, no type coercion is performed on parameters unless requested explicitly (see below). - No validation is performed on parameters, but you can insert a middleware with a
validate!()
method, or use a:finally
block. - No ordering or multiplicity is preserved: you canât say
--file=this --file=that
. Instead, define the param as an arraySettings.define :file, :type => Array
and give a simple comma-separated list.
Commandline parameters are demonstrated in examples/simple_script.rb and examples/env_var_script.rb
Defined Parameters
You donât have to pre-define parameters, but you can:
Settings.define :dest_time, :type => DateTime, :description => 'Arrival time' Settings.define 'delorean.power_source', :env_var => 'POWER_SOURCE', :description => 'Delorean subsytem supplying power to the Flux Capacitor.' Settings.define :password, :required => true, :encrypted => true
:description
: documents a param.:type
: converts params to a desired form.:required
: marks params required.:encrypted
: marks params to be obscured when saved to disk. See [#Encrypted Parameters] below for caveats.:env_var
: take param from given environment variable if set.
Defined parameters are demonstrated in most of the example scripts
Description
If you define a paramâs description, besides nicely documenting it within your code the description will be stuffed into the output when the âhelp commandline option is invoked.
$ ./examples/simple_script usage: simple_script.rb [...--param=val...] Params: --delorean.roads_needed delorean.roads_needed --dest_time=DateTime Date to travel to [Default: 11-05-1955]
Type Conversion
Parameters defined with a :type
and will be type-converted when you call Settings.resolve!
.
Settings.define :dest_time, :type => DateTime Settings.define :fugeddaboudit, :type => Array Settings :fugeddaboudit => 'badabing,badaboom,hey', :dest_time => '11-05-1955' Settings.resolve! Settings[:fugeddaboudit] #=> ['badabing', 'badaboom', 'hey'] Settings[:dest_time] #=> #<DateTime: 4870833/2,0,2299161>
Configliere can coerce parameter values to Integer, Float, :boolean, Symbol, Array, Date and DateTime.
- :boolean converts nil to nil ; false, âfalseâ, 0, â0â and ââ to false; and everything else to true.
- Array just does a simple split on â,â. It doesnât do any escaping or quoting.
- Date and DateTime convert unparseable inputs to nil.
- :filename calls File.expand_path() on the param.
Required Parameters
Any required parameter found to be nil raise an error (listing all missing params) when you call Settings.resolve! (See examples/env_var_script.rb)
Environment Variables
Settings.define :dest_time, :env_var => 'DEST_TIME' Settings.define :environment, :env_var => 'RACK_ENV'
Encrypted Parameters
Define a param to be encrypted and invoke Settings.save!. It will use Settings.encrypt_pass (or the ENCRYPT_PASS environment variable) to encrypt the data when it is saved to disk. (see examples/encrypted_script.rb)
Settings.use :encrypted Settings.define 'amazon.api.key', :encrypted => true Settings 'amazon.api.key' => 'fnord'
In this example, the hash saved to disk will contain { :amazon => { :api => { :encrypted_key => "...encrypted val..." } } }
. After reading from disk, #resolve! will recover its original value: { :amazon => { :api => { :key => "fnord" } } }
.
There are two kinds of cryptography in this world: cryptography that will stop your kid sister from reading your files, and cryptography that will stop major governments from reading your files. This book is about the latter. â Preface to Applied Cryptography by Bruce Schneier
Configliere provides the former.
Anyone with access to the script, its config files and its normal launch environment can recover the plaintext password; but it at least doesnât appear when you cat the file while giving a presentation.
Ruby Block
Settings.use :config_block Settings.finally do |c| c.dest_time = (Time.now + 60) if c.username == 'einstein' # you can use hash syntax too c[:dest_time] = (Time.now + 60) if c[:username] == 'einstein' end # # ... rest of setup ... # Settings.resolve! # the finally blocks will be called in order
Configliere âfinallyâ blocks are invoked when you call resolve!
. Theyâre guaranteed to be called at the end of the resolve chain, and before the validate chain.
Config blocks are demonstrated in examples/config_block.rb
Shortcut syntax for deep keys
You can use a âdotted keyâ like âdelorean.power_sourceâ as simple notation for a deep key: Settings['delorean.power_source']
is equivalent to Settings[:delorean][:power_source]
. You can use a dotted key in any simple reference:
Settings['delorean.power_source'] = "Mr. Fusion" Settings[:delorean][:power_source] #=> "Mr. Fusion" Settings.delete('delorean.power_source') #=> "Mr. Fusion" Settings #=> { :delorean => {} }
Intermediate keys âauto-vivifyâ (automatically create any intervening hashes):
Settings['one.two.three'] = "To tha Fo'" # Settings is { :one => { :two => { :three => "To tha Fo'" } }, :delorean => { :power_source => "Mr. Fusion" }
Independent Settings
All of the above examples use the global variable Settings
, defined in configliere.rb. It really works fine in practice, even where several systems intersect. Youâre free to define your own settings universe though:
class Wolfman def config @config ||= Configliere::Param.new.use(:commandline).defaults({ :moon => 'full', :nards => true, }) end end teen_wolf = Wolfman.new teen_wolf.config.defaults(:give_me => 'keg of beer') teen_wolf.config #=> {:moon=>"full", :nards=>true, :give_me=>"keg of beer" } Settings #=> {}
Values in here donât overlap with the Settings object or any other settings universe. However, every one that pulls in commandline params gets a full copy of the commandline params.
Project info
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 a pull request to github.com/mrflip
- Drop a line to the mailing list for infochimps open-source projects, [email protected]
Copyright
Copyright © 2010 mrflip. See LICENSE for details.