cockpit 0.0.1.7 → 0.1.1

data/README.markdown

@@ -1,225 +1,126 @@
-# Cockpit
+<h1>Cockpit <img src='http://imgur.com/oXAb6.png' width='16' height='15'/></h1>
 
-<q>Super DRY Settings for Ruby, Rails, and Sinatra Apps.</q>
+> Super DRY Settings for Ruby, Rails, and Sinatra Apps.  Thin layer above wycat's [Moneta](http://github.com/wycats/moneta) for pluggable backend support.
 
-I am going to use this in all future gems that need configurable variables.  Reason being, every gem uses _some_ configurable variables, and you end up writing the same code over and over again.
+## How it works
 
-This will make it so if say 10 gems have custom settings, you can change this:
+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.
 
-    Paperclip.config  = ...
-    S3.configure      = ...
-    Authlogic.setup   = ...
-    MyApp.settings    = ....
-    
-to this:
+You define settings like this:
 
-    Settings do
-      paperclip       ...
-      s3              ...
-      authentication  ...
-      app             ...
+    settings = Cockpit "mongo" do
+      site do
+        title "My Site"
+        time_zone lambda { "Hawaii" }
+        feed do
+          per_page 10
+          formats %w(rss atom)
+        end
+      end
     end
 
-    Paperclip.config  = Settings(:paperclip)
-    S3.configure      = Settings(:s3)
-    Authlogic.setup   = Settings(:authentication)
-    MyApp.settings    = Settings(:app)
-    
-Which translates to 1, uniform, clean, configuration file.
-
-## Install
+That gives you [this data structure](http://gist.github.com/558480), which is accessed internally as a flat hash with keys like this:
 
-    sudo gem install cockpit
-    
-## Usage
+    ["site.feed.formats", "site.time_zone", "site.feed.per_page", "site", "site.feed", "site.title"]
+       
+## Global and Instance Settings
 
-### Migration
+By default you will have 1 set of global settings, accessible via `Cockpit::Settings.root` which is populated in this call:
 
-    create_table :settings, :force => true do |t|
-      t.string :key
-      t.string :value
-      t.string :cast_as
-      t.string :configurable_type
-      t.integer :configurable_id
+    Cockpit "mongo" do
+      site do
+        author "Lance"
+      end
     end
+    
+If you want to have settings encapsulated in an independent scope, you can just assign that to a variable:
 
-### Setup (`config/initializers/settings.rb`)
-
-    Cockpit do
+    site_settings = Cockpit "mongo" do
       site do
-        title "Martini", :tooltip => "Set your title!"
-        tagline "Developer Friendly, Client Ready Blog with Rails 3"
-        keywords "Rails 3, Heroku, JQuery, HTML 5, Blog Engine, CSS3"
-        copyright "© 2010 Viatropos. All rights reserved."
-        timezones :value => lambda { TimeZone.first }, :options => lambda { TimeZone.all }
-        date_format "%m %d, %Y"
-        time_format "%H"
-        week_starts_on "Monday", :options => ["Monday", "Sunday", "Friday"]
-        language "en-US", :options => ["en-US", "de"]
-        touch_enabled true
-        touch_as_subdomain false
-        google_analytics ""
-        teasers :title => "Teasers" do
-          disable false
-          left 1, :title => "Left Teaser"
-          right 2
-          center 3
-        end
-        main_quote 1
+        author "Lance"
       end
-      asset :title => "Asset (and related) Settings" do
-        thumb do
-          width 100, :tip => "Thumb's width"
-          height 100, :tip => "Thumb's height"
-        end
-        medium do
-          width 600, :tip => "Thumb's width"
-          height 250, :tip => "Thumb's height"
+    end
+    
+## Associated Settings with Models
+
+You can also associate settings with any object (plain Object, ActiveRecord, MongoMapper::Document, etc.):
+
+    class User < ActiveRecord::Base
+      include Cockpit
+      
+      cockpit "mongo" do
+        preferences do
+          favorite_color "red"
         end
-        large do
-          width 600, :tip => "Large's width"
-          height 295, :tip => "Large's height"
+        settings do
+          google_analytics "123123123"
         end
       end
-      authentication :title => "Authentication Settings" do
-        use_open_id true
-        use_oauth true
-      end
-      front_page do
-        slideshow_tag "slideshow"
-        slideshow_effect "fade"
-      end
-      page do
-        per_page 10
-        feed_per_page 10
-      end
-      people do
-        show_avatars true
-        default_avatar "/images/missing-person.png"
-      end
-      social do
-        facebook "http://facebook.com/viatropos"
-        twitter "http://twitter.com/viatropos"
-      end
-      s3 do
-        key "my_key"
-        secret "my_secret"
-      end
     end
+    
+And access them like this:
 
-#### Get
+    user = User.new
+    user.cockpit["settings.google_analytics"] #=> "123123123"
+    user.cockpit["preferences.favorite_color"] = "green"
+    
+## Swappable Backend
 
-    Settings.get("site.title").value        #=> "Martini"
-    Settings.get("site.title.value")        #=> "Martini"
-    Settings("site.title").value            #=> "Martini"
-    Settings("site.title.value")            #=> "Martini"
-    Settings["site.title"].value            #=> "Martini"
-    Settings["site.title.value"]            #=> "Martini"
-    Settings.site.title.value               #=> "Martini" # doesn't pass through store yet
+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).
+
+The current backends supported are these keys:
+
+- mongodb (or 'mongo')
+- redis
+- active_record
+- file
+- memory
+- yaml
+
+It should be easy enough to wrap the rest of the Moneta adapters.
+
+This is specified as the first DSL attribute:
+
+    Cockpit "redis" do
+      site do
+        author "Lance"
+      end
+    end
     
-#### Set
-
-    Settings.set("site.title" => "Martini") #=> {:site => {:title => {:value => "Martini"}}}
-    Settings("site.title" => "Martini")     #=> {:site => {:title => {:value => "Martini"}}}
-    Settings["site.title"] = "Martini"      #=> {:site => {:title => {:value => "Martini"}}}
-    Settings.site.title = "Martini"         #=> {:site => {:title => {:value => "Martini"}}} # doesn't pass through store yet
-
-### Key points
-
-- Each node is any word you want
-- You can nest them arbitrarily deep
-- You can use Procs
-- Values are type casted
-- Settings can be defined in yaml or using the DSL.
-- The preferred way to _get_ values is `Settings("path.to.value").value`
-- You can add custom properties to each setting:
-  - `Settings("site.title").tooltip #=> "Set your title!"`
-- You have multiple storage options:
-  - `Settings.store = :db`: Syncs setting to/from ActiveRecord
-  - `Settings.store = :memory`: Stores everything in a Hash (memoized, super fast)
-- You can specify them on a per-model basis.
-
-Example:
+## Use Cases
 
-    class User < ActiveRecord::Base
-      acts_as_configurable :settings do
-        name "Lance", :title => "First Name", :options => ["Lance", "viatropos"]
-        favorite do
-          color "red"
-        end
+This makes it really easy to edit random settings from an interface, such as an admin panel.  Next goal is to add callbacks around save/destroy so you can run processes when settings are changed (such as changing your google_analytics, which would require re-rendering views if they were cached).
+
+The goal is to make this [enormous configuration dsl work](http://gist.github.com/558432), so I can define an entire site in a DSL.
+
+### Other API Notes
+
+When you specify the DSL, that creates a flat tree of defaults, which aren't saved to the database.  Then when you update the setting, it saves to the database, otherwise when the value is read and is null, it will use the default from the in-memory/dsl-defined tree.
+
+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
+      site do
+        time_zones "MST", :options => Proc.new { TZInfo::Timezone.all.map(&:name) }
       end
     end
     
-    User.new.settings #=> <#Settings @tree={
-      :favorite => {
-        :color => {:type=>:string, :value=>"red"}
-      },
-      :name => {:type=>:string, :title=>"First Name", :value=>"Lance", :options=>["Lance", "Viatropos"]}
-    }/>
+    assert_equal TZInfo::Timezone.all.map(&:name), Cockpit::Settings["site.time_zones"][:options].call
+    
+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:
+
+    class Bookmark < ActsAsJoinable::Relationship; end
+    
+    class User < ActiveRecord::Base
+      joins :posts, :as => :parent, :through => :bookmark
+    end
     
-### Why
-
-There's no standard yet for organizing random properties in Rails apps.  And settings should be able to be modified through an interface (think Admin panel).
-
-Cockpit encapsulates the logic common to:
-
-- Options
-- Preferences
-- Settings
-- Configuration
-- Properties and Attributes
-- Key/Value stores
-
-Sometimes you need a global store, sometimes that global store needs to be customizable by the user, sometimes each user has their own set of configurations.  This handles all of those cases.
-
-## Todo
-
-- Add ability to `freeze` certain branches of the tree (so plugins can use it and know `Settings.clear` won't remove it)
-- Settings should be sorted by the way they were constructed
-- Check type, so when it is saved it knows what to do.
-- Store global declarations in memory
-- Create "context" for each set of settings, giving it its own `tree`.  Allows mimicking subclasses.
-- `Settings` should be a collection of trees or `contexts`:
-    Settings
-      user
-        global
-          default
-          user_a
-          user_b
-      widget
-        global
-          default
-          widget_a
-          widget_b
-        text
-          default
-          widget_a
-          widget_b
-        social
-          default
-          widget_a
-          widget_b
-    Settings.for(:widget, :social) #=> default social widget settings.
-
-This ended up being very similar to i18n:
-
-- [http://guides.rubyonrails.org/i18n.html](http://guides.rubyonrails.org/i18n.html)
-- [I asked about this on the i18n lighthouse](http://i18n.lighthouseapp.com/projects/14947/tickets/21-abstract-out-configuration-functionality-from-i18n-into-separate-gem#ticket-21-1)
-
-I think the i18n gem should be broken down into two parts: Configuration (key/value store), and Translation.
-
-#### End Goal
-
-- Base key-value functionality gem, which allows you to store arbitrary key values in any database (similar to moneta).  Should store settings in MongoDB by default.
-- i18n and Cockpit build on top of that
-
-### Alternatives
-
-- [Preferences](http://github.com/pluginaweek/preferences)
-- [SettingsGoo](http://rubygems.org/gems/settings-goo)
-- [RailsSettings](http://github.com/Squeegy/rails-settings)
-- [SimpleConfig](http://github.com/lukeredpath/simpleconfig)
-- [Configatron](http://github.com/markbates/configatron)
-- [RConfig](http://github.com/rahmal/rconfig)
-- [Serenity](http://github.com/progressions/serenity)
-- [ApplicationSettings](http://github.com/bradhaydon/application_settings)
+<cite>copyright [@viatropos](http://viatropos.com) 2010</cite>

data/Rakefile

@@ -5,16 +5,17 @@ require 'rake/gempackagetask'
 spec = Gem::Specification.new do |s|
   s.name              = "cockpit"
   s.authors           = ["Lance Pollard"]
-  s.version           = "0.0.1.7"
-  s.summary           = "Cockpit: Super DRY Configuration for Ruby, Rails, and Sinatra Apps"
+  s.version           = "0.1.1"
+  s.summary           = "Super DRY Configuration Management for Ruby, Rails, and Sinatra Apps.  With Pluggable NoSQL/SQL backends using Moneta"
   s.homepage          = "http://github.com/viatropos/cockpit"
   s.email             = "lancejpollard@gmail.com"
-  s.description       = "Super DRY Configuration for Ruby, Rails, and Sinatra Apps"
+  s.description       = "Super DRY Configuration for Ruby, Rails, and Sinatra Apps.  With Pluggable NoSQL/SQL backends using Moneta"
   s.has_rdoc          = false
   s.rubyforge_project = "cockpit"
   s.platform          = Gem::Platform::RUBY
-  s.files             = %w(README.markdown Rakefile init.rb MIT-LICENSE) + Dir["{lib,rails,test,app}/**/*"] - Dir["test/tmp"]
+  s.files             = %w(README.markdown Rakefile MIT-LICENSE) + Dir["{lib,test,app}/**/*"] - Dir["test/tmp"]
   s.require_path      = "lib"
+  s.add_dependency("moneta")
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/lib/cockpit/core/definition.rb

@@ -0,0 +1,93 @@
+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
+        else
+          self.attributes = {}
+        end
+      else
+        self.attributes ||= {}
+      end
+      if block_given?
+        self.value ||= []
+        self.nested = true
+        instance_eval(&block)
+      else
+        self.value = *args.first
+        self.nested = false
+      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)
+      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
+          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
+        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)
+        else
+          self.value << Cockpit::Definition.new(method, *args, &block)
+        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)
+      end
+    end
+  end
+end

data/lib/cockpit/core/definitions.rb

@@ -0,0 +1,55 @@
+module Cockpit
+  # settings have one direct definition and many child definitions
+  class Definitions < Hash
+    attr_accessor :name, :scope
+    
+    def initialize(*args, &block)
+      define!(*args, &block)
+    end
+    
+    def define!(*args, &block)
+      options = args.extract_options!
+      options[:store] ||= args.first
+      options.each do |k, v|
+        send("#{k}=", v) if respond_to?("#{k}=")
+      end
+      raise ArgumentError.new("pass a :name to Cockpit::Setting.define!") if self.name.blank?
+      if block_given?
+        self << Cockpit::Definition.define!(&block)
+      end
+      self
+    end
+    
+    def <<(value)
+      ([value] + self.values).flatten.uniq.each do |definition|
+        self.merge!(definition.keys)
+      end
+      self
+    end
+    
+    def []=(key, value)
+      self << Cockpit::Definition.new(key, value) unless has_key?(key)
+      super(key.to_s, value)
+    end
+    
+    def [](key)
+      super(key.to_s)
+    end
+    
+    def to_hash
+      keys.inject({}) do |hash, key|
+        hash[key] = self[key].value
+        hash
+      end
+    end
+    
+    def method_missing(method, *args, &block)
+      if has_key?(method)
+        self[method]
+      else
+        super(method, *args, &block)
+      end
+    end
+    
+  end
+end

data/lib/cockpit/core/include.rb

@@ -0,0 +1,90 @@
+module Cockpit
+  def self.included(base)
+    base.send(:include, ObjectInclude)
+    if defined?(::ActiveRecord::Base) && base.ancestors.include?(::ActiveRecord::Base)
+      base.send(:include, ActiveRecordInclude)
+    end
+  end
+  
+  module ActiveRecordInclude
+    def self.included(base)
+      base.class_eval do
+        def self.cockpit(*args, &block)
+          if block_given? || @cockpit.nil?
+            @cockpit = Cockpit::Settings.new(
+              :name => self.name.underscore.gsub(/[^a-z0-9]/, "_").squeeze("_"),
+              :store => :active_record,
+              &block
+            )
+            
+            @cockpit.keys.each do |key|
+              next if key =~ /\./
+              
+              define_method key do
+                send(:cockpit)[key]
+              end
+              
+              define_method "#{key}?" do
+                !send(key).blank?
+              end
+            end
+            
+          else
+            @cockpit
+          end
+        end
+        
+        def cockpit
+          unless @cockpit
+            @cockpit = Cockpit::Settings.new(
+              :name => self.class.cockpit.name,
+              :store => :active_record,
+              :record => self
+            )
+          end
+          
+          @cockpit
+        end
+        
+        def get(key)
+          cockpit[key]
+        end unless respond_to?(:get)
+
+        def set(*args)
+          if args.last.is_a?(Hash)
+            cockpit.set(args.last)
+          else
+            cockpit[args.first] = args.last
+          end
+        end unless respond_to?(:set)
+      end
+    end
+  end
+  
+  module ObjectInclude
+    def self.included(base)
+      base.class_eval do
+        def self.cockpit(*args, &block)
+          if block_given?
+            @cockpit = Cockpit::Settings.new(
+              :name => self.name.underscore.gsub(/[^a-z0-9]/, "_").squeeze("_"),
+              :scope => "default",
+              :store => args.first || "memory",
+              &block
+            )
+          else
+            @cockpit
+          end
+        end
+        
+        def cockpit
+          unless @cockpit
+            @cockpit = self.class.cockpit.dup
+          end
+
+          @cockpit
+        end 
+      end
+    end
+  end
+end