reference_book 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 380f06491602cd309c6565ce8ada2c5c63b688c7
+  data.tar.gz: 7a02e9c9e6b22611b12d4a0493c75a24204dcca0
+SHA512:
+  metadata.gz: 3cf69339ecfb6974f4eec6f1ce10da3385e956ebe1b205e88909ce89f4c642ed929f605877091073280ea04deba2e926fd5d1ef0aef171be397901d99c2f1276
+  data.tar.gz: 3709e458d2063e5baeebbacc41c73e55e4973781da300dafdf8e70a02f41c74fea017fc304c298ac406dc9fc88cbbdca7058e311b748654b9962e1536925cc59

data/.gitignore

@@ -0,0 +1,27 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+
+# OSX
+.Spotlight-V100
+.DS_Store
+.Trashes

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in reference_book.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Tommaso Pavese
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# ReferenceBook
+
+A multi-context configuration library and DSL.  
+**ReferenceBook** provides an easy interface to define, validate and query **multi-context** configuration data.
+
+What does **multi-context** mean?  
+Any setting that should be static and that exist in different alternative versions.
+
+
+
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Examples
+
+Lots are available [in the repo](https://github.com/tompave/reference_book/tree/master/examples).
+
+
+
+
+## Features/Problems
+
+* requires Ruby >= 2.0.0
+* simple configuration DSL, with validations
+* configuration data exists as frozen objects, not namespaced constants
+* library and books metaphor
+* easy and flexible query interface
+
+
+
+
+
+
+
+## Rubies
+
+**ReferenceBook** requires a Ruby patch level `>= 2.0`.  
+It doesn't use any _2-only_ syntax features, but it does rely on some core classes' methods that only appeared with MRI 2.0.0.
+
+**MRI**: supported, tested with 2.0 and 2.1.  
+**JRuby**: tested in 2.0 mode (`JRUBY_OPTS=--2.0 rake test`).  
+**Rubinius**: not supported, even in 2.1 mode its standard library classes seem to expose a 1.9 interface.  
+
+
+## Tests
+
+`rake test`
+
+
+
+
+## To Do
+
+* add support for different libraries, each with an enforced book structure
+* make it work with Ruby 1.9.3 (involves implementing methods that at the moment are provided by core classes).
+
+
+## Installation
+
+
+Add this line to your application's Gemfile:
+
+    gem 'reference_book'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install reference_book
+
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/reference_book/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 a new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end

data/examples/config.rb

@@ -0,0 +1,59 @@
+# To optionally define and enforce a static book structure.
+# Without this, books are free-form.
+#
+ReferenceBook.define_book_structure :price, :currency, :country_name, :date_format
+
+
+# Given the structure defined above:
+
+
+# This is valid
+#
+ReferenceBook.write_book(title: "UnitedStates", library_key: :us) do |book|
+  book.price = 12
+  book.currency = '$'
+  book.country_name = 'US'
+  book.date_format = '%-m/%-d/%Y'
+end
+
+
+# This is valid too. The library_key will be ':united_kingdom'
+#
+ReferenceBook.write_book(title: "UnitedKingdom") do |book|
+  book.price = 10
+  book.currency = '£'
+  book.country_name = 'UK'
+  book.date_format = '%-d/%-m/%Y'
+end
+
+
+# This will raise an error because of the missing keys
+#
+ReferenceBook.write_book(title: "Canada") do |book|
+  book.price = 12
+end
+
+
+# This will raise an error because of the unexpected key
+#
+ReferenceBook.write_book(title: "Italy") do |book|
+  book.price = 10
+  book.currency = '€'
+  book.country_name = 'Italy'
+  book.date_format = '%-d/%-m/%Y'
+  book.international_prefix = '+39'
+end
+
+
+
+# This will raise an error because 'title' and 'library_key' have
+# a special meaning, and must be defined as method parameters
+
+ReferenceBook.write_book(title: "Spain") do |book|
+  book.price = 10
+  book.currency = ''
+  book.country_name = 'Spain'
+  book.date_format = '%-d/%-m/%Y'
+  book.title = 'Spain'
+  book.library_key = :spain
+end

data/examples/interface_and_use.rb

@@ -0,0 +1,129 @@
+# Given this configuration:
+
+ReferenceBook.write_book(title: "Elf") do |book|
+  book.strength     = 0
+  book.dexterity    = +2
+  book.constitution = -2
+  book.intelligence = 0
+  book.wisdom       = 0
+  book.charisma     = 0
+end
+
+ReferenceBook.write_book(title: "Dwarf") do |book|
+  book.strength     = 0
+  book.dexterity    = 0
+  book.constitution = +2
+  book.intelligence = 0
+  book.wisdom       = 0
+  book.charisma     = -2
+end
+
+ReferenceBook.write_book(title: "Halfling") do |book|
+  book.strength     = -2
+  book.dexterity    = +2
+  book.constitution = 0
+  book.intelligence = 0
+  book.wisdom       = 0
+  book.charisma     = 0
+end
+
+
+
+
+# The books can be retrieved with:
+
+ReferenceBook.library.index
+# => [:elf, :dwarf, :halfling]
+
+ReferenceBook.library.elf
+ReferenceBook.library[:elf]
+
+ReferenceBook::Library.elf
+ReferenceBook::Library[:elf]
+
+# => #<struct ReferenceBook::Book::Elf
+#               strength = 0,
+#               dexterity = 2,
+#               constitution = -2,
+#               intelligence = 0,
+#               wisdom = 0,
+#               charisma = 0,
+#               title = "Elf",
+#               library_key = :elf>
+
+
+# And each book can be queried with:
+
+ReferenceBook.library.elf.dexterity
+ReferenceBook.library.elf[:dexterity]
+# => 2
+
+ReferenceBook.library.dwarf.dexterity
+ReferenceBook.library.dwarf[:dexterity]
+# => 0
+
+ReferenceBook.library[:halfling].widsom
+ReferenceBook.library[:halfling][:wisdom]
+# => 0
+
+
+
+
+# You can wrap it with your own logic:
+
+def modifier_for(race, stat)
+  race = race.downcase.to_sym
+  stat = stat.downcase.to_sym
+  ReferenceBook.library[race][stat]
+end
+
+modifier_for('Dwarf', 'Charisma')
+# => -2
+
+
+
+# Books are read-only:
+
+ReferenceBook.library.dwarf.strength = 10
+# RuntimeError: can't modify frozen ReferenceBook::Book::Dwarf
+
+
+
+
+
+
+# Also, books are a thin subclass of the base Ruby Struct.
+# They are frozen, but expose the same interface:
+
+book = ReferenceBook.library.elf
+
+book.to_h
+# => {:strength => 0,
+#     :dexterity => 2,
+#     :constitution => -2,
+#     :intelligence => 0,
+#     :wisdom => 0,
+#     :charisma => 0,
+#     :title => "Elf",
+#     :library_key => :elf}
+
+book.to_a
+# => [0, 2, -2, 0, 0, 0, "Elf", :elf]
+
+book.members
+# => [:strength, :dexterity, :constitution, :intelligence, :wisdom, :charisma, :title, :library_key]
+
+book.select { |value| value != 0 }
+# => [2, -2, "Elf", :elf]
+
+
+book.each_pair { |k, v| puts "#{k}: #{v}" }
+# strength: 0
+# dexterity: 2
+# constitution: -2
+# intelligence: 0
+# wisdom: 0
+# charisma: 0
+# title: Elf
+# library_key: elf
+

data/examples/rails_controllers_and_views.rb

@@ -0,0 +1,65 @@
+# Given this configuration:
+
+ReferenceBook.write_book(title: 'Italy', library_key: :it) do |book|
+  book.currency  = '€'
+  book.time_zone = 'Europe/Rome'
+end
+
+ReferenceBook.write_book(title: 'UnitedKindom', library_key: :uk) do |book|
+  book.currency  = '£'
+  book.time_zone = 'Europe/London'
+end
+
+
+
+
+# All controllers can have access to the most appropriate book for the current locale:
+
+
+class ApplicationController < ActionController::Base
+  helper_method :ref_book
+
+private
+  
+  def ref_book
+    @ref_book ||= ReferenceBook.library[country_key_for_locale]
+  end
+
+
+  def country_key_for_locale
+    case I18n.locale
+      #...
+    end
+  end
+end
+
+
+
+
+# Or, to have more fine grained control:
+
+module CustomReferenceBookMethods
+  extend ActiveSupport::Concern
+
+  included do |base|
+    raise 'ops' unless base.instance_methods.include?(:country_key_for_locale)
+    helper_method :ref_book
+  end
+
+private
+  
+  def ref_book
+    @ref_book ||= ReferenceBook.library[country_key_for_locale]
+  end
+end
+
+
+
+
+class ApplicationController < ActionController::Base
+  include CustomReferenceBookMethods
+
+  def country_key_for_locale
+    # ...
+  end
+end

data/examples/rails_models.rb

@@ -0,0 +1,103 @@
+# Given this configuration:
+
+ReferenceBook.write_book(title: 'FreeAccount', library_key: :free) do |book|
+  book.max_blog_posts = 5
+  book.max_comments   = 10
+  book.max_votes      = 0
+  book.with_ads       = true
+  book.auth_policy    = Proc.new { |user, resource| resource.free? && !resource.already_viewed_by?(user) }
+end
+
+
+ReferenceBook.write_book(title: 'SilverAccount', library_key: :silver) do |book|
+  book.max_blog_posts = 50
+  book.max_comments   = 10_000
+  book.max_votes      = 1_000
+  book.with_ads       = false
+  book.auth_policy    = Proc.new { true }
+end
+
+
+ReferenceBook.write_book(title: 'GoldAccount', library_key: :gold) do |book|
+  book.max_blog_posts = 200
+  book.max_comments   = 50_000
+  book.max_votes      = 10_000
+  book.with_ads       = false
+  book.auth_policy    = Proc.new { true }
+end
+
+
+
+
+# An ActiveRecord model can intercat with it directly:
+
+class User < ActiveRecord::Base
+
+  validates :accounty_type, presence: true,
+                           inclusion: { in: %w(free silver gold) }
+
+
+  def ref_book
+    @ref_book ||= ReferenceBook.library[account_type.to_sym]
+  end
+
+
+  def max_blog_posts
+    ref_book.max_blog_posts
+  end
+
+
+  def can_access?(resource)
+    ref_book.auth_policy.call(self, resource)
+  end
+
+
+  def ads_list
+    if ref_book.with_ads
+      Ads::List.new(self)
+    else
+      Ads::None.new
+    end
+  end
+
+end
+
+
+
+# Or it can be implemented in a module
+
+
+module CustomReferenceBookMethods
+  def ref_book
+    @ref_book ||= ReferenceBook.library[account_type.to_sym]
+  end
+
+
+  def max_blog_posts
+    ref_book.max_blog_posts
+  end
+
+
+  def can_access?(resource)
+    ref_book.auth_policy.call(self, resource)
+  end
+
+
+  def ads_list
+    if ref_book.with_ads
+      Ads::List.new(self)
+    else
+      Ads::None.new
+    end
+  end
+end
+
+
+
+
+class User < ActiveRecord::Base
+  include CustomReferenceBookMethods
+
+  validates :accounty_type, presence: true,
+                           inclusion: { in: %w(free silver gold) }
+end

data/lib/reference_book/book.rb

@@ -0,0 +1,2 @@
+class ReferenceBook::Book < Struct
+end

data/lib/reference_book/errors.rb

@@ -0,0 +1,13 @@
+class ReferenceBook::Error < StandardError
+end
+
+
+class ReferenceBook::BookDefinitionError < ReferenceBook::Error
+end
+
+class ReferenceBook::LockedBookSpecError < ReferenceBook::Error
+end
+
+
+# class ReferenceBook::BookLookupError < ReferenceBook::Error
+# end

data/lib/reference_book/inflector.rb

@@ -0,0 +1,34 @@
+module ReferenceBook::Inflector
+  class << self
+
+    def constantize(raw)
+      if raw && raw.length > 0
+        title = raw.to_s.gsub(/[^a-zA-Z]/, '')
+        title[0] = title[0].upcase
+        title
+      end
+    end
+
+
+
+
+    def make_key(raw)
+      return nil unless raw
+      if raw.is_a? Symbol
+        raw
+      else
+        camel_to_snake(raw.to_s).gsub(/[^a-zA-Z0-9]/, '_').downcase.to_sym
+      end
+    end
+
+
+
+  private
+
+    CAMEL_REGEX = /([a-z])([A-Z])/
+    def camel_to_snake(raw)
+      raw.gsub(CAMEL_REGEX, '\1_\2').downcase
+    end
+
+  end
+end

data/lib/reference_book/library.rb

@@ -0,0 +1,64 @@
+module ReferenceBook::Library
+  class << self
+
+    def store(book)
+      verify_library_key!(book.library_key)
+
+      shelf[book.library_key] = book
+      index << book.library_key
+      define_accessor_for(book)
+      book
+    end
+
+
+    def shelf
+      @shelf ||= {}
+    end
+
+
+    def index
+      @index ||= []
+    end
+
+
+    def [](key)
+      shelf[key]
+    end
+
+
+    def empty!
+      index.each { |key| remove_accessor_for(key) }
+      @index = []
+      @shelf = {}
+      nil
+    end
+
+
+    def verify_library_key!(key)
+      if is_key_in_use?(key)
+        raise ReferenceBook::BookDefinitionError, "the library key '#{key}' is already in use."
+      end
+    end
+
+
+
+  private
+
+    def define_accessor_for(book)
+      self.define_singleton_method book.library_key do
+        self.shelf[book.library_key]
+      end
+    end
+
+
+    def remove_accessor_for(key)
+      self.singleton_class.send :remove_method, key
+    end
+
+
+    def is_key_in_use?(key)
+      index.include?(key)
+    end
+    
+  end
+end

data/lib/reference_book/setup/collector.rb

@@ -0,0 +1,28 @@
+require 'ostruct'
+
+class ReferenceBook::Setup::Collector < OpenStruct
+  def title=(*args)
+    protected_attribute_warning('title')
+  end
+
+  def library_key=(*args)
+    protected_attribute_warning('library_key')
+  end
+
+
+  def []=(key, value)
+    if key == :title || key == :library_key
+      protected_attribute_warning(key)
+    else
+      super
+    end
+  end
+
+
+
+private
+  
+  def protected_attribute_warning(key)
+    raise ReferenceBook::BookDefinitionError, "You can't set a Book's #{key} in its definition block"
+  end
+end

data/lib/reference_book/setup/locked_book_spec.rb

@@ -0,0 +1,51 @@
+class ReferenceBook::Setup::LockedBookSpec
+  
+
+  def initialize(keys_array)
+    if keys_array.any?
+      @book_keys = symbolize_and_sort(keys_array)
+    else
+      raise ReferenceBook::LockedBookSpecError, "A LockedBookSpec must have at least one key"
+    end
+  end
+
+
+
+  def verify_keys!(other_keys)
+    if @book_keys == other_keys.sort
+      true
+    else
+      missing    = @book_keys - other_keys
+      unexpected = other_keys - @book_keys
+
+      message = error_message_with(missing, unexpected)
+      raise ReferenceBook::BookDefinitionError, message
+    end
+  end
+
+
+
+
+
+private
+  
+  def symbolize_and_sort(keys)
+    keys.map(&:to_sym).sort
+  end
+
+
+
+  def error_message_with(missing, unexpected)
+    msg = "Couldn't create Book"
+    if missing.any?
+      msg << ", missing keys: [#{missing.join(', ')}]"
+    end
+
+    if unexpected.any?
+      msg << ", unexpected keys: [#{unexpected.join(', ')}]"
+    end
+
+    msg
+  end
+end
+