ambition 0.5.1 → 0.5.2

data/README

@@ -1,10 +1,24 @@
-Ambition
-========
+= Ambition
+
+
+== Get it
+
 
-http://github.com/defunkt/ambition
 
 $ git clone git://github.com/defunkt/ambition.git
 
+== Resources
+
+ * http://ambition.rubyforge.org/
+ * http://groups.google.com/group/ambition-rb/
+ * http://errtheblog.com/posts/63-full-of-ambition
+ * http://errtheblog.com/posts/82-adapting-ambitiously
+ * http://errtheblog.com/posts/86-sugary-adapters
+ * http://errtheblog.com/posts/64-even-more-ambitious
+
+
+
+== Author
 
 Chris Wanstrath
 chris@ozmm.org

data/ambition.gemspec

@@ -1,11 +1,11 @@
 
-# Gem::Specification for Ambition-0.5.1
+# Gem::Specification for Ambition-0.5.2
 # Originally generated by Echoe
 
 Gem::Specification.new do |s|
   s.name = %q{ambition}
-  s.version = "0.5.1"
-  s.date = %q{2008-02-16}
+  s.version = "0.5.2"
+  s.date = %q{2008-02-29}
   s.summary = %q{Ambition builds yer API calls from plain jane Ruby.}
   s.email = %q{chris@ozmm.org}
   s.homepage = %q{http://errtheblog.com/}
@@ -29,7 +29,7 @@ end
 # require 'rake/testtask'
 # require 'rake/rdoctask'
 # 
-# Version = '0.5.1'
+# Version = '0.5.2'
 # 
 # module Rake::TaskManager
 #   def delete_task(task_class, *args, &block)
@@ -94,7 +94,7 @@ end
 #   rdoc.rdoc_files.add(files)
 #   rdoc.main     = "README" 
 #   rdoc.title    = "ambition"
-#   rdoc.template = File.exists?(t="/Users/chris/ruby/projects/err/rock/template.rb") ? t : "/var/www/rock/template.rb"
+#   # rdoc.template = File.exists?(t="/Users/chris/ruby/projects/err/rock/template.rb") ? t : "/var/www/rock/template.rb"
 #   rdoc.rdoc_dir = 'doc' 
 #   rdoc.options << '--inline-source'
 # end

data/lib/ambition/api.rb

@@ -1,4 +1,8 @@
-module Ambition
+module Ambition #:nodoc:
+  # Module that you will extend from in your adapters in your toplevel file.
+  # 
+  # For example, for ambitious_sphinx in lib/ambition/adapters/ambitious_sphinx.rb, we have:
+  #   ActiveRecord::Base.extend Ambition::API
   module API
     include Enumerable
 
@@ -14,6 +18,7 @@ module Ambition
       context << Processors::Sort.new(context, block)
     end
 
+    # Entries that our context is able to find.
     def entries
       ambition_context.kick
     end
@@ -31,45 +36,60 @@ module Ambition
 
     ##
     # Convenience methods
+    
+    # See Enumerable#detect
     def detect(&block)
       select(&block).first
     end
 
+    # See Array#first
     def first(count = 1)
       sliced = slice(0, count)
       count == 1 ? Array(sliced.kick).first : sliced
     end
 
+    # See Array#each, applied to +entries+
     def each(&block)
       entries.each(&block)
     end
 
+    # See Enumerable#any?
     def any?(&block)
       select(&block).size > 0
     end
 
+    # See Enumerable#all?
     def all?(&block)
       size == select(&block).size
     end
 
+    # See Array#empty?
     def empty?
       size.zero?
     end
 
-    ##
-    # Plumbing
+
+    # Builds a new +Context+.
     def ambition_context
       Context.new(self)
     end
 
+    # Gives you the current ambitious adapter.
     def ambition_adapter
       name   = respond_to?(:name) ? name : self.class.name
       parent = respond_to?(:superclass) ? superclass : self.class.superclass
       @@ambition_adapter[name] || @@ambition_adapter[parent.name]
     end
 
+    
+    # Assign the ambition adapter. Typically, you use this in the toplevel file of your adapter.
+    #
+    # For example, for ambitious_sphinx, in our lib/ambition/adapters/ambitious_sphinx.rb:
+    #
+    #   ActiveRecord::Base.ambition_adapter = Ambition::Adapters::AmbitiousSphinx
     def ambition_adapter=(klass)
       @@ambition_adapter ||= {}
+      # should this be doing the same check for respond_to?(:name) like above?
       @@ambition_adapter[name] = klass
     end
 

data/lib/ambition/context.rb

@@ -1,22 +1,32 @@
-module Ambition
+module Ambition #:nodoc:
+  # This class includes several methods you will likely want to be accessing through your
+  # Query and Translator classes:
+  #
+  # * +clauses+
+  # * +owner+
+  # * +stash+
   class Context
+    undef_method :to_s
     include API
-
-    ##
-    # These are the methods your Query and Translator classes will 
-    # want to access.
-    #
-    #   +owner+   The class everything was called on.  Like `User' 
+    
+    # A hash of arrays, one key per processor.
+    # So, if someone called User.select, your
+    # +clauses+ hash would have a :select key with
+    # an array of translated strings via your Select
+    # class.
+    # 
+    # This is accessible from your Query and Translator classes.
+    attr_reader :clauses
+    
+    # The class everything was called on.  Like `User`
     #
-    #   +clauses+ A hash of arrays, one key per processor.
-    #             So, if someone called User.select, your
-    #             +clauses+ hash would have a :select key with
-    #             an array of translated strings via your Select
-    #             class.
+    # This is accessible from your Query and Translator classes.
+    attr_reader :owner
+    
+    # A place for you to stick stuff.  Available to all Translators and your Query class.
     #
-    #   +stash+   A place for you to stick stuff.  Available to
-    #             all Translators and your Query class.
-    attr_reader :clauses, :owner, :stash
+    # This is accessible from your Query and Translator classes.
+    attr_reader :stash
 
     def initialize(owner)
       @owner   = owner
@@ -24,10 +34,12 @@ module Ambition
       @stash   = {}
     end
 
+    # Gets the ambition_context. From a Ambition::Context, this is actually +self+.
     def ambition_context
       self
     end
 
+    # Adds a clause to this context.
     def <<(clause)
       @clauses[clause.key] ||= []
       @clauses[clause.key] << clause.to_s
@@ -38,22 +50,10 @@ module Ambition
       Processors::Base.translator(self, :Query)
     end
 
-    def to_hash
-      adapter_query.to_hash
-    end
-
-    def to_s
-      adapter_query.to_s
-    end
-
-    def kick
-      adapter_query.kick
-    end
-
-    def size
-      adapter_query.size
+    def method_missing(method, *args, &block)
+      return super unless adapter_query.respond_to? method
+      adapter_query.send(method, *args, &block)
     end
-    alias_method :length, :size
 
     def inspect
       "(Query object: call #to_s or #to_hash to inspect, call an Enumerable (such as #each or #first) to request data)"

data/lib/ambition/core_ext.rb

@@ -1,3 +1,4 @@
+# Object extensions to make metaprogramming a little easier.
 class Object
   def metaclass; (class << self; self end) end
   def meta_eval(&blk) metaclass.instance_eval(&blk) end

data/lib/ambition/enumerable.rb

@@ -1,4 +1,4 @@
-module Ambition
+module Ambition #:nodoc:
   Enumerable = ::Enumerable.dup
   Enumerable.class_eval do
     remove_method :find, :find_all

data/lib/ambition/processors/base.rb

@@ -1,5 +1,5 @@
-module Ambition
-  module Processors
+module Ambition #:nodoc:
+  module Processors #:nodoc:
     class Base
       ##
       # Processing methods
@@ -93,15 +93,26 @@ module Ambition
         eval variable, @block
       end
 
+      # Gives you the current translator. Uses +self.translator+ to look it up,
+      # if it isn't known yet.
       def translator
         @translator ||= self.class.translator(@context)
       end
 
       def self.translator(context, name = nil)
+        # Grok the adapter name
         name   ||= self.name.split('::').last
+        # Get the module for it
         klass    = context.owner.ambition_adapter.const_get(name)
         instance = klass.new
 
+        # Make sure that the instance has everything it will need:
+        #
+        # * context
+        # * owner
+        # * clauses
+        # * stash
+        # * negated?
         unless instance.respond_to? :context
           klass.class_eval do
             attr_accessor :context, :negated

data/lib/ambition/processors/ruby.rb

@@ -1,7 +1,7 @@
 require 'ruby2ruby'
 
-module Ambition
-  module Processors
+module Ambition #:nodoc:
+  module Processors #:nodoc:
     class Ruby < RubyToRuby
       def self.process(node)
         @processor ||= new

data/lib/ambition/processors/select.rb

@@ -1,5 +1,5 @@
-module Ambition
-  module Processors
+module Ambition #:nodoc:
+  module Processors #:nodoc:
     class Select < Base
       def initialize(context, block)
         @context  = context

data/lib/ambition/processors/slice.rb

@@ -1,5 +1,5 @@
-module Ambition
-  module Processors
+module Ambition #:nodoc:
+  module Processors #:nodoc:
     class Slice < Base
       def initialize(context, start, length=nil)
         @context = context

data/lib/ambition/processors/sort.rb

@@ -1,5 +1,5 @@
-module Ambition
-  module Processors
+module Ambition #:nodoc:
+  module Processors #:nodoc:
     class Sort < Base
       def initialize(context, block)
         @context = context

data/lib/ambition/sexp_translator.rb

@@ -1,6 +1,6 @@
 require 'parse_tree'
 
-module Ambition
+module Ambition #:nodoc:
   class SexpTranslator
     @@block_cache = {}
 

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: ambition
 version: !ruby/object:Gem::Version 
-  version: 0.5.1
-date: 2008-02-16 00:00:00 -08:00
+  version: 0.5.2
+date: 2008-02-29 00:00:00 -08:00
 summary: Ambition builds yer API calls from plain jane Ruby.
 require_paths: 
 - lib