stacked_config 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0cc8ac49474011f38a0cf1b6859849c9feb356b9
-  data.tar.gz: 5b5076b0f63330df95152b0403619043807bee21
+  metadata.gz: 396a51271ebfbb2aee0f6a8d3d03674f46b7a398
+  data.tar.gz: d4215b4890198baf73cb42ea690ff46b000e9ea3
 SHA512:
-  metadata.gz: f66b20e0469a6c5f3ce095c401ec1ba527ef9e9a0e1a15e597c02d6d4b4f7ddf7d90362548fe9b757b9e4b2822a94bb321f463181ecd375e92f2735fa0b2a16c
-  data.tar.gz: 4f6b134a3dc729a0a03f67c70338eac58cae74780df30ee62d90a822bd5bb7026966cd1cec9fba06105b9f402c52d856f34d4f7f302a46c63bd1350734102359
+  metadata.gz: 35cc07767ab94e5891230097e9a83ecaac1202c4325af0d2e8e6fc82ff555d4b760e855bb8e41d8014e66135b52833608ff78e60a30df7e8750c67d48fb408e9
+  data.tar.gz: d114a476a6684535ffabc7a777fe4eff2175a11cd58cca4644ba9657b513e0fc4d3bad0850907425f12ce8c0074ad404d2c21c69da5f991cbc2c64410c5de3cd

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.0.0
+script:
+  - bundle exec rake spec

data/README.md

@@ -1,10 +1,21 @@
 # StackedConfig
+ [![Build Status](https://travis-ci.org/lbriais/stacked_config.svg)](https://travis-ci.org/lbriais/stacked_config)
+ [![Gem Version](https://badge.fury.io/rb/stacked_config.svg)](http://badge.fury.io/rb/stacked_config)
 
-Code should be ready for prod
+The purpose of this gem is to provide a __simple__ way to handle the __inheritance__ of __config files__ for a ruby
+script. By default, it will handle already few config layers:
 
-No doc written for the time being
+* The __system layer__, which is a level common to all applications using this gem.
+* The __global layer__, which is the level to declare options for all users that use the ruby script using this gem.
+* The __user layer__, which is the level, where a user can set options for the ruby script using this gem.
+* The __extra layer__, which provides the possibility to specify a config file from the command line.
+* The __command-line layer__, which provides the ability to specify options from the command line.
+* The __override layer__, which will contain all modifications done to the config at run time.
 
-Wait for version 0.1.x
+The different layers are evaluated by default in that order using the [super_stack gem][SS] (Please read for more
+detail).
+
+All the config files are following the [YAML] syntax.
 
 ## Installation
 
@@ -22,12 +33,133 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basics
+
+`stacked_config` is a very versatile configuration system for your scripts. The default behaviour may satisfy most of
+ the needs out of the box.
+
+```ruby
+require 'stacked_config'
+
+config = StackedConfig::Orchestrator.new
+
+config[:runtime_property] = 'A runtime property'
+
+# Displays all the internals of the config:
+puts config.detailed_layers_info
+
+# Normally you may probably only need to access some properties
+if config[:help]
+    puts config.command_line_help
+end
+```
+
+Try this little script and then create some config files to test how it is handled (see next section to know where to
+create the config files).
+
+
+### Where are my config files ?
+
+`stacked_config` will look for config files in different places depending on the layer we are talking about. Have a look
+at the source to understand where exactly your config files can be, but basically it is following the Unix way of
+doing things...
+
+* Sources for the [system layer][SystemLayer]
+* Sources for the [global layer][GlobalLayer]
+* Sources for the [user layer][UserLayer]
+
+As you can see in the sources, paths are expressed using kind of 'templates', which meaning should be obvious
+
+* `##SYSTEM_CONFIG_ROOT##` is where the system config is stored. On Unix systems, it should be `/etc`.
+* `##PROGRAM_NAME##` is by default the name of the script you are running (with no extension). You can if you want
+  change this name at runtime. Changing it will trigger a re-search and reload of all the config files.
+* `##USER_CONFIG_ROOT##` is where the user config is stored. On Unix systems, it should be your `$HOME` directory.
+* `##EXTENSION##` is one of the following extensions : `conf CONF cfg CFG yml YML yaml YAML`.
+
+The search of the config files is done according to the order defined in sources just above and then extensions
+are tried according to the extensions just above in that exact order.
+
+__The first file matching for a particular level is used !__ And there can be only one per level.
+
+Thus according to the rules above, and assuming my script is named `my_script.rb` if the two following files exists at
+user config level, only the first is taken in account:
+
+* `~/.my_script.yml`
+* `~/.config/my_script.conf`
+
+
+### Script command line options
+
+`stacked_config` uses internally the fantastic [Slop] gem to manage options coming from
+the command line.
+
+To define your options the command-line layer exposes a `slop_definition` method that enables
+to directly configure slop.
+
+For most usages you can use the higher level method `add_command_line_section` from the orchestrator.
+
+```ruby
+require 'stacked_config'
+
+config = StackedConfig::Orchestrator.new
+config.add_command_line_section do |slop|
+  slop.on :u, :useless, 'Stupid option', :argument => false
+  slop.on :an_int, 'Stupid option with integer argument', :argument => true, :as => Integer
+end
+```
+
+The `add_command_line_section` method supports a parameter to define the name of the section.
+
+
+### Advanced usage
+
+#### Re-ordering layers
+
+The way layers are processed is done according to their priority. By default the existing layers have the following
+priorities:
+
+* The system layer has a priority of 10
+* The global layer has a priority of 20
+* The user layer has a priority of 30
+* The extra layer has a priority of 40
+* The command-line layer has a priority of 100
+* The override layer has a priority of 1000
+
+But imagine you want to say that no-one could override properties defined at the system and global layer even from the
+command-line, then you just have to change the priorities of those 2 layers.
+
+```ruby
+require 'stacked_config'
+
+config = StackedConfig::Orchestrator.new
+config.system_layer.priority = 1500
+config.global_layer.priority = 1600
+```
+
+By doing such the system and global layers will be evaluated after the command line layer and therefore properties set
+in those files cannot be overridden even at command line level.
+
+
+#### Adding extra layers
+
+Imagine you want to add a specific layer in your config, coming from let's say a web-service or a database, you may
+create your own layers for this purpose. Have a look at [super_stack gem][SS] for further info about how to create
+layers.
+
+But basically just create your new layer, gives it a priority and add it to the orchestrator.
+
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/stacked_config/fork )
+1. [Fork it] ( https://github.com/lbriais/stacked_config/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+[SS]:          https://github.com/lbriais/super_stack       "Super Stack gem"
+[SystemLayer]: https://github.com/lbriais/stacked_config/blob/master/lib/stacked_config/layers/system_layer.rb "the system layer places where config files are searched"
+[GlobalLayer]: https://github.com/lbriais/stacked_config/blob/master/lib/stacked_config/layers/global_layer.rb "the global layer places where config files are searched"
+[UserLayer]:   https://github.com/lbriais/stacked_config/blob/master/lib/stacked_config/layers/user_layer.rb   "the user layer places where config files are searched"
+[YAML]:        http://www.yaml.org/    "The Yaml official site"
+[Slop]:        https://rubygems.org/gems/slop   "The Slop gem"

data/lib/stacked_config/layers/command_line_layer.rb

@@ -14,7 +14,11 @@ module StackedConfig
         slop_definition.parse
         slop_definition.banner = build_banner
         clear
-        merge! slop_definition.to_hash
+        merge! slop_definition.to_hash.delete_if {|k,v| v.nil?}
+      end
+
+      def possible_options
+        slop_definition.to_hash.keys.sort
       end
 
       def reload

data/lib/stacked_config/layers/generic_layer.rb

@@ -5,10 +5,7 @@ module StackedConfig
 
       include StackedConfig::SourceHelper
 
-      attr_reader :orchestrator
-
       def rescan
-
         set_config_file possible_sources
       end
 

data/lib/stacked_config/orchestrator.rb

@@ -10,14 +10,42 @@ module StackedConfig
       super
       self.merge_policy = SuperStack::MergePolicies::FullMergePolicy
       setup_layers
-      default_name = File.basename($PROGRAM_NAME)
+      default_name = self.class.default_executable_name
       describes_application executable_name: default_name, app_name: default_name
     end
 
+    def detailed_layers_info
+      info, sep = [], '-' * 80
+      info << sep
+      layers.values.sort {|a, b| a.priority <=> b.priority}.each do |layer|
+        info << layer.name
+        if layer.file_name.nil?
+          info << 'There is no file attached to this level.'
+        else
+          info << "Using '#{layer.file_name}' as config file for this layer."
+        end
+        if layer.empty?
+          info << 'There is no data in this layer'
+        else
+          info << 'This layer contains the following data:'
+          info << layer.to_yaml
+        end
+        info << sep
+      end
+      info.join "\n"
+    end
+
+    def command_line_help
+      command_line_layer.help
+    end
+
+    def self.default_executable_name
+      File.basename($PROGRAM_NAME).gsub /\.[^\.]+$/, ''
+    end
+
     private
 
     def setup_layers
-
       # The command line level.
       @command_line_layer = setup_layer StackedConfig::Layers::CommandLineLayer, 'Command line configuration level', 100
 

data/lib/stacked_config/source_helper.rb

@@ -77,7 +77,7 @@ module StackedConfig
       res.gsub! '##SYSTEM_CONFIG_ROOT##', system_config_root
       res.gsub! '##USER_CONFIG_ROOT##', user_config_root
 
-      exec_name = manager.nil? ? File.basename($PROGRAM_NAME) : manager.executable_name
+      exec_name = manager.nil? ? StackedConfig::Orchestrator.default_executable_name : manager.executable_name
       res.gsub! '##PROGRAM_NAME##', exec_name
       res
     end

data/lib/stacked_config/version.rb

@@ -1,3 +1,3 @@
 module StackedConfig
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/spec/command_line_layer_spec.rb

@@ -4,24 +4,24 @@ require 'spec_helper'
 describe StackedConfig::Layers::CommandLineLayer do
   subject { StackedConfig::Layers::CommandLineLayer.new }
 
-  it 'should have some default command line options defined' do
-    expect(subject.length > 0).to be_truthy
+  it 'should expose an empty layer by default' do
+    expect(subject.length == 0).to be_truthy
   end
 
   it 'should have a "help" command line options defined' do
-    expect(subject.keys.include? :help).to be_truthy
+    expect(subject.possible_options.include? :help).to be_truthy
   end
 
   it 'should have a "auto" command line options defined' do
-    expect(subject.keys.include? :auto).to be_truthy
+    expect(subject.possible_options.include? :auto).to be_truthy
   end
 
   it 'should have a "simulate" command line options defined' do
-    expect(subject.keys.include? :simulate).to be_truthy
+    expect(subject.possible_options.include? :simulate).to be_truthy
   end
 
   it 'should have a "verbose" command line options defined' do
-    expect(subject.keys.include? :verbose).to be_truthy
+    expect(subject.possible_options.include? :verbose).to be_truthy
   end
 
 

data/stacked_config.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rspec', '~> 3.0'
 
-  spec.add_dependency 'super_stack', '~> 0.2', '>= 0.2.4'
+  spec.add_dependency 'super_stack', '~> 0.2', '>= 0.2.5'
   spec.add_dependency 'slop'
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stacked_config
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-24 00:00:00.000000000 Z
+date: 2014-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,7 +75,7 @@ dependencies:
         version: '0.2'
     - - '>='
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.2.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -85,7 +85,7 @@ dependencies:
         version: '0.2'
     - - '>='
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.2.5
 - !ruby/object:Gem::Dependency
   name: slop
   requirement: !ruby/object:Gem::Requirement
@@ -109,6 +109,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md