levels 0.1.0

data/lib/levels/configuration.rb

@@ -0,0 +1,98 @@
+module Levels
+  # A Configuration is the merging of one or more levels. This is the top level
+  # object that you will interact with most.
+  #
+  # Examples
+  #
+  #   # In this example we'll represent a Level as a Hash.
+  #   level1 = { group1: { key1: 1 } }
+  #   level2 = { group1: { key1: 2, key2: 2 }, group2: { x: 9 } }
+  #
+  #   # The configuration exposes each group that exists in a Level.
+  #   config = Levels::Configuration.new([level1, level2])
+  #
+  #   # A Group may be accessed via hash syntax.
+  #   config[:group1] # => { key1: 2, key2: 2 }
+  #   # Or method syntax.
+  #   config.group1 # => { key1: 2, key2: 2 }
+  #
+  #   # You can check if a Group exists.
+  #   config.defined?(:group1) # => true
+  #   config.group1? # => true
+  #
+  class Configuration
+    include Levels::MethodMissing
+
+    # Internal: Initialze a new configuration.
+    #
+    # levels - Array of Levels::Level.
+    #
+    def initialize(levels, event_handler = nil)
+      @levels = levels
+      @event_handler = event_handler || NullEventHandler.new
+      @root_observer = Levels::Audit.start(LazyEvaluator.new(self))
+    end
+
+    # Public: Set the event handler. The event handler is notified whenever a
+    # key is read; allowing you to track exactly what is and isn't used at
+    # runtime.
+    #
+    # event_handler - Levels::EventHandler.
+    #
+    # Returns nothing.
+    def event_handler=(event_handler)
+      @event_handler = event_handler
+    end
+
+    # Public: Retrieve a group. The resulting group is the union of the named
+    # group from each Level that defines that group.
+    #
+    # group_key - Symbol name of the group.
+    #
+    # Examples
+    #
+    #   # In this example we'll represent a Level as a Hash.
+    #   level1 = { group: { key1: 1 } }
+    #   level2 = { group: { key1: 2, key2: 2 } }
+    #
+    #   config = Levels::Configuration.new([level1, level2])
+    #   config[:group] # => { key1: 2, key2: 2 }
+    #
+    # Returns a Levels::ConfiguredGroup.
+    # Raises Levels::UnknownGroup if the group is not defined.
+    def [](group_key)
+      raise UnknownGroup unless self.defined?(group_key)
+      group_observer = @root_observer.observe_group(@event_handler)
+      Levels::ConfiguredGroup.new(@levels, group_key, group_observer)
+    end
+
+    # Public: Determine if a group is defined. A group is defined if it exists
+    # in any Level.
+    #
+    # group_key - Symbol name of the group.
+    #
+    # Returns a Boolean.
+    def defined?(group_key)
+      @levels.any? { |level| level.defined?(group_key) }
+    end
+
+    def to_s
+      "<Levels::Configuration #{@levels.map { |l| l._level_name }.join(', ')}>"
+    end
+
+    # Returns an Enumerator which yields [gruop_name, Group#to_enum].
+    def to_enum
+      Enumerator.new do |y|
+        group_keys = Set.new
+        @levels.each do |level|
+          level.to_enum.each do |name, group|
+            group_keys << name
+          end
+        end
+        group_keys.each do |name|
+          y << [name, self[name].to_enum]
+        end
+      end
+    end
+  end
+end

data/lib/levels/configured_group.rb

@@ -0,0 +1,62 @@
+module Levels
+  # A ConfiguredGroup is the union of one or more Groups. When a key is read,
+  # the value returned is the value from the last Level that defines that key.
+  class ConfiguredGroup
+    include Levels::MethodMissing
+
+    # Internal: Initialize a configured group.
+    #
+    def initialize(levels, group_key, group_observer)
+      @levels = levels
+      @group_key = group_key
+      @group_observer = group_observer
+    end
+
+    # Public: Retrieve a value.
+    #
+    # value_key - Symbol name of the value.
+    #
+    # Returns the value stored at that key.
+    # Raises Levels::UnknownKey if the key is not defined.
+    def [](value_key)
+      raise UnknownKey unless self.defined?(value_key)
+      values = @group_observer.observe_values(@levels, @group_key, value_key)
+      values.final_value
+    end
+
+    # Public: Determine if a key is defined.
+    #
+    # value_key - Symbol name of the key.
+    #
+    # Returns a Boolean.
+    def defined?(value_key)
+      groups.any? { |group| group.defined?(value_key) }
+    end
+
+    def to_s
+      "<Levels::ConfiguredGroup #{@group_key}>"
+    end
+
+    # Returns an Enumerator which yields [key, value].
+    def to_enum
+      Enumerator.new do |y|
+        value_keys = Set.new
+        groups.each do |group|
+          group.to_enum.each do |key, value|
+            value_keys << key
+          end
+        end
+        value_keys.each do |key|
+          y << [key, self[key]]
+        end
+      end
+    end
+
+  protected
+
+    def groups
+      levels = @levels.find_all { |level| level.defined?(@group_key) }
+      levels.map { |level| level[@group_key] }
+    end
+  end
+end

data/lib/levels/event_handler.rb

@@ -0,0 +1,127 @@
+module Levels
+  # This is the interface for capturing what happens when a value is read.
+  # Capturing events exposes you to the audit trail system implemented in
+  # Levels::Audit.
+  #
+  #     class MyEventHandler
+  #
+  #       def on_values(values)
+  #         # This method is called any time a value is accessed.
+  #         # The argument `values` is a Levels::Audit::Values representing the
+  #         # set of all possible values.
+  #       end
+  #
+  #       def on_nested_values(values)
+  #         # Similar to `on_values`, but called when the values were found
+  #         # during the evaluation of another value.
+  #       end
+  #     end
+  #
+  module EventHandler
+
+    def on_values(values)
+    end
+
+    def on_nested_values(values)
+    end
+  end
+
+  # A null implementation.
+  class NullEventHandler
+    include EventHandler
+  end
+
+  module Colorizer
+
+    RESET =    "\033[0m"
+    FOREGROUND = {
+      black:   "\033[30m",
+      red:     "\033[31m",
+      green:   "\033[32m",
+      brown:   "\033[33m",
+      blue:    "\033[34m",
+      magenta: "\033[35m",
+      cyan:    "\033[36m",
+      white:   "\033[37m"
+    }
+
+    def foreground_color(name, str)
+      code = FOREGROUND[name] or raise ArgumentError, "Unknown color #{name.inspect}"
+      "#{code}#{str}#{RESET}"
+    end
+  end
+
+  class CliEventHandler
+    include Colorizer
+
+    def initialize(stream, color = false)
+      @stream = stream
+      @color = color
+      @indent = 0
+    end
+
+    def on_values(values)
+      write :white, "> #{values.group_key}.#{values.value_key}"
+      values.each do |value|
+        value.notify(self)
+        if value.final?
+          write :green, " + #{value.inspect} from #{value.level_name}"
+        else
+          write :red, " - #{value.inspect} from #{value.level_name}"
+        end
+      end
+    end
+
+    def on_nested_values(values)
+      indent do
+        on_values(values)
+      end
+    end
+
+  protected
+
+    def indent
+      begin
+        @indent += 1
+        yield
+      ensure
+        @indent -= 1
+      end
+    end
+
+    def write(color, str)
+      prefix = "  " * @indent
+      str = foreground_color(color, str) if @color
+      @stream.puts prefix + str
+    end
+  end
+
+  # A temporary implementation that will be moved back to config to
+  # restore its original behavior.
+  class ConfigCoreEventHandler
+
+    def initialize(log)
+      @log = log
+      @base_color = :magenta
+      @alt_color  = :cyan
+    end
+
+    def on_read_from_merged_group(group_name, key, levels)
+      final_level_name, final_value = levels.last
+
+      if levels.size == 1
+        @log << @log.colorize("Read #{group_name}.#{key} => #{final_value.inspect} from #{final_level_name}", @base_color)
+      else
+        skipped_levels = levels[0..-2]
+
+        @log << @log.colorize("Read #{group_name}.#{key}", @base_color)
+        @log.indent do
+          skipped_levels.each do |level_name, value|
+            @log << @log.colorize("Skip #{value.inspect} from #{level_name}", @alt_color)
+          end
+          @log << @log.colorize("Use  #{final_value.inspect} from #{final_level_name}", @base_color)
+        end
+      end
+    end
+  end
+end

data/lib/levels/group.rb

@@ -0,0 +1,61 @@
+module Levels
+  # A group is a set of key/value pairs containing your data.
+  #
+  # Examples
+  #
+  #     group = Levels::Group.new(name: "Joe", age: 33)
+  #
+  #     group.name # => "Joe"
+  #     group.age  # => 33
+  #
+  class Group
+    include Levels::MethodMissing
+
+    # Internal: Initialize a new group.
+    #
+    # data              - Hash of key/values for the group.
+    # value_transformer - Proc that takes (key, value) and returns value.
+    #
+    def initialize(data = {}, value_transformer = nil)
+      @values = Levels::KeyValues.new(data)
+      @value_transformer = value_transformer || -> key, value { value }
+    end
+
+    # Public: Get the value for a key.
+    #
+    # Returns the value.
+    # Raises Levels::UnknownKey if the key is not defined.
+    def [](value_key)
+      if @values.key?(value_key)
+        key, value = @values.pair(value_key)
+        @value_transformer.call(key.to_sym, value)
+      else
+        raise UnknownKey, "#{value_key.inspect} is not defined in #{self}"
+      end
+    end
+
+    # Public: Determine if a key is defined.
+    #
+    # Returns a Boolean.
+    def defined?(key)
+      @values.key?(key)
+    end
+
+    def to_s
+      "<Levels::Group>"
+    end
+
+    # Returns an Enumerator which yields [key, value].
+    def to_enum
+      Enumerator.new do |y|
+        @values.each do |key, value|
+          y << [key.to_sym, self[key]]
+        end
+      end
+    end
+
+    def eql_hash?(hash)
+      @values == Levels::KeyValues.new(hash)
+    end
+  end
+end

data/lib/levels/input/json.rb

@@ -0,0 +1,17 @@
+module Levels
+  module Input
+    # This input 
+    class JSON
+
+      def initialize(json_string)
+        @json = ::JSON.parse(json_string)
+      end
+
+      def read(level)
+        @json.each do |group_name, group|
+          level.set_group(group_name, group)
+        end
+      end
+    end
+  end
+end

data/lib/levels/input/ruby.rb

@@ -0,0 +1,120 @@
+module Levels
+  module Input
+    # This input provides a DSL for writing levels in ruby.
+    class Ruby
+
+      def initialize(ruby_string, file = "Code in Memory", line = 1)
+        @ruby_string = ruby_string
+        @file = file
+        @line = line
+      end
+
+      def read(level)
+        dsl = DSL.new(level)
+        dsl.instance_eval(@ruby_string, @file, @line)
+        dsl.close_current_group
+      end
+
+      # The Ruby syntax DSL. This syntax aims to be very readable and writable.
+      # A stateful syntax and no trailing commas allows values to be easily
+      # moved around without excess text editing.
+      #
+      # Examples
+      #
+      #     group :webserver
+      #       set hostname: "localhost"
+      #     group :task_queue
+      #       set workers: 1
+      #       set queues: -> { ["high", "low", webserver.hostname] }
+      #
+      class DSL
+        include Levels::Runtime
+
+        def initialize(level)
+          @level = level
+        end
+
+        # Public: Start a group.
+        #
+        # name - Symbol or String name of the group.
+        #
+        # Returns nothing.
+        # Raises a RuntimeError if the group has already been defined.
+        def group(name)
+          close_current_group
+          if @level.defined?(name)
+            raise RuntimeError, "Group has already been created: #{name.inspect}"
+          end
+          @group = name
+          @hash = {}
+          nil
+        end
+
+        # Public: Set a key/value pair in the current group.
+        #
+        # Arguments
+        #
+        # hash  - Hash of key/value pairs. The keys may be a Symbol or String.
+        #
+        # key   - Symbol or String key.
+        # value - Any value.
+        #
+        # Examples
+        #
+        #     # Ruby 1.9 Hash.
+        #     set key: "value"
+        #
+        #     # Ruby 1.9 Hash.
+        #     set :key => "value"
+        #
+        #     # Key can be a String.
+        #     set "key" => "value"
+        #
+        #     # Multiple key/values.
+        #     set :key => "value", :more => "values"
+        #
+        #     # Key, value.
+        #     set :key, "value"
+        #
+        # Returns nothing.
+        # Raises SyntaxError if no current group is defined.
+        # Raises ArgumentError if other forms of arguments are given
+        # Raises RuntimeError if a key has already been set.
+        def set(*args)
+          raise SyntaxError, "No group is defined" if @hash.nil?
+          case
+          when args.size == 1 && Hash === args.first
+            hash = args.first
+          when args.size == 2 && !(args.any? { |a| Hash === a })
+            hash = { args.first => args.last }
+          else
+            raise ArgumentError, "Set must be given a Hash or two arguments. Got #{args.inspect}"
+          end
+          key_values = Levels::KeyValues.new(@hash)
+          hash.keys.each do |key|
+            if key_values.key?(key)
+              raise RuntimeError, "Key has already been set: #{key.inspect}"
+            end
+          end
+          @hash.update(hash)
+          nil
+        end
+
+        def close_current_group
+          @level.set_group(@group, @hash) if @group
+          @group = nil
+          @hash = nil
+        end
+
+        def to_s
+          "<Levels>"
+        end
+
+        def inspect
+          "<Levels>"
+        end
+      end
+    end
+  end
+end
+