caesars 0.5.6 → 0.6.0

data/CHANGES.txt

@@ -1,12 +1,19 @@
-CAESAR -- CHANGES
+CAESARS -- CHANGES
 
 
+#### 0.6.0 (2009-04-30) ###############################
+
+* ADDED: Forced reloading for Caesars::Config.refresh. This allows
+one DSL to affect the parsing of another. 
+* ADDED: Caesars.forced_ignore
+* ADDED: Better docs for Caesars::Config
+* ADDED: Ceasars::Config.has_key?
+
 
 #### 0.5.6 (2009-04-28) ###############################
 
 * FIXED: Bug in fixed_hash which wasn't forcing the hash man!
 
-
 #### 0.5.5 (2009-04-27) ###############################
 
 * CHANGE: Caesars.chill and Caesars.forced_hash can now be used together. 

data/README.rdoc

@@ -1,4 +1,4 @@
-= Caesars - v0.5
+= Caesars - v0.6
 
 A simple class for rapid DSL prototyping in Ruby.
 
@@ -15,7 +15,7 @@ Or for GitHub fans:
 * git clone git://github.com/delano/caesar.git
 
 
-== EXAMPLE 1 -- Flavour
+== EXAMPLE 1 -- A Simple DSL
 
      require 'caesars'
 
@@ -38,7 +38,7 @@ Or for GitHub fans:
 
 
 
-== EXAMPLE 2 -- Staff
+== EXAMPLE 2 -- Storing Blocks as Procs
 
      require 'caesars'
      
@@ -111,7 +111,7 @@ Or for GitHub fans:
      p @staff_fte.splashdown.sheila.salary.call(rand(100))  # => 549.77
 
 
-== EXAMPLE 3 -- External Config file
+== EXAMPLE 3 -- External Config Files
 
      require 'caesars'
      

data/caesars.gemspec

@@ -1,13 +1,14 @@
 @spec = Gem::Specification.new do |s|
-  s.name = %q{caesars}
-  s.version = "0.5.6"
-  s.date = %q{2009-04-28}
+  s.name = "caesars"
+  s.rubyforge_project = "caesars"
+  s.version = "0.6.0"
+  s.date = "2009-04-30"
   s.specification_version = 1 if s.respond_to? :specification_version=
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.authors = ["Delano Mandelbaum"]
-  s.description = %q{A simple class for rapid DSL prototyping in Ruby.}
-  s.summary = %q{Caesars: A simple class for rapid DSL prototyping in Ruby.}
+  s.description = %q{Rapid DSL prototyping in Ruby.}
+  s.summary = %q{Caesars: Rapid DSL prototyping in Ruby.}
   s.email = %q{delano@solutious.com}
 
   # = MANIFEST =
@@ -29,8 +30,7 @@
   s.has_rdoc = true
   s.homepage = %q{http://github.com/delano/caesar}
   s.extra_rdoc_files = %w[README.rdoc LICENSE.txt CHANGES.txt]
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Caesars: A simple class for rapid DSL prototyping in Ruby.", "--main", "README.rdoc"]
+  s.rdoc_options = ["--line-numbers", "--title", "Caesars: Rapid DSL prototyping in Ruby.", "--main", "README.rdoc"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.1.1}
-  s.rubyforge_project = "caesars"
+  s.rubygems_version = "1.1.1"
 end

data/lib/caesars.rb

@@ -1,5 +1,5 @@
 
-# Caesars -- A simple class for rapid DSL prototyping.
+# Caesars -- Rapid DSL prototyping in Ruby.
 #
 # Subclass Caesars and start drinking! I mean, start prototyping
 # your own domain specific language!
@@ -7,10 +7,11 @@
 # See bin/example
 #
 class Caesars
-  VERSION = 0.5
+  VERSION = 0.6
   @@debug = false
   @@chilled = {}
   @@forced_array = {}
+  @@forced_ignore = {}
   
   def Caesars.enable_debug; @@debug = true; end
   def Caesars.disable_debug; @@debug = false; end
@@ -27,7 +28,12 @@ class Caesars
     return false unless name
     @@forced_array.has_key?(name.to_sym)
   end
-  
+  # Is the given +name+ a forced ignore? 
+  # See Caesars.forced_ignore
+  def Caesars.forced_ignore?(name)
+    return false unless name
+    @@forced_ignore.has_key?(name.to_sym)
+  end
   
   # A subclass of ::Hash that provides method names for hash parameters.
   # It's like a lightweight OpenStruct. 
@@ -70,6 +76,7 @@ class Caesars
     @caesars_name = name if name
     @caesars_properties = Caesars::Hash.new
     @caesars_pointer = @caesars_properties
+    init if respond_to?(:init)
   end
   
   # Returns an array of the available 
@@ -231,6 +238,10 @@ class Caesars
   # previously) and also in subclasses of Caesars for returning the appropriate
   # attribute values. 
   def method_missing(meth, *args, &b)
+    if Caesars.forced_ignore?(meth)
+      STDERR.puts "Forced ignore: #{meth}" if Caesars.debug?
+      return
+    end
     
     # Handle the setter, attribute=
     if meth.to_s =~ /=$/ && @caesars_properties.has_key?(meth.to_s.chop.to_sym)
@@ -314,7 +325,11 @@ class Caesars
     module_eval %Q{
       def #{caesars_meth}(*caesars_names,&b)
         this_meth = :'#{caesars_meth}'
-
+        if Caesars.forced_ignore?(this_meth)
+          STDERR.puts "Forced ignore: \#{this_meth}" if Caesars.debug?
+          return
+        end
+        
         if @caesars_properties.has_key?(this_meth) && caesars_names.empty? && b.nil?
           return @caesars_properties[this_meth] 
         end
@@ -362,7 +377,7 @@ class Caesars
   #        end
   #      end
   #
-  #      @config.food.count.call(3)     # => 5
+  #      @food.count.call(3)    # => 5
   #
   def self.chill(caesars_meth)
     @@chilled[caesars_meth.to_sym] = true
@@ -378,15 +393,37 @@ class Caesars
   #      
   #      food do
   #        taste :delicious
-  #        sauce 
+  #        sauce :tabasco, :worcester
+  #        sauce :franks
   #      end
   #
-  #      @config.food.count.call(3)     # => 5
+  #      @food.sauce            # => [[:tabasco, :worcester], [:franks]]
+  #
   def self.forced_array(caesars_meth)
+    STDERR.puts "forced_array: #{caesars_meth}" if Caesars.debug?
     @@forced_array[caesars_meth.to_sym] = true
     nil
   end
   
+  # Specify a method that should always be ignored. 
+  # Here's an example:
+  #
+  #     class Food < Caesars
+  #       forced_ignore :taste
+  #     end
+  #     
+  #     food do
+  #       taste :delicious
+  #     end
+  #
+  #     @food.taste             # => nil
+  #
+  def self.forced_ignore(caesars_meth)
+    STDERR.puts "forced_ignore: #{caesars_meth}" if Caesars.debug?
+    @@forced_ignore[caesars_meth.to_sym] = true
+    nil
+  end
+  
   # Executes automatically when Caesars is subclassed. This creates the
   # YourClass::DSL module which contains a single method named after YourClass 
   # that is used to catch the top level DSL method. 
@@ -399,7 +436,8 @@ class Caesars
   #      end
   #
   def self.inherited(modname)
-    meth = (modname.to_s.split(/::/))[-1].downcase  # Some::ClassName => classname
+    # NOTE: We may be able to replace this without an eval using Module.nesting
+    meth = (modname.to_s.split(/::/))[-1].downcase  # Some::HighBall => highball
     module_eval %Q{
       module #{modname}::DSL
         def #{meth}(*args, &b)
@@ -448,6 +486,16 @@ class Caesars::Config
   
   @@glasses = []
   
+  # Used by postprocess to tell refresh to reload all configs.
+  class ForceRefresh < RuntimeError
+    # The list of config types that need to be refreshed. This is currently
+    # for informational-purposes only. It does not affect which files/config
+    # types are refreshed. See Caesars::Config::ForcedRefresh
+    attr_reader :glasses 
+    def initialize(*glasses); @glasses = glasses; end
+    def message; "Force refresh of: #{@glasses.join(',')}"; end
+  end
+  
   # +args+ is a last of config file paths to load into this instance.
   # If the last argument is a hash, it's assumed to be a list of 
   # options. The available options are:
@@ -459,62 +507,80 @@ class Caesars::Config
     @options = args.last.is_a?(Hash) ? args.pop : {}
     @paths = args.empty? ? [] : args
     @options = {}
-    
+    @forced_refreshes = 0
     refresh
   end
   
+  # Reset all config instance variables to nil.
   def caesars_init
     # Remove instance variables used to populate DSL data
-    instance_variables.each do |varname|
-      next if varname == :'@options' || varname == :'@paths'  # Ruby 1.9.1
-      next if varname == '@options' || varname == '@paths'  # Ruby 1.8
-      instance_variable_set(varname, nil)
-    end
-    
+    keys.each { |confname| instance_variable_set("@#{confname}", nil) }
     # Re-apply options
     @options.each_pair do |n,v|
       self.send("#{n}=", v) if respond_to?("#{n}=")
     end
-    
     check_paths     # make sure files exist
   end
   
-  # This method is a stub. It gets called by refresh after the 
-  # config file has be loaded. You can use it to do some post 
+  # This method is a stub. It gets called by refresh after each 
+  # config file has be loaded. You can use it to run file specific
   # processing on the configuration before it's used elsewhere. 
   def postprocess
   end
   
+  # Clear all current configuration (sets all config instance
+  # variables to nil) and reload all config files in +@paths+.
+  # After each path is loaded, Caesars::Config.postprocess is
+  # called. If a ForceRefresh exception is raise, refresh is
+  # run again from the start. This is useful in the case 
+  # where one DSL can affect the parsing of another. Note that
+  # refresh only clears the instance variables, the class vars
+  # for each of the DSLs are not affected so all calls to
+  # +forced_array+, +forced_hash+, +chill+ and +forced_ignore+
+  # are unaffected. 
+  #
+  # Rudy has an example of forced refreshing in action. See 
+  # the files (http://github.com/solutious/rudy):
+  #
+  # * +lib/rudy/config.rb+
+  # * +lib/rudy/config/objects.rb+. 
+  # 
   def refresh
-    caesars_init
-    
-    @paths.each do |path|
-      puts "Loading config from #{path}" if @verbose 
-      
-      begin
-        @@glasses.each { |glass| extend glass }
+    caesars_init    # Delete all current configuration
+    @@glasses.each { |glass| extend glass }
+
+    begin
+      @paths.each do |path|
+        puts "Loading config from #{path}" if @verbose || Caesars.debug?
         dsl = File.read path
-        
-        # We're using eval so the DSL code can be executed in this
-        # namespace.
-        eval %Q{
-          #{dsl}
-        }, binding, __FILE__, __LINE__
-        
-        postprocess
-        
-      rescue Caesars::Error => ex
-        STDERR.puts ex.message
-        STDERR.puts ex.backtrace if Caesars.debug?
-      rescue ArgumentError, SyntaxError => ex
-        STDERR.puts "Syntax error in #{path}."
-        STDERR.puts ex.message
-        STDERR.puts ex.backtrace if Caesars.debug?
-        exit 1
+        # eval so the DSL code can be executed in this namespace.
+        eval dsl, binding, __FILE__, __LINE__
+        # Execute Caesars::Config.postprocesses every time a file is loaded
+        postprocess # Can raise ForceRefresh
+      end
+    
+    rescue Caesars::Config::ForceRefresh => ex
+      @forced_refreshes += 1
+      if @forced_refreshes > 3
+        STDERR.puts "Too many forced refreshed (#{@forced_refreshes})"
+        exit 9
       end
+      STDERR.puts ex.message if Caesars.debug?
+      refresh
+      
+    rescue Caesars::Error => ex
+      STDERR.puts ex.message
+      STDERR.puts ex.backtrace if Caesars.debug?
+    rescue ArgumentError, SyntaxError => ex
+      STDERR.puts "Syntax error in #{path}."
+      STDERR.puts ex.message
+      STDERR.puts ex.backtrace if Caesars.debug?
+      exit 1
     end
   end
   
+  # Checks all values of +@paths+, raises an exception for nil
+  # values and file paths that don't exist.
   def check_paths
     @paths.each do |path|
       raise "You provided a nil value" unless path
@@ -522,7 +588,7 @@ class Caesars::Config
     end
   end
   
-  
+  # Do any of the known DSLs have config data?
   def empty?
     keys.each do |obj|
       return false if self.respond_to?(obj.to_sym)
@@ -530,18 +596,55 @@ class Caesars::Config
     true
   end
   
+  # Specify a DSL class (+glass+) to include in this config. 
+  # 
+  #     class CoolDrink < Caesars::Config
+  #       dsl CoolDrink::Flavours::DSL
+  #     end
+  #
   def self.dsl(glass)
     @@glasses << glass
   end
   
+  # Provide a hash-like interface for Config classes.
+  # +name+ is the name of a DSL config. 
+  #
+  #     class CoolDrink < Caesars::Config
+  #       dsl CoolDrink::Flavours::DSL
+  #     end
+  #
+  #     cd = CoolDrink.new('/path/2/config')
+  #     cd[:flavours]     # => {}
+  #
   def [](name)
     self.send(name) if respond_to?(name)
   end
-    
+  
+  # Returns the list of known DSL config names. 
+  #     class CoolDrink < Caesars::Config
+  #       dsl CoolDrink::Flavours::DSL
+  #     end
+  #
+  #     cd = CoolDrink.new('/path/2/config')
+  #     cd.keys           # => [:flavours]
+  #
   def keys
     @@glasses.collect { |glass| glass.methname }
   end
   
+  # Is +name+ a known configuration type?
+  #
+  #     class CoolDrink < Caesars::Config
+  #       dsl CoolDrink::Flavours::DSL
+  #     end
+  #
+  #     cd = CoolDrink.new('/path/2/config')
+  #     cd.has_key?(:taste)        # => false
+  #     cd.has_key?(:flavours)     # => true
+  #
+  def has_key?(name)
+    respond_to?(name)
+  end
 end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: caesars
 version: !ruby/object:Gem::Version 
-  version: 0.5.6
+  version: 0.6.0
 platform: ruby
 authors: 
 - Delano Mandelbaum
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-28 00:00:00 -04:00
+date: 2009-04-30 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: A simple class for rapid DSL prototyping in Ruby.
+description: Rapid DSL prototyping in Ruby.
 email: delano@solutious.com
 executables: []
 
@@ -40,9 +40,8 @@ licenses: []
 post_install_message: 
 rdoc_options: 
 - --line-numbers
-- --inline-source
 - --title
-- "Caesars: A simple class for rapid DSL prototyping in Ruby."
+- "Caesars: Rapid DSL prototyping in Ruby."
 - --main
 - README.rdoc
 require_paths: 
@@ -65,6 +64,6 @@ rubyforge_project: caesars
 rubygems_version: 1.3.2
 signing_key: 
 specification_version: 1
-summary: "Caesars: A simple class for rapid DSL prototyping in Ruby."
+summary: "Caesars: Rapid DSL prototyping in Ruby."
 test_files: []