cockpit 0.1.1 → 0.2.0

data/README.markdown

@@ -1,17 +1,25 @@
 <h1>Cockpit <img src='http://imgur.com/oXAb6.png' width='16' height='15'/></h1>
 
-> Super DRY Settings for Ruby, Rails, and Sinatra Apps.  Thin layer above wycat's [Moneta](http://github.com/wycats/moneta) for pluggable backend support.
+> Super DRY Settings for Ruby, Rails, and Sinatra Apps with pluggable backend support.
+
+## Install
+
+    sudo gem install cockpit
 
 ## How it works
 
-You can define arbitrarily nested key/value pairs of any type, and customize them from an Admin panel or the terminal, and save them to the MySQL, MongoDB, Redis, or even a File.
+You can define arbitrarily nested key/value pairs of any type, and customize them from an Admin panel or the terminal, and save them to the MySQL, MongoDB, Redis, in memory, or even a File.
+
+1. Settings can be associated with a model class
+2. Settings can be associated with a model instance, which can use the model class settings as defaults
+3. Settings can be global and not reference a model at all (basic key/value store).
 
 You define settings like this:
 
-    settings = Cockpit "mongo" do
+    Cockpit :active_record do
       site do
         title "My Site"
-        time_zone lambda { "Hawaii" }
+        time_zone :default => lambda { "Hawaii" }
         feed do
           per_page 10
           formats %w(rss atom)
@@ -19,73 +27,93 @@ You define settings like this:
       end
     end
 
-That gives you [this data structure](http://gist.github.com/558480), which is accessed internally as a flat hash with keys like this:
+That gives you an instance of `Cockpit::Settings`, a tree data structure.
 
-    ["site.feed.formats", "site.time_zone", "site.feed.per_page", "site", "site.feed", "site.title"]
-       
-## Global and Instance Settings
+## Global Settings API
 
-By default you will have 1 set of global settings, accessible via `Cockpit::Settings.root` which is populated in this call:
+If you've defined your `:active_record` settings like above, which are _global_ settings, you can use them like this:
 
-    Cockpit "mongo" do
-      site do
-        author "Lance"
-      end
-    end
+### Get Methods
+
+    Cockpit::Settings["site.feed.per_page"] #=> 10
+    Cockpit::Settings("site.feed.per_page") #=> 10
+    Cockpit::Settings.site.feed.per_page.value #=> 10
     
-If you want to have settings encapsulated in an independent scope, you can just assign that to a variable:
+Everything ultimately passes through the hash form of the method, `Cockpit::Settings["path"]`, so that's the most optimized way to do it.
 
-    site_settings = Cockpit "mongo" do
-      site do
-        author "Lance"
-      end
+You can also check to see if these settings exist:
+
+    Cockpit::Settings.site.feed.per_page? #=> true
+
+### Set Methods
+
+    Cockpit::Settings["site.feed.per_page"] = 20
+    Cockpit::Settings("site.feed.per_page", 20)
+    Cockpit::Settings.site.feed.per_page.value = 20
+    
+### Behind the Scenes
+
+When you define settings using the DSL, they get stored as `Cockpit::Spec` objects into a global hash in the `Cockpit::Settings` class, which is a dictionary of `specs[class][name] = spec`.  Global specs aren't associated with a class (e.g. model class), so the `class` is `NilClass`.  You can have multiple global settings classes if you'd like, just give them names:
+
+    Cockpit :store => :active_record, :name => :more_settings do
+      hello "world"
     end
     
-## Associated Settings with Models
+You can access specific global settings like this:
+
+    Cockpit::Settings.find(:more_settings).hello.value #=> "world"
+    
+## Instance Settings API
 
 You can also associate settings with any object (plain Object, ActiveRecord, MongoMapper::Document, etc.):
 
     class User < ActiveRecord::Base
       include Cockpit
       
-      cockpit "mongo" do
+      cockpit do
         preferences do
           favorite_color "red"
         end
         settings do
-          google_analytics "123123123"
+          birthday :after => :queue_birthday_message, :if => lambda { |key, value|
+            value =~ /\d\d\/\d\d\/\d\d\d\d/ # 10/03/1986
+          }
+          number_of_children, Integer
         end
       end
+      
+      def queue_birthday_message(key, value)
+        BirthdayMailer.enqueue(value # ,...)
+      end
     end
     
 And access them like this:
 
     user = User.new
-    user.cockpit["settings.google_analytics"] #=> "123123123"
+    user.cockpit["settings.number_of_children"] #=> 300
     user.cockpit["preferences.favorite_color"] = "green"
+    user.cockpit.settings.number_of_children.value = 0
+    user.cockpit.preferences? #=> true
     
-## Swappable Backend
+If your model class doesn't have methods named after the cockpit keys, it will generate methods for you and delegate them to the `cockpit`:
 
-Thanks to the work behind Moneta, there's a clear interface to key/value stores (and some people have added ActiveRecord support which I've included in this).
+    user.preferences.favorite_color? #=> true
+    user.settings? #=> true
+    user.preferences.favorite_color.value = "turquoise"
+    
+## Swappable Backend
 
 The current backends supported are these keys:
 
-- mongodb (or 'mongo')
-- redis
 - active_record
-- file
+- mongo
 - memory
-- yaml
 
-It should be easy enough to wrap the rest of the Moneta adapters.
+Soon, or as need be, I'll support redis, files, couchdb, etc.  Haven't needed them yet.
 
-This is specified as the first DSL attribute:
+## Caching
 
-    Cockpit "redis" do
-      site do
-        author "Lance"
-      end
-    end
+For Active Record, Cockpit just adds a `has_many :settings` declaration to your model, and loads all of the settings on the first call, caching any further gets to settings for that model.  This means basically that settings are extendable database attributes for your model.
     
 ## Use Cases
 
@@ -99,7 +127,7 @@ When you specify the DSL, that creates a flat tree of defaults, which aren't sav
 
 You can also associate a hash with each setting definition.  This is great for say options, defaults, titles and tooltips, etc.  Here's an example:
 
-    Cockpit "active_record" do
+    Cockpit :active_record do
       site do
         time_zones "MST", :options => Proc.new { TZInfo::Timezone.all.map(&:name) }
       end
@@ -111,16 +139,11 @@ And you can access the definition object directly:
 
     Cockpit::Settings.definition("site.time_zones").attributes[:options]
     
-## Customizations
-
-Not yet implemented, just ideas.
-
-If you want to extend the Relationship model and reference that in your child/parent classes, you can do that like so:
+You can even do this in the terminal:
 
-    class Bookmark < ActsAsJoinable::Relationship; end
-    
-    class User < ActiveRecord::Base
-      joins :posts, :as => :parent, :through => :bookmark
-    end
+    irb -r 'rubygems'
+    require 'cockpit'
+    Cockpit { site { title "Lance" } }
+    puts Cockpit::Settings["site.title"] #=> "Lance"
     
 <cite>copyright [@viatropos](http://viatropos.com) 2010</cite>

data/lib/cockpit.rb

@@ -1,4 +1,5 @@
 require 'rubygems'
+require 'defined-by'
 
 this = File.expand_path(File.dirname(__FILE__))
 Dir["#{this}/cockpit/*"].each { |c| require c unless File.directory?(c) }

data/lib/cockpit/core/definition.rb

@@ -1,92 +1,203 @@
 module Cockpit
-  # This class defines default properties for a setting object, based on the DSL
-  class Definition
-    # keys is the nested keys associated with child values
-    attr_accessor :key, :value, :keys, :nested, :parent, :attributes, :type
-    
-    def initialize(key, *args, &block)
-      process(key, *args, &block)
-    end
-    
-    def process(key, *args, &block)
-      self.key = key.to_s
-      if args.length >= 1
-        if args.last.is_a?(Hash)
-          self.attributes = args.pop
+  class Settings
+    # This class defines default properties for a setting object, based on the DSL
+    class Definition
+      
+      class << self
+        def define!(options = {}, &block)
+          DefinedBy::DSL(&block).map do |key, value, dsl_block|
+            Cockpit::Settings::Definition.new(key, value, &dsl_block)
+          end
+        end
+      end
+      
+      # keys is the nested keys associated with child values
+      attr_reader :key, :value
+      attr_reader :attributes, :type, :callbacks, :validation
+      attr_reader :nested
+      
+      def initialize(key, *args, &block)
+        @key        = key.to_s
+        @attributes = {}
+        
+        if block_given?
+          @value    = self.class.define!(&block)
+          @nested   = true
         else
-          self.attributes = {}
+          args = args.pop
+          if args.is_a?(Array)
+            if args.last.is_a?(Hash)
+              @attributes.merge!(args.pop)
+            end
+            if args.last.is_a?(Class)
+              @type = args.pop
+            end
+            
+            args = args.pop if (args.length == 1)
+          end
+          
+          if attributes.has_key?(:default)
+            @value = attributes.delete(:default)
+          else
+            if args.is_a?(Class)
+              @type = args
+            else
+              @value = args
+            end
+          end
+          
+          @validation = attributes.delete(:if)
+          @callbacks = {
+            :before => attributes.delete(:before),
+            :after  => attributes.delete(:after)
+          }
+          
+          @type     ||= @value.class
+          @nested   = false
         end
-      else
-        self.attributes ||= {}
       end
-      if block_given?
-        self.value ||= []
-        self.nested = true
-        instance_eval(&block)
-      else
-        self.value = *args.first
-        self.nested = false
+      
+      def each(&block)
+        iterate(:each, &block)
       end
-    end
-    
-    def [](key)
-      if attributes.has_key?(key.to_sym)
-        attributes[key.to_sym]
-      elsif attributes.has_key?(key.to_s)
-        attributes[key.to_s]
-      else
-        method_missing(key)
+      
+      def map(&block)
+        iterate(:map, &block)
       end
-    end
-    
-    def nested?
-      self.nested == true
-    end
-    
-    def keys(separator = ".")
-      if nested?
-        value.inject({key => self}) do |hash, definition|
-          sub_definition = definition.keys.keys.inject({}) do |sub_hash, sub_key|
-            sub_hash["#{key}#{separator}#{sub_key}"] = definition.keys[sub_key]
-            sub_hash
+      
+      def iterate(method, &block)
+        keys.send(method) do |key|
+          case block.arity
+          when 1
+            yield(key)
+          when 2
+            yield(key, value_for(key))
           end
-          hash.merge(sub_definition)
         end
-      else
-        {key => self}
       end
-    end
-    
-    def method_missing(method, *args, &block)
-      method  = method.to_s.gsub("=", "").to_sym
-      if args.blank? && !block_given?
-        result = self.value.detect do |definition|
-          definition.key == method.to_s
+      
+      def keys
+        @keys ||= get_keys(false, :keys)
+      end
+      
+      def all_keys
+        @all_keys ||= get_keys(true, :all_keys)
+      end
+      
+      def child(key)
+        flatten[key.to_s]
+      end
+      
+      def value_for(key)
+        child(key).value rescue nil
+      end
+      
+      def [](key)
+        value_for(key)
+      end
+      
+      # map of nested key to definition
+      def flatten(separator = ".")
+        unless @flattened
+          if nested?
+            @flattened = value.inject({key => self}) do |hash, definition|
+              sub_definition = definition.keys.inject({}) do |sub_hash, sub_key|
+                sub_hash["#{key}#{separator}#{sub_key}"] = definition.child(sub_key)
+                sub_hash
+              end
+              hash.merge(sub_definition)
+            end
+          else
+            @flattened = {key => self}
+          end
         end
-        result ? result.value : nil
-      else
-        old_value = self.value.detect { |definition| definition.key == method.to_s }
-        if old_value
-          old_value.process(method, *args, &block)
+        
+        @flattened
+      end
+      
+      def to_hash
+        flatten.inject({}) do |hash, key, definition|
+          hash[key] = definition.value unless definition.nested?
+          hash
+        end
+      end
+      
+      def to_tree
+        {key => nested? ? value.map(&:to_tree) : value}
+      end
+      
+      def nested?
+        self.nested == true
+      end
+      
+      # callbacks
+      def with_callbacks(record, new_value, &block)
+        validate(record, new_value) do
+          callback(:before, record, new_value)
+          yield(new_value)
+          callback(:after, record, new_value)
+        end
+      end
+      
+      def validate(record, new_value, &block)
+        yield if execute(validation, record, new_value)
+      end
+      
+      def callback(name, record, new_value)
+        execute(callbacks[name], record, new_value)
+      end
+      
+      def execute(executable, record, new_value)
+        return true unless executable
+        
+        case executable
+        when String, Symbol
+          if record.respond_to?(executable)
+            case record.method(executable).arity
+            when 0
+              record.send(executable)
+            when 1
+              record.send(executable, key)
+            when 2
+              record.send(executable, key, new_value)
+            end
+          end
+        when Proc
+          case executable.arity
+          when 0, -1
+            if record
+              record.instance_eval(&executable)
+            else
+              executable.call
+            end
+          when 1
+            if record
+              record.instance_exec(key, &executable)
+            else
+              executable.call(key)
+            end
+          when 2
+            if record
+              record.instance_exec(key, new_value, &executable)
+            else
+              executable.call(key, new_value)
+            end
+          end
+        end
+      end
+      
+      protected
+      def get_keys(include_self, method)
+        if nested?
+          @keys = include_self ? [key] : []
+          @keys += value.map(&method).flatten.map {|key| "#{self.key}.#{key}"}
         else
-          self.value << Cockpit::Definition.new(method, *args, &block)
+          @keys = [key]
         end
       end
-    end
-    
-    class << self
-      # top-level declaration are the first keys in the chain
-      def define!(*args, &block)
-        @definitions = []
-        instance_eval(&block) if block_given?
-        definitions = @definitions
-        @definitions = nil
-        definitions
-      end
-      
-      def method_missing(method, *args, &block)
-        method  = method.to_s.gsub("=", "").to_sym
-        @definitions << Cockpit::Definition.new(method, *args, &block)
+      
+      def call_proc(proc, record)
+        
       end
     end
   end