Files | Admin

Notes:

Release Name: 0.6.4

Notes:
= Caesars - v0.6

A simple class for rapid DSL prototyping in Ruby.

== Installation

One of:

* gem install caesars
* copy lib/caesars.rb into your lib directory. 

Or for GitHub fans:

* gem install delano-caesars --source http://gems.github.com
* git clone git://github.com/delano/caesar.git


== EXAMPLE 1 -- A Simple DSL

     require 'caesars'

     class Flavour < Caesars  # Subclass Caesars. 
     end
     
     extend Flavour::DSL     # Bring the DSL into the current namespace. 
                             # This module is created dynamically based
                             # on the name of the subclass.
     
     flavour do              # Start drinking! I mean, start writing your
       spicy true            # domain specific language! 
       clamy true            # Use any attribute name you want.
       salty true
       vodka :very_true      # And any value you want. 
     end
     
     p @flavour              # => #<Flavour:0x3f56b0 ...>
     p @flavour.spicy        # => true



== EXAMPLE 2 -- Storing Blocks as Procs

     require 'caesars'
     
     class Staff < Caesars
     
       chill :calculate      # Delay execution of the blocks for the calculate
                             # attribute. They will be stored as Procs.                      
     end
     
     extend Staff::DSL
     
     # The top level method is the lower case name of the class. For deeper
     # names like Class::SecondLevel it will use the final name 
     # (i.e. secondlevel). You can supply an optional modifier name which 
     # will be included in the instance variable (@staff_fte).
     staff :fte do
       desc 'Our hard-working, "full-time" staff'

       location :splashdown do
         town :tsawwassen

         person :steve, :sheila do
           role :manager
         end

         person :steve do
           role :cook
           anger :high
           hours 25
           catchphrase "Rah! [strokes goatee]"
         end

         person :sheila do
           catchphrase "This gravy tastes like food I ate in a Mexican prison."
           hours rand(20)
           rate "9.35/h"
           calculate :salary do |gumption|
             ("%.2f" % [gumption * self.splashdown.sheila.rate.to_f]).to_f
           end
         end

         person :delano do
           role :cook
           rate "8.35/h"
           hours 57
           satisfaction :low
           calculate :salary do 
             self.splashdown.delano.rate.to_f * self.splashdown.delano.hours
           end
         end

       end
     end
     
     p @staff_fte                    # => #<Staff: ...>
     p @staff_fte.desc               # => Our hard-working, "full-time" staff
     
     # Deeper attributes are also available via instance methods
     p @staff_fte.splashdown.delano  # => {:role=>:cook, :rate=>"$8.35/h", :satisfaction=>:low}
     p @staff_fte.splashdown.sheila  # => {:role=>:manager, :catchphrase=>"This gravy tastes like food I ate in a Mexican prison."}
     p @staff_fte.splashdown.steve   # => {:role=>[:manager, :cook], :anger=>:high, :catchphrase=>"Rah! [strokes goatee]"}
     p @staff_fte.splashdown.delano.satisfaction   # => :low
     
     # You can also access them using hash syntax
     p @staff_fte.splashdown[:steve][:role]  # => [:manager, :cook]
     
     # The "chilled" attributes store their blocks as Procs and are not executed automatically. 
     # You can call them manually and send arguments like you normally would. 
     p @staff_fte.splashdown.delano.salary.call             # => 475.95
     p @staff_fte.splashdown.sheila.salary.call(rand(100))  # => 549.77


== EXAMPLE 3 -- External Config Files

     require 'caesars'
     
     class Food < Caesars
       chill :order
     end
     class Drink < Caesars
     end
     
     class PartyConfig < Caesars::Config
       dsl Food::DSL
       dsl Drink::DSL
     end
     
     conffile = File.join(File.dirname(__FILE__), 'party.conf')
     @config = PartyConfig.new(conffile)
     
     p @config.food.order.call   # => 10kg
     p @config[:drink][:wine]    # => 12L
     p @config                   # => <PartyConfig:0x3f780c ...>
     p @config.keys              # => [:food, :drink]
     
     # [... make changes to party.conf ...]
     
     @config.refresh

*party.conf*

     food do 
       oysters "10kg"
       order do
         self.oysters
       end
     end
     
     drink do
       wine "12L"
     end

== More Info

* GitHub[http://github.com/delano/caesars]
* Inspiration[http://www.youtube.com/watch?v=ycElb0tB9_U]
* Recipe[http://twitter.com/solutious/status/1264327499]

== Credits

* OrderedHash implementation by jan molic
* Delano Mandelbaum (delano@solutious.com)

== Thanks

* Clams, Tomatoes, Grey Goose, and the rest of the crew. 
* Caleb Buxton (http://cpb.ca) for early feedback.
* Solutious Inc (http://solutious.com)

== License

See: LICENSE.txt


Changes: CAESARS -- CHANGES #### 0.6.4 (2009-05-10) ############################### * CHANGE: OrderedHash support for Ruby 1.8 and JRuby #### 0.6.3 (2009-05-04) ############################### * FIXED: Bug in forced_hash, not creating some keys #### 0.6.2 (2009-05-03) ############################### * FIXED: When setting Caesars::Config.verbose it would get reset after a refresh. * FIXED: Handling a keyword that's passed to both forced_hash and chill * ADDED: Print message to STDERR when force refreshing in debug or verbose mode * ADDED: Caesars::SyntaxError #### 0.6.1 (2009-05-02) ############################### * ADDED: known_symbol? and known_symbol_by_glass? #### 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. * ADDED: Print error to STDERR when a duplicate key found for forced_hash keys * ADDED: Caesars.forced_array * CHANGE: Caesars.method_missing now stores and returns an empty Caesars::Hash for known methods that are called (currently only ones defined by forced_array) #### 0.5.4 (2009-04-11) ############################### * FIXED: find_deferred would abort early because the safety limit to prevent endless loops wasn't being reset between calls. #### 0.5.3 (2009-04-10) ############################### * ADDED: Better error handling when reading DSL config files * ADDED: forced_hash method #### 0.5.2 (2009-03-31) ############################### * ADDED: Caesars.debug?, Caesars.enable_debug, Caesars.disable_debug * CHANGED: find_deferred now supports nested Arrays. See rdocs. * BUG: Found bug related to string/symbol ambiguity when using find. It's not fixed yet so for now be mindful of which attributes are strings and which are symbols. String attributes are stored as strings but find and find_deferred look for symbols. The hash syntax and method accessors are not affected. #### 0.5.1 (2009-03-11) ############################### * FIXED: Method-syntax was broken for attributes of top level method * FIXED: Caesars::Hash#refresh was setting @options to nil * UPDATED: docs and bin/example to reflect Caesars::Hash changes. * FIXED: instance_variables in Ruby 1.9.1 returns Symbols #### 0.5.0 (2009-03-11) ############################### * FIXED: find_deferred now gracefully handles nil errors * ADDED: empty? method in Caesars::Config * ADDED: post processing hook in Caesars::Config#refresh * ADDED: Caesars::Hash#to_hash now recursively casts children to ::Hash. * FIXED: Added Array support to Caesars::Hash * ADDED: Setters for Caesars attributes * ADDED: Caesars::Config supports multiple config files * ADDED: Top level methods used more than once now merges values rather than overwrites. * ADDED: Caesars::Config supports reloading config files on the fly #### 0.4.2 (2009-03-05) ############################### * FIXED: missing bin/party.conf in gem release * FIXED: Now works with Ruby 1.8+ * ADDED: Cleaner rdocs. * TODO: Fix support for top level methods with names: food :extra do; end; # => food_extra #### 0.4.0 (2009-03-05) ############################### * CHANGE: Removed bloody method. We now parse blocks immediately. * CHANGE: Renamed virgin method to chill. * ADDED: Caesars::Config class for loading DSLs as config files. See Example 3. * ADDED: Added find_deferred method to automatically jump up the heirarchy when looking for a specific attribute. * ADDED: Added to_hash and [] methods to Caesars to make it more hashlike. * FIXED: "chilled" attributes weren't available by method name #### 0.3.2 (2009-03-04) ############################### * FIXED: Added file and line info for eval code (better debugging). * CHANGE: The top level DSL method names are now determined by by the class name. Some::ClassName becomes classname. This is less confusing than allowing it to be anything and makes it possible to use several DSLs in the same namespace. #### 0.3.1 (2009-03-04) ############################### * ADDED: Accept instances without a name * CHANGE: Updated examples. * ADDED: More rdocs. #### 0.3 (2009-03-04) ############################### Initial public release