bolts 0.1.0dev1

data/lib/bolts.rb

@@ -0,0 +1,3 @@
+module Bolts
+  require 'bolts/version'
+end

data/lib/bolts/application.rb

@@ -0,0 +1,69 @@
+module Bolts
+  class Application
+
+    # @!attribute [r] name
+    #   @return [String]
+    attr_reader :name
+
+    # @!attribute [r] initializers
+    #   @return [Array<Object>] A list of initializers to run before
+    #     application startup
+    attr_reader :initializers
+
+    # @!attribute [r] finalizers
+    #   @return [Array<Object>] A list of finalizers to run after application
+    #     completion
+    attr_reader :finalizers
+
+    # @!attribute [r] error_handlers
+    #   @return [Array<Object>] A list of erro handles to run in case of
+    #     application errors.
+    attr_reader :error_handlers
+
+    def initialize(name)
+      @name = name
+
+      @main = nil
+
+      @initializers = []
+      @finalizers   = []
+
+      @error_handlers = []
+    end
+
+    # Run the main body of the application
+    #
+    # This method takes a block that actually runs under the application,
+    # performs all initialization steps, runs the block, performs finalization
+    # steps, and runs error handlers if an error was raised.
+    #
+    # @return [void]
+    def run!
+      @initializers.each { |action| action.call(self) }
+      @main.call(self)
+      @finalizers.each { |action| action.call(self) }
+    rescue => e
+      @error_handlers.each { |action| action.call(self) }
+      raise e
+    end
+
+    # Add a new action to run on app initialization
+    def on_initialize(&block)
+      @initializers << block
+    end
+
+    # Add a new action to run on app finalization
+    def on_finalize(&block)
+      @finalizers << block
+    end
+
+    # Add a new action to run on app error
+    def on_error(&block)
+      @error_handlers << block
+    end
+
+    def on_run(&block)
+      @main = block
+    end
+  end
+end

data/lib/bolts/settings.rb

@@ -0,0 +1,7 @@
+module Bolts
+  module Settings
+    require 'bolts/settings/registry'
+    require 'bolts/settings/container'
+    require 'bolts/settings/mixin'
+  end
+end

data/lib/bolts/settings/container.rb

@@ -0,0 +1,89 @@
+require 'bolts/settings'
+
+# Defines a collection for application settings
+#
+# This implements a hierarchical interface to application settings. Containers
+# can define an optional parent container that will be used for default options
+# if those options aren't set on the given container.
+class Bolts::Settings::Container
+
+  # @!attribute [r] valid_keys
+  #   @return [Set<Symbol>] All valid keys defined on the container or parent container.
+  attr_accessor :valid_keys
+
+  # @param parent [Bolts::Settings::Container] An optional parent container
+  def initialize(parent = nil)
+    @parent = parent
+
+    @valid_keys = Set.new
+    @settings = {}
+  end
+
+  # Look up a value in the container. The lookup checks the current container,
+  # and then falls back to the parent container if it's given.
+  #
+  # @param key [Symbol] The lookup key
+  #
+  # @return [Object, nil] The retrieved value if present.
+  #
+  # @raise [Bolts::Settings::Container::InvalidKey] If the looked up key isn't
+  #   a valid key.
+  def [](key)
+    validate_key! key
+
+    if @settings[key]
+      @settings[key]
+    elsif @parent and (pkey = @parent[key])
+      @settings[key] = pkey
+      pkey
+    end
+  end
+
+  # Set a value on the container
+  #
+  # @param key [Symbol] The lookup key
+  # @param value [Object] The value to store in the container
+  #
+  # @raise [Bolts::Settings::Container::InvalidKey] If the looked up key isn't
+  #   a valid key.
+  def []=(key, value)
+    validate_key! key
+
+    @settings[key] = value
+  end
+
+  # Define a valid container key
+  #
+  # @note This should only be used by {#Bolts::Settings::ClassSettings}
+  #
+  # @param key [Symbol]
+  # @return [void]
+  def add_valid_key(key)
+    @valid_keys.add(key)
+  end
+
+  # Determine if a key is a valid setting.
+  #
+  # @param key [Symbol]
+  #
+  # @return [true, false]
+  def valid_key?(key)
+    if @valid_keys.include?(key)
+      true
+    elsif @parent and @parent.valid_key?(key)
+      @valid_keys.add(key)
+      true
+    end
+  end
+
+  private
+
+  def validate_key!(key)
+    unless valid_key?(key)
+      raise InvalidKey, "Key #{key} is not a valid key"
+    end
+  end
+
+  # @api private
+  class InvalidKey < StandardError; end
+end

data/lib/bolts/settings/definition.rb

@@ -0,0 +1,21 @@
+require 'bolts/settings'
+
+class Bolts::Settings::Definition
+
+  attr_reader :name
+  attr_reader :desc
+  attr_reader :default
+
+  attr_writer :value
+
+  def initialize(name, desc, default)
+
+    @name = name
+    @desc = desc
+    @default = default
+  end
+
+  def value
+    (! @value.nil?) ? @value : @default
+  end
+end

data/lib/bolts/settings/errors.rb

@@ -0,0 +1,7 @@
+require 'bolts/settings'
+
+module Bolts::Settings
+  class SettingsError < StandardError; end
+
+  class InvalidSetting < SettingsError; end
+end

data/lib/bolts/settings/mixin.rb

@@ -0,0 +1,58 @@
+require 'bolts/settings'
+
+module Bolts::Settings::Mixin
+
+  def self.included(klass)
+    klass.send(:include, InstanceMethods)
+    klass.send(:extend, ClassMethods)
+  end
+
+  module InstanceMethods
+
+    # @return [Bolts::Settings::Container] A settings container for the given instance.
+    def settings
+      @settings ||= Bolts::Settings::Container.new(self.class.settings)
+    end
+  end
+
+  module ClassMethods
+
+    # Bind to a setting registry so that global settings can change this class.
+    #
+    # @param registry [Bolts::Setting::Registry]
+    # @param name [String] The name of the setting to bind to
+    # @param block [Proc] An optional block to execute when the setting changes
+    def bind_setting(registry, name)
+      def_setting_attr(name)
+
+      registry.bind_watcher(self, name)
+    end
+
+    # Define a setting and optional default on the extending class.
+    #
+    # @param key [Symbol]
+    # @param default [Object]
+    #
+    # @return [void]
+    def def_setting_attr(key, default = nil)
+      defaults.add_valid_key(key)
+      defaults[key] = default if default
+    end
+
+    # A singleton settings container for storing immutable default configuration
+    # on the extending class.
+    #
+    # @return [Bolts::Settings::Container]
+    def defaults
+      @defaults ||= Bolts::Settings::Container.new
+    end
+
+    # A singleton settings container for storing manual setting configurations
+    # on the extending class.
+    #
+    # @return [Bolts::Settings::Container]
+    def settings
+      @settings ||= Bolts::Settings::Container.new(defaults)
+    end
+  end
+end

data/lib/bolts/settings/registry.rb

@@ -0,0 +1,104 @@
+require 'bolts/settings'
+require 'bolts/settings/definition'
+
+class Bolts::Settings::Registry
+
+  attr_reader :definitions
+
+  attr_reader :watchers
+
+  def initialize
+    @definitions = []
+
+    @watchers = Hash.new { |h, k| h[k] = [] }
+  end
+
+  # Create a new setting definition
+  #
+  # @example
+  #   reg.define_setting(
+  #     'my-setting',
+  #     :desc => 'setting description goes here',
+  #     :default => 'default value',
+  #   )
+  #
+  # @param name [String] The setting name
+  # @param opts [Hash]
+  #
+  # @param opts [String] :desc The setting description
+  # @param opts [Object] :default
+  def define_setting(name, options)
+    definition = Bolts::Settings::Definition.new(name, options[:desc], options[:default])
+    @definitions << definition
+  end
+
+  # Look up the definition with the given name.
+  #
+  # @param name [String]
+  # @return [Bolts::Setting::Definition, nil]
+  def definition(name)
+    @definitions.find { |definition| name == definition.name }
+  end
+
+  # Apply settings from a hash
+  #
+  # @param hash [Hash]
+  # @return [Hash] The hash with the processed values removed
+  def set_values(hash)
+    ret = hash.dup
+
+    hash.each_pair do |name, value|
+      if set_value(name, value)
+        ret.delete(name)
+      end
+    end
+
+    ret
+  end
+
+  # Set a definition value
+  #
+  # @param name [String]
+  # @param value [Object]
+  #
+  # @return [true, false] If the setting could be applied
+  def set_value(name, value)
+    if (setting_def = self.definition(name))
+      setting_def.value = value
+      true
+    else
+      false
+    end
+  end
+
+  alias :[]= :set_value
+
+  # Retrieve a definition value
+  #
+  # @param name [String]
+  #
+  # @return [Object]
+  def get_value(name)
+    if (setting_def = self.definition(name))
+      setting_def.value
+    end
+  end
+
+  alias :[] :get_value
+
+  # @param name [String] The setting name to bind to
+  # @param obj [#[]=] An object that can have properties set
+  def bind_watcher(name, settable)
+    @watchers[name] << settable
+  end
+
+  def notify_watchers
+    @watchers.each_pair do |name, list|
+      setting_def = self.definition(name)
+
+      list.each do |watcher|
+        watcher[name] = setting_def.value
+      end
+    end
+  end
+end

data/lib/bolts/version.rb

@@ -0,0 +1,3 @@
+module Bolts
+  VERSION = '0.1.0dev1'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'bolts'
+
+PROJECT_ROOT = File.expand_path('..', File.dirname(__FILE__))

data/spec/unit/application_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+require 'bolts/application'
+
+describe Bolts::Application do
+  let(:sequence) { [] }
+  subject do
+    described_class.new('test').tap do |app|
+      app.on_run { sequence << :main }
+    end
+  end
+
+  describe "with an initializer" do
+    it "hands the application to the initializer" do
+      subject.on_initialize { |app| expect(app).to eq subject }
+      subject.run!
+    end
+
+    it "runs the initializer before the main action" do
+      subject.on_initialize { sequence << :initializer }
+      subject.run!
+
+      expect(sequence).to eq [:initializer, :main]
+    end
+  end
+
+  describe "with a finalizer" do
+    it "hands the application to the finalizer" do
+      subject.on_finalize { |app| expect(app).to eq subject }
+      subject.run!
+    end
+
+    it "runs the finalizer after the main action" do
+      subject.on_finalize { sequence << :finalizer }
+      subject.run!
+      expect(sequence).to eq [:main, :finalizer]
+    end
+  end
+
+  describe "with an error handler" do
+    it "hands the application to the error handler" do
+      subject.on_error { |app| expect(app).to eq subject }
+      subject.on_run { raise "kaboom!" }
+      expect { subject.run! }.to raise_error StandardError, /kaboom!/
+    end
+
+    it "runs the error handler if an exception was raised" do
+      subject.on_error { sequence << :error }
+      subject.on_run { sequence << :main; raise "kaboom!" }
+      expect { subject.run! }.to raise_error StandardError, /kaboom!/
+      expect(sequence).to eq [:main, :error]
+    end
+
+    it "doesn't run the error handler on normal application exit" do
+      subject.on_error { sequence << :error }
+      subject.run!
+      expect(sequence).to eq [:main]
+    end
+  end
+end

data/spec/unit/settings/container_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+require 'bolts/settings'
+
+describe Bolts::Settings::Container do
+
+  describe 'validating keys' do
+    it 'can add new valid keys' do
+      subject.add_valid_key(:v)
+      subject[:v]
+    end
+
+    it 'can check if a key is valid' do
+      subject.add_valid_key(:v)
+      expect(subject.valid_key?(:v)).to be_true
+    end
+
+    it 'can list all valid keys' do
+      subject.add_valid_key(:v)
+      subject.add_valid_key(:w)
+
+      expect(subject.valid_keys).to include :v
+      expect(subject.valid_keys).to include :w
+    end
+  end
+
+  describe 'specifying settings' do
+    it 'fails if a setting application uses an invalid key' do
+      expect { subject[:invalid] = 'fail' }.to raise_error Bolts::Settings::Container::InvalidKey
+    end
+
+    it 'can look up values that it sets' do
+      subject.add_valid_key :v
+      subject[:v] = 'set'
+      expect(subject[:v]).to eq 'set'
+    end
+  end
+
+  describe 'looking up settings' do
+    before do
+      subject.add_valid_key :v
+    end
+
+    it 'fails if a setting lookup uses an invalid key' do
+      expect { subject[:invalid] }.to raise_error Bolts::Settings::Container::InvalidKey
+    end
+
+    it 'returns nil if a key is valid but no setting is present' do
+      expect(subject[:v]).to be_nil
+    end
+
+    describe 'with a parent container' do
+      let(:parent) { described_class.new.tap { |p| p.add_valid_key :v } }
+      subject { described_class.new(parent) }
+
+      it 'uses its setting over a parent value' do
+        subject[:v] = 'child'
+        parent[:v] = 'parent'
+        expect(subject[:v]).to eq 'child'
+      end
+
+      it 'falls back to the parent value if it does not have a value' do
+        parent[:v] = 'parent'
+        expect(subject[:v]).to eq 'parent'
+      end
+    end
+  end
+end

data/spec/unit/settings/definition_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+require 'bolts/settings/definition'
+
+describe Bolts::Settings::Definition do
+
+  subject do
+    described_class.new(
+      'test',
+      'description here',
+      'default value'
+    )
+  end
+
+  it "has a name" do
+    expect(subject.name).to eq 'test'
+  end
+
+  it "has a description" do
+    expect(subject.desc).to eq 'description here'
+  end
+
+  it "has a default value" do
+    expect(subject.default).to eq 'default value'
+  end
+
+  it "prefers an explicit value over a default value" do
+    subject.value = 'explicit!'
+    expect(subject.value).to eq 'explicit!'
+  end
+
+  it "uses a default value if no explicit value is specified" do
+    subject.value = nil
+    expect(subject.value).to eq 'default value'
+  end
+end

data/spec/unit/settings/registry_spec.rb

@@ -0,0 +1,95 @@
+require 'spec_helper'
+require 'bolts/settings/registry'
+
+describe Bolts::Settings::Registry do
+
+  it "can define new settings" do
+    subject.define_setting('something', :desc => 'a setting definition!')
+    expect(subject.definitions).to have(1).items
+    expect(subject.definition('something')).to be_a_kind_of Bolts::Settings::Definition
+  end
+
+  describe "applying settings" do
+    before do
+      subject.define_setting('partycat', :desc => 'party cat loves to party')
+      subject.define_setting('partydog', :desc => 'party dog also loves to party')
+    end
+
+    it "applies settings from a hash" do
+      settings = {
+        'partycat' => 'parties!',
+        'partydog' => 'we love parties!',
+      }
+
+      subject.set_values(settings)
+
+      expect(subject.definition('partycat').value).to eq 'parties!'
+      expect(subject.definition('partydog').value).to eq 'we love parties!'
+    end
+
+    it "can directly retrieve a definition value" do
+      settings = {
+        'partycat' => 'parties!',
+        'partydog' => 'we love parties!',
+      }
+
+      subject.set_values(settings)
+
+      expect(subject.get_value('partycat')).to eq 'parties!'
+      expect(subject.get_value('partydog')).to eq 'we love parties!'
+    end
+
+    it "removes used settings from the returned hash" do
+      input = {
+        'partycat' => 'parties!',
+        'partydog' => 'we love parties!',
+        'partysnake' => 'partysnake hates parties'
+      }
+
+      output = subject.set_values(input)
+
+      expect(output).to have(1).items
+      expect(output).to include('partysnake' => 'partysnake hates parties')
+    end
+
+    it "doesn't modify the hash in place" do
+      input = {
+        'partycat' => 'parties!',
+        'partydog' => 'we love parties!',
+        'partysnake' => 'partysnake hates parties'
+      }
+
+      subject.set_values(input)
+
+      expect(input).to eq input
+    end
+
+    it "applies a single setting and value" do
+      subject.set_value('partycat', 'parties!')
+      expect(subject.definition('partycat').value).to eq 'parties!'
+    end
+  end
+
+  describe "binding values" do
+    let(:container) { double('settings container') }
+
+    before do
+      subject.define_setting('partycat', :desc => 'party cat loves to party')
+      subject.set_value('partycat', 'parties!')
+    end
+
+    it "can bind objects to settings" do
+      subject.bind_watcher('partycat', container)
+
+      expect(subject.watchers).to include('partycat' => [container])
+    end
+
+    it "can notify bound objects" do
+      subject.bind_watcher('partycat', container)
+
+      expect(container).to receive(:[]=).with('partycat', 'parties!')
+
+      subject.notify_watchers
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: bolts
+version: !ruby/object:Gem::Version
+  version: 0.1.0dev1
+  prerelease: 5
+platform: ruby
+authors:
+- Adrien Thebo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+description: 
+email: adrien@somethingsinistral.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/bolts/settings.rb
+- lib/bolts/settings/errors.rb
+- lib/bolts/settings/registry.rb
+- lib/bolts/settings/container.rb
+- lib/bolts/settings/mixin.rb
+- lib/bolts/settings/definition.rb
+- lib/bolts/version.rb
+- lib/bolts/application.rb
+- lib/bolts.rb
+- spec/spec_helper.rb
+- spec/unit/settings/registry_spec.rb
+- spec/unit/settings/container_spec.rb
+- spec/unit/settings/definition_spec.rb
+- spec/unit/application_spec.rb
+homepage: http://github.com/adrienthebo/bolts
+licenses:
+- Apache 2.0
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Bolts is a foundation for writing applications
+test_files:
+- spec/unit/settings/registry_spec.rb
+- spec/unit/settings/container_spec.rb
+- spec/unit/settings/definition_spec.rb
+- spec/unit/application_spec.rb
+has_rdoc: