levels 0.1.0

data/examples/01_base.rb

@@ -0,0 +1,6 @@
+group :webserver
+  set hostname: "localhost"
+
+group :task_queue
+  set workers: 1
+  set queues: -> { ["high", "low", webserver.hostname] }

data/examples/01_merge_to_json.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+#
+# This example sets up three levels:
+#
+#   * "Base" from examples/01_base.rb
+#   * "Prod" from examples/01_prod.json
+#   * "System Environment" with no prefix.
+#
+# Base defines the possible keys with default vaules, Prod changes a few of
+# those values, and System changes one more.
+#
+# A log of the levels used, and where each value came from is written to
+# STDERR. The merged output as JSON is written to STDOUT.
+
+examples="$(cd "$(dirname "$BASH_SOURCE")" && pwd)"
+
+# Alter a value via the system environment.
+export TASK_QUEUE_WORKERS='10'
+
+bundle exec levels \
+  --output json \
+  --level "Base" \
+  --level "Prod" \
+  --system \
+  $examples/01_base.rb \
+  $examples/01_prod.json
+

data/examples/01_prod.json

@@ -0,0 +1,8 @@
+{
+  "webserver": {
+    "hostname": "example.com"
+  },
+  "task_queue": {
+    "workers": 5
+  }
+}

data/examples/02_base.rb

@@ -0,0 +1,4 @@
+group :examples
+  set file_name: nil
+  set file_value1: file("02_value")
+  set file_value2: -> { file(examples.file_name) }

data/examples/02_merge_with_file.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+#
+# This example shows how to store and read a value from a file.
+#
+#   * examples/02_base.rb reads a file twice. Once where the file name
+#     is known, and once where it is unknown until set via an
+#     environment variable.
+
+examples="$(cd "$(dirname "$BASH_SOURCE")" && pwd)"
+
+# Alter a value via the system environment.
+export EXAMPLES_FILE_NAME='02_value'
+
+bundle exec levels \
+  --output json \
+  --level "Base" \
+  --system \
+  $examples/02_base.rb
+
+

data/examples/02_value

@@ -0,0 +1 @@
+Hello from the file!

data/levels.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/levels/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Ryan Carver"]
+  gem.email         = ["ryan@ryancarver.com"]
+  gem.description   = %q{A tool for reading and writing configuration data.}
+  gem.summary       = %q{A tool for reading and writing configuration data.}
+  gem.homepage      = "https://github.com/rcarver/levels"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "levels"
+  gem.require_paths = ["lib"]
+  gem.version       = Levels::VERSION
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "minitest", "~>4.0"
+end

data/lib/levels.rb

@@ -0,0 +1,77 @@
+require "json"
+require "yaml"
+require "open3"
+
+require "levels/version"
+
+require "levels/method_missing"
+require "levels/runtime"
+
+require "levels/audit"
+require "levels/configuration"
+require "levels/configured_group"
+require "levels/event_handler"
+require "levels/group"
+require "levels/key"
+require "levels/key_values"
+require "levels/lazy_evaluator"
+require "levels/level"
+require "levels/setup"
+
+require "levels/input/json"
+require "levels/input/ruby"
+require "levels/input/system"
+require "levels/input/yaml"
+
+require "levels/output/json"
+require "levels/output/system"
+require "levels/output/yaml"
+
+require "levels/system/constants"
+require "levels/system/key_formatter"
+require "levels/system/key_generator"
+require "levels/system/key_parser"
+
+module Levels
+
+  # Error thrown if a group is defined more than once.
+  DuplicateGroup = Class.new(StandardError)
+
+  # Error thrown when attempting to access a group that has not been defined.
+  UnknownGroup = Class.new(StandardError)
+
+  # Error thrown when attempting to read a key that has not been defined.
+  UnknownKey = Class.new(StandardError)
+
+  # Public: Begin a new setup. The setup is used to add one or more
+  # levels, then merged into a configuration.
+  #
+  # Examples
+  #
+  #   setup = Levels.setup
+  #   setup.add "Base", "file.rb"
+  #   setup.add_system
+  #   my_config = setup.merge
+  #
+  # Returns a Levels::Setup.
+  def self.setup
+    Levels::Setup.new
+  end
+
+  # Public: Get a merged configuration by using the setup.
+  #
+  # Examples
+  #
+  #   my_config = Levels.merge do |setup|
+  #     setup.add "Base", "file.rb"
+  #     setup.add_system
+  #   end
+  #
+  # Returns a Levels::Configuration.
+  def self.merge
+    setup = self.setup
+    yield setup if block_given?
+    setup.merge
+  end
+end
+

data/lib/levels/audit.rb

@@ -0,0 +1,24 @@
+module Levels
+  # In order to understand which of many possible values is actually used at
+  # runtime, Levels provides an audit trail for each value that's accessed.
+  # The audit trail is reported via the Levels::EventHandler interface.
+  module Audit
+
+    # Internal: Begin an audit.
+    #
+    # evaluator - Ducktype #call used to interpret raw values.
+    #
+    # Returns a Levels::Audit::RootObserver.
+    def self.start(evaluator)
+      Levels::Audit::RootObserver.new(evaluator)
+    end
+
+    autoload :GroupObserver,         'levels/audit/group_observer'
+    autoload :NestedGroupObserver,   'levels/audit/nested_group_observer'
+    autoload :RootObserver,          'levels/audit/root_observer'
+    autoload :Value,                 'levels/audit/value'
+    autoload :ValueObserver,         'levels/audit/value_observer'
+    autoload :Values,                'levels/audit/values'
+
+  end
+end

data/lib/levels/audit/group_observer.rb

@@ -0,0 +1,26 @@
+module Levels
+  module Audit
+    # The GroupObserver notifies when a value is accessed.
+    class GroupObserver
+
+      # Initialize a new GroupObserver.
+      #
+      # value_observer - Levels::Audit::ValueObserver.
+      # event_handler  - Levels::EventHandler.
+      #
+      def initialize(value_observer, event_handler)
+        @value_observer = value_observer
+        @event_handler = event_handler
+      end
+
+      # Retrieve the value at a group+value key and notify that it was read.
+      #
+      # Returns a Levels::Audit::Values.
+      def observe_values(levels, group_key, value_key)
+        values = @value_observer.observe_values(levels, group_key, value_key)
+        @event_handler.on_values(values)
+        values
+      end
+    end
+  end
+end

data/lib/levels/audit/nested_group_observer.rb

@@ -0,0 +1,37 @@
+module Levels
+  module Audit
+    # The NestedGroupObserver is like a GroupObserver, but used to
+    # observe what happens during recursive value evaluation.
+    class NestedGroupObserver
+
+      # Initialize a new NestedGroupObserver.
+      #
+      # value_observer - Levels::Audit::ValueObserver.
+      #
+      def initialize(value_observer)
+        @value_observer = value_observer
+        @values = []
+      end
+
+      # Retrieve the value at a group+value key.
+      #
+      # Returns a Levels::Audit::Values.
+      def observe_values(levels, group_key, value_key)
+        values = @value_observer.observe_values(levels, group_key, value_key)
+        @values << values
+        values
+      end
+
+      # Private: Notify that the observed values were seen. After notifying of
+      # the observed values, the set of observed values is reset.
+      #
+      # event_handler - Levels::EventHandler.
+      #
+      # Returns nothing.
+      def notify_nested(event_handler)
+        @values.each { |v| event_handler.on_nested_values(v) }
+        @values.clear
+      end
+    end
+  end
+end

data/lib/levels/audit/root_observer.rb

@@ -0,0 +1,63 @@
+module Levels
+  module Audit
+    # The RootObserver observes all accesses to group and value data.
+    class RootObserver
+
+      # Initialize a new RootObserver
+      #
+      # evaluator - Ducktype #call used to interpret raw values.
+      #
+      def initialize(evaluator)
+        @evaluator = evaluator
+        @current_value_stack = []
+      end
+
+      # Get an observer to watch when values are accessed from a group.
+      #
+      # event_handler - Levels::EventHandler to receive observations.
+      #
+      # Returns a Levels::Audit::GroupObserver.
+      def observe_group(user_observer)
+        if current_value
+          observer = NestedGroupObserver.new(value_observer)
+          current_value.add_nested_group_observer(observer)
+          observer
+        else
+          GroupObserver.new(value_observer, user_observer)
+        end
+      end
+
+      # Private: Set the current value context. This is used to capture
+      # recursive values.
+      #
+      # value - Levels::Audit::Value.
+      #
+      # Yields.
+      #
+      # Returns nothing.
+      def with_current_value(value)
+        begin
+          @current_value_stack << value
+          yield
+        ensure
+          @current_value_stack.pop
+        end
+      end
+
+      # Private: Get the current value.
+      #
+      # Returns a Levels::Audit::Value or nil.
+      def current_value
+        @current_value_stack.last
+      end
+
+    protected
+
+      def value_observer
+        ValueObserver.new(self, @evaluator)
+      end
+    end
+  end
+end
+
+

data/lib/levels/audit/value.rb

@@ -0,0 +1,64 @@
+module Levels
+  module Audit
+    # The Value represents one piece of configuration data that was originally
+    # stored in a Level.
+    class Value
+
+      # Initialize a new Value.
+      #
+      # level_name - String the name of the level this value was in.
+      # final      - Boolean true if this is the "final" value for a set of
+      #              levels.
+      #
+      def initialize(level_name, final, value = :__no_value__)
+        @level_name = level_name
+        @final = final
+        @nested_group_observers = []
+        if value == :__no_value__
+          @value = yield self if block_given?
+        else
+          @value = value
+        end
+      end
+
+      # Returns a String the name of the level.
+      attr_reader :level_name
+
+      # Returns the actual value.
+      attr_reader :value
+
+      # Returns the actual value.
+      alias raw value
+
+      # Returns a Boolean true if this is the final value.
+      def final?
+        !!@final
+      end
+
+      # Returns a Boolean true if this value is recursive.
+      def recursive?
+        !@nested_group_observers.empty?
+      end
+
+      # Public: Trigger a notification of the nested values. For any nested
+      # values, the event handler will receive the `#on_nested_values` message.
+      #
+      # event_handler - Levels::EventHandler.
+      def notify(event_handler)
+        @nested_group_observers.each do |ngo|
+          ngo.notify_nested(event_handler)
+        end
+      end
+
+      # Private: This is used to accumulate recursive group access.
+      def add_nested_group_observer(nested_group_observer)
+        @nested_group_observers << nested_group_observer
+      end
+
+      def inspect
+        value.inspect
+      end
+    end
+  end
+end
+

data/lib/levels/audit/value_observer.rb

@@ -0,0 +1,46 @@
+module Levels
+  module Audit
+    # The ValueObserver iterates over levels to find the appriate values.  It
+    # accumulates all possible values and indicates which is the "final" value.
+    class ValueObserver
+
+      # Initialize a new ValueObserver.
+      #
+      # root_observer - Levels::Audit::RootObserver.
+      # evaluator     - Ducktype #call used to interpret raw values.
+      #
+      def initialize(root_observer, evaluator)
+        @root_observer = root_observer
+        @evaluator = evaluator
+      end
+
+      # Get the possible values for a group+value key. The values are retrieved
+      # and evaluated in context of the RootObserver so that recursive values
+      # are tracked.
+      #
+      # levels    - Array of Levels::Level.
+      # group_key - Levels::Key.
+      # value_key - Levels::Key.
+      #
+      # Returns a Levels::Audit::Values.
+      def observe_values(levels, group_key, value_key)
+        valid_levels = levels.find_all do |level|
+          level.defined?(group_key) &&
+          level[group_key].defined?(value_key)
+        end
+
+        values = valid_levels.map.with_index do |level, index|
+          group = level[group_key]
+
+          Value.new(level._level_name, index == valid_levels.size - 1) do |value|
+            @root_observer.with_current_value(value) do
+              @evaluator.call(group[value_key])
+            end
+          end
+        end
+
+        Values.new(group_key, value_key, values)
+      end
+    end
+  end
+end

data/lib/levels/audit/values.rb

@@ -0,0 +1,66 @@
+module Levels
+  module Audit
+    # The Values is a set of possible values for a group+value key.
+    class Values
+
+      # Initialize a new Values.
+      #
+      # group_key - Levels::Key.
+      # value_key - Levels::Key.
+      # values    - Array of Levels::Audit::Value.
+      #
+      def initialize(group_key, value_key, values)
+        @group_key = group_key
+        @value_key = value_key
+        @values = values
+      end
+
+      # Public: Returns a Levels::Key.
+      attr_reader :group_key
+
+      # Public: Returns a Levels::Key.
+      attr_reader :value_key
+
+      # Public: Returns the Levels::Audit::Value marked final.
+      def final
+        @values.find { |v| v.final? }
+      end
+
+      # Public: Returns the actual user-defined final value.
+      def final_value
+        @values.find { |v| v.final? }.value
+      end
+
+      include Enumerable
+
+      # Public: Iterate over all potential values.
+      def each(&block)
+        @values.each(&block)
+      end
+
+      # Public: Returns true if there are no potential values.
+      def empty?
+        @values.empty?
+      end
+
+      # Public: Returns true if there is only a final value.
+      def only_final?
+        size == 1 && final
+      end
+
+      # Public: Returns true if any of the values are recursive.
+      def recursive?
+        @values.any? { |v| v.recursive? }
+      end
+
+      # Public: Returns the number of potential values.
+      def size
+        @values.size
+      end
+
+      def inspect
+        "<Values #{group_key.inspect} #{value_key.inspect} #{@values.inspect}>"
+      end
+    end
+  end
+end