stacked_config 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 396a51271ebfbb2aee0f6a8d3d03674f46b7a398
-  data.tar.gz: d4215b4890198baf73cb42ea690ff46b000e9ea3
+  metadata.gz: bbaae6cc93a17d8d15943af382d2683addc479c2
+  data.tar.gz: 3949626e5a158e99d7cdcf1bcdf6a32852966bb8
 SHA512:
-  metadata.gz: 35cc07767ab94e5891230097e9a83ecaac1202c4325af0d2e8e6fc82ff555d4b760e855bb8e41d8014e66135b52833608ff78e60a30df7e8750c67d48fb408e9
-  data.tar.gz: d114a476a6684535ffabc7a777fe4eff2175a11cd58cca4644ba9657b513e0fc4d3bad0850907425f12ce8c0074ad404d2c21c69da5f991cbc2c64410c5de3cd
+  metadata.gz: 8a9e072826b8bccf78c16d30479ebfda5f92408c3fa4bf92661bcf11a48efc7c1c0ce7f715dcafad384917ef8f54f6787160af5d6369336e6f3a5a2760e1e926
+  data.tar.gz: bcb3241c7a790dce29df30c1a219cb3589d9a0ec9f4e859842bc5e4ea63c515e27c47d08582fdc1d1d9fd1763c1ba70f2376ddab0677f321570915b036dfa7e6

data/README.md

@@ -2,18 +2,22 @@
  [![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)
 
+If you need to manage config files accross the system, some of them belonging to the administrator some to the user
+running the application, some coming from the command line and more, __[This Gem]
+(http://rubygems.org/gems/stacked_config) is made for you__ !
+
 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:
 
 * 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 __extra layer__, which provides the possibility to specify another 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.
 
 The different layers are evaluated by default in that order using the [super_stack gem][SS] (Please read for more
-detail).
+detail). The `StackedConfig::Orchestrator` will expose a merged view of all its layers without modifying them.
 
 All the config files are following the [YAML] syntax.
 
@@ -54,9 +58,25 @@ if config[: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).
+Try this little script and then create some config files to test how it is handled (see [next section]
+(#where-are-my-config-files-) to know where to create the config files).
+
+You are supposed to access the merged config through the `[]` method of the orchestrator (`config[]` in the previous
+example). Still you can directly modify any of the layers automatically created, you are not supposed to, and if you
+modify or add any new property (a so called "runtime property"), it will actually set the property in the `override`
+layer.
+
+That's why you can always come back to the initial state by calling `reset` on the orchestrator. This actually just
+clears the override layer.
 
+Every layer is accessible through the following orchestrator properties:
+
+* `system_layer`
+* `global_layer`
+* `user_layer`
+* `provided_config_file_layer`
+* `command_line_layer`
+* `write_layer`
 
 ### Where are my config files ?
 
@@ -72,14 +92,15 @@ As you can see in the sources, paths are expressed using kind of 'templates', wh
 
 * `##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.
+  change this name at runtime. __Changing it (using the `executable_name` orchestrator property ) 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.
+__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:
@@ -90,11 +111,98 @@ user config level, only the first is taken in account:
 
 ### Script command line options
 
-`stacked_config` uses internally the fantastic [Slop] gem to manage options coming from
-the command line.
+`stacked_config` uses internally the fantastic [Slop] gem to manage options coming from the command line within the
+command line layer. This layer will be simply part of the complete config that the orchestrator exposes.
+
+#### Command line help
+
+You can easily display a help using the orchestrator `command_line_help` method.
+
+To even have a better command line help displayed you can provide optional information:
+
+* The __application name__ through the `app_name` orchestrator property.
+* The __application version__ through the `app_version` orchestrator property.
+* The __application description__ through the `app_description` orchestrator property.
+
+You could as well do this with the `describes_application` method (see [complete example]()).
+
+```ruby
+require 'stacked_config'
+
+config = StackedConfig::Orchestrator.new
+
+config.app_name = 'My super Application'
+config.app_version = '1.0.0'
+config.app_description = <<EOD
+You can have a multiline description of your application.
+This may help a lot having a consistent command-line help.
+EOD
+puts config.command_line_help
+```
+
+This would issue:
+
+```
+Usage: myscript [options]
+My super Application Version: 1.0.0
+
+You can have a multiline description of your application.
+This may help a lot having a consistent command-line help.
+
+-- Generic options -------------------------------------------------------------
+        --auto                 Auto mode. Bypasses questions to user.
+        --simulate             Do not perform the actual underlying actions.
+    -v, --verbose              Enable verbose mode.
+    -h, --help                 Displays this help.
+-- Configuration options -------------------------------------------------------
+        --config-file          Specify a config file.
+        --config-override      If specified override all other config.
+```
+
+Which are the default options available.
+
+
+#### Default command line options
+
+By default the following command line options are available:
+
+* __auto__             Auto mode. Bypasses questions to user. Just provided for convenience. Not used anywhere in the
+                       code.
+* __simulate__         Do not perform the actual underlying actions. Just provided for convenience. Not used anywhere
+                       in the code.
+* __verbose__          Enable verbose mode. Just provided for convenience. Not used anywhere in the code.
+* __help__             Displays this help. Just provided for convenience. Not used anywhere in the code.
+* __config-file__      Specify a config file for the extra layer.
+* __config-override__  If specified, means that the config file specified will override all other config (actually
+                       changes the merge policy [see below] (#changing-the-way-things-are-merged)) of the extra layer.
+
+Flags that are said "Just provided for convenience. Not used anywhere in the code." are just there because they are
+standard options and thus you can easily test in your code.
+
+```ruby
+puts "Something very important" if config[:verbose]
+```
+
+`stacked_config` provides a convenient method to display the command line help every user expects from a decent script:
+
+```ruby
+require 'stacked_config'
+
+config = StackedConfig::Orchestrator.new
+
+if config[:help]
+    # command_line_help will provide a formatted help to display on the command line
+    puts config.command_line_help
+    exit 0
+end
+
+# ... do something else
+```
+
+#### Adding new command line options
 
-To define your options the command-line layer exposes a `slop_definition` method that enables
-to directly configure slop.
+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.
 
@@ -110,20 +218,23 @@ end
 
 The `add_command_line_section` method supports a parameter to define the name of the section.
 
+__Of course adding new command line options will adapt the display of the `command_line_help` method of the
+orchestrator__.
 
-### Advanced usage
 
-#### Re-ordering layers
+## 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
+* 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.
@@ -137,10 +248,10 @@ 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.
+in those files cannot be overridden even at command line level thanks to [super_stack][SS] mechanisms.
 
 
-#### Adding extra layers
+### 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
@@ -148,14 +259,165 @@ layers.
 
 But basically just create your new layer, gives it a priority and add it to the orchestrator.
 
+### Changing the way things are merged
+
+The [super_stack gem][SS] defines some different merge policies. By default `stacked_config` will use the
+`SuperStack::MergePolicies::FullMergePolicy` that merges hashes and arrays at all levels. But you can choose to completely
+change the merge behaviour by changing the merge policy. See [super_stack gem][SS] documentation for other merge
+policies.
+
+Merge policies can be changed either at orchestrator level or at layer level by setting the merge_policy property.
+
+This is actually exactly what happens when the `config-override` flag is passed on the command line. It triggers the
+change of the merge policy of the extra layer from `SuperStack::MergePolicies::FullMergePolicy` to
+`SuperStack::MergePolicies::OverridePolicy`.
+
+## A complete example of a program using `stacked_config`
+
+Save the following file somewhere as `example.rb`.
+
+You can use this as a template for your own scripts:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'stacked_config'
+
+class MyApp
+
+  VERSION = '0.0.1'
+  NAME = 'My brand new Application'
+  DESCRIPTION = 'Best app ever'
+
+  attr_reader :config
+
+  def initialize
+    @config = StackedConfig::Orchestrator.new
+    config.describes_application app_name: NAME, app_version: VERSION, app_description: DESCRIPTION
+    add_script_options
+  end
+
+
+  def add_script_options
+    config.add_command_line_section('Options for the script') do |slop|
+      slop.on :u, :useless, 'Stupid option', :argument => false
+      slop.on :an_int, 'Stupid option with integer argument', :argument => true, :as => Integer
+    end
+  end
+
+  def run
+    if config[:help]
+      puts config.command_line_help
+      exit 0
+    end
+    do_some_processing
+  end
+
+  def do_some_processing
+    # Here you would really start your process
+    config[:something] = 'Added something...'
+
+    if config[:verbose]
+      puts ' ## Here is a display of the config sources and contents'
+      puts config.detailed_layers_info
+      puts ' ## This the resulting merged config'
+      puts config[].to_yaml
+    end
+
+    puts ' ## Bye...'
+  end
+
+end
+
+MyApp.new.run
+```
+
+If you run
+
+    $ ./example.rb
+
+You would get
+
+```
+ ## Bye...
+```
+
+If you run
+
+    $ ./example.rb --help
+
+You would get
+
+```
+Usage: example [options]
+My brand new Application Version: 0.0.1
+
+Best app ever
+-- Generic options -------------------------------------------------------------
+        --auto                 Auto mode. Bypasses questions to user.
+        --simulate             Do not perform the actual underlying actions.
+    -v, --verbose              Enable verbose mode.
+    -h, --help                 Displays this help.
+-- Configuration options -------------------------------------------------------
+        --config-file          Specify a config file.
+        --config-override      If specified override all other config.
+-- Options for the script ------------------------------------------------------
+    -u, --useless              Stupid option
+        --an_int               Stupid option with integer argument
+```
+
+If you run
+
+    $ ./example.rb --verbose
+
+You would get
+```
+ ## Here is a display of the config sources and contents
+--------------------------------------------------------------------------------
+System-wide configuration level
+There is no file attached to this level.
+There is no data in this layer
+--------------------------------------------------------------------------------
+Global configuration level
+There is no file attached to this level.
+There is no data in this layer
+--------------------------------------------------------------------------------
+User configuration level
+There is no file attached to this level.
+There is no data in this layer
+--------------------------------------------------------------------------------
+Specific config file configuration level
+There is no file attached to this level.
+There is no data in this layer
+--------------------------------------------------------------------------------
+Command line configuration level
+There is no file attached to this level.
+This layer contains the following data:
+--- !ruby/hash:StackedConfig::Layers::CommandLineLayer
+:verbose: true
+
+--------------------------------------------------------------------------------
+Overridden configuration level
+There is no file attached to this level.
+This layer contains the following data:
+--- !ruby/hash:SuperStack::Layer
+:something: Added something...
+
+--------------------------------------------------------------------------------
+ ## This the resulting merged config
+---
+:verbose: true
+:something: Added something...
+ ## Bye...
+```
 
 ## Contributing
 
-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
+1. [Fork it] ( https://github.com/lbriais/stacked_config/fork ), clone your fork.
+2. Create your feature branch (`git checkout -b my-new-feature`) and develop your super extra feature.
+3. Commit your changes (`git commit -am 'Add some feature'`).
+4. Push to the branch (`git push origin my-new-feature`).
+5. Create a 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"

data/lib/stacked_config/orchestrator.rb

@@ -14,30 +14,6 @@ module StackedConfig
       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 /\.[^\.]+$/, ''

data/lib/stacked_config/program_description_helper.rb

@@ -42,6 +42,32 @@ module StackedConfig
 
     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 describes_application(options = {})
       self.app_name = options.fetch(:app_name, nil)
       self.app_version = options.fetch(:app_version, nil)

data/lib/stacked_config/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stacked_config
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Laurent B.