benhoskings-ambition 0.5.4.3 → 0.5.4.4

data/.gitignore

@@ -0,0 +1,2 @@
+pkg
+live

data/Rakefile

@@ -0,0 +1,16 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "benhoskings-ambition"
+    gemspec.summary = "Ambition builds yer API calls from plain jane Ruby."
+    gemspec.description = "Ambition builds yer API calls from plain jane Ruby."
+    gemspec.email = "chris@ozmm.org"
+    gemspec.homepage = "http://errtheblog.com/"
+    gemspec.authors = ['Chris Wanstrath', 'Ben Hoskings']
+    gemspec.add_dependency 'ParseTree', '=2.1.1'
+    gemspec.add_dependency 'ruby2ruby', '=1.1.8'
+    gemspec.add_dependency 'rubigen', '>=1.1.1'
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/ambition.gemspec

@@ -1,120 +1,121 @@
-
-# Gem::Specification for Ambition-0.5.4
-# Originally generated by Echoe
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{ambition}
-  s.version = "0.5.4.3"
-
-  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.version = "0.5.4.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Chris Wanstrath", "Ben Hoskings"]
-  s.date = %q{2008-04-26}
+  s.date = %q{2009-10-22}
   s.default_executable = %q{ambition_adapter}
   s.description = %q{Ambition builds yer API calls from plain jane Ruby.}
-  s.email = %q{chris@ozmm.org, ben@hoskings.net}
+  s.email = %q{chris@ozmm.org}
   s.executables = ["ambition_adapter"]
-  s.extra_rdoc_files = ["bin/ambition_adapter", "lib/ambition/api.rb", "lib/ambition/context.rb", "lib/ambition/core_ext.rb", "lib/ambition/enumerable.rb", "lib/ambition/processors/base.rb", "lib/ambition/processors/ruby.rb", "lib/ambition/processors/select.rb", "lib/ambition/processors/slice.rb", "lib/ambition/processors/sort.rb", "lib/ambition/sexp_translator.rb", "lib/ambition.rb", "LICENSE", "README"]
-  s.files = ["app_generators/ambition_adapter/ambition_adapter_generator.rb", "app_generators/ambition_adapter/templates/lib/adapter/base.rb.erb", "app_generators/ambition_adapter/templates/lib/adapter/query.rb.erb", "app_generators/ambition_adapter/templates/lib/adapter/select.rb.erb", "app_generators/ambition_adapter/templates/lib/adapter/slice.rb.erb", "app_generators/ambition_adapter/templates/lib/adapter/sort.rb.erb", "app_generators/ambition_adapter/templates/lib/init.rb.erb", "app_generators/ambition_adapter/templates/LICENSE", "app_generators/ambition_adapter/templates/Rakefile", "app_generators/ambition_adapter/templates/README", "app_generators/ambition_adapter/templates/test/helper.rb.erb", "app_generators/ambition_adapter/templates/test/select_test.rb.erb", "app_generators/ambition_adapter/templates/test/slice_test.rb.erb", "app_generators/ambition_adapter/templates/test/sort_test.rb.erb", "app_generators/ambition_adapter/USAGE", "bin/ambition_adapter", "lib/ambition/api.rb", "lib/ambition/context.rb", "lib/ambition/core_ext.rb", "lib/ambition/enumerable.rb", "lib/ambition/processors/base.rb", "lib/ambition/processors/ruby.rb", "lib/ambition/processors/select.rb", "lib/ambition/processors/slice.rb", "lib/ambition/processors/sort.rb", "lib/ambition/sexp_translator.rb", "lib/ambition.rb", "LICENSE", "Manifest", "README", "test/adapters/exemplar/association_test.rb", "test/adapters/exemplar/count_test.rb", "test/adapters/exemplar/detect_test.rb", "test/adapters/exemplar/enumerable_test.rb", "test/adapters/exemplar/helper.rb", "test/adapters/exemplar/index_operator.rb", "test/adapters/exemplar/reject_test.rb", "test/adapters/exemplar/select_test.rb", "test/adapters/exemplar/slice_test.rb", "test/adapters/exemplar/sort_test.rb", "test/debug", "test/helper.rb", "ambition.gemspec"]
-  s.has_rdoc = true
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "Manifest",
+     "README",
+     "Rakefile",
+     "ambition.gemspec",
+     "app_generators/ambition_adapter/USAGE",
+     "app_generators/ambition_adapter/ambition_adapter_generator.rb",
+     "app_generators/ambition_adapter/templates/LICENSE",
+     "app_generators/ambition_adapter/templates/README",
+     "app_generators/ambition_adapter/templates/Rakefile",
+     "app_generators/ambition_adapter/templates/lib/adapter/base.rb.erb",
+     "app_generators/ambition_adapter/templates/lib/adapter/query.rb.erb",
+     "app_generators/ambition_adapter/templates/lib/adapter/select.rb.erb",
+     "app_generators/ambition_adapter/templates/lib/adapter/slice.rb.erb",
+     "app_generators/ambition_adapter/templates/lib/adapter/sort.rb.erb",
+     "app_generators/ambition_adapter/templates/lib/init.rb.erb",
+     "app_generators/ambition_adapter/templates/test/helper.rb.erb",
+     "app_generators/ambition_adapter/templates/test/select_test.rb.erb",
+     "app_generators/ambition_adapter/templates/test/slice_test.rb.erb",
+     "app_generators/ambition_adapter/templates/test/sort_test.rb.erb",
+     "bin/ambition_adapter",
+     "deps.rip",
+     "lib/ambition.rb",
+     "lib/ambition/api.rb",
+     "lib/ambition/context.rb",
+     "lib/ambition/core_ext.rb",
+     "lib/ambition/enumerable.rb",
+     "lib/ambition/processors/base.rb",
+     "lib/ambition/processors/ruby.rb",
+     "lib/ambition/processors/select.rb",
+     "lib/ambition/processors/slice.rb",
+     "lib/ambition/processors/sort.rb",
+     "lib/ambition/sexp_translator.rb",
+     "site/Rakefile",
+     "site/src/_adapters.textile",
+     "site/src/adapters.textile",
+     "site/src/adapters/activerecord.textile",
+     "site/src/api.textile",
+     "site/src/index.textile",
+     "site/src/layout.textile",
+     "site/src/static/bg.png",
+     "site/src/static/code_highlighter.js",
+     "site/src/static/css.js",
+     "site/src/static/html.js",
+     "site/src/static/hubris.css",
+     "site/src/static/javascript.js",
+     "site/src/static/ruby.js",
+     "test/adapters/exemplar/association_test.rb",
+     "test/adapters/exemplar/count_test.rb",
+     "test/adapters/exemplar/detect_test.rb",
+     "test/adapters/exemplar/enumerable_test.rb",
+     "test/adapters/exemplar/helper.rb",
+     "test/adapters/exemplar/index_operator.rb",
+     "test/adapters/exemplar/reject_test.rb",
+     "test/adapters/exemplar/select_test.rb",
+     "test/adapters/exemplar/slice_test.rb",
+     "test/adapters/exemplar/sort_test.rb",
+     "test/debug",
+     "test/helper.rb"
+  ]
   s.homepage = %q{http://errtheblog.com/}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ambition", "--main", "README"]
+  s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.required_ruby_version = Gem::Requirement.new(">= 1.8.6")
-  s.rubyforge_project = %q{err}
-  s.rubygems_version = %q{1.3.1}
+  s.rubygems_version = %q{1.3.5}
   s.summary = %q{Ambition builds yer API calls from plain jane Ruby.}
+  s.test_files = [
+    "test/adapters/exemplar/association_test.rb",
+     "test/adapters/exemplar/count_test.rb",
+     "test/adapters/exemplar/detect_test.rb",
+     "test/adapters/exemplar/enumerable_test.rb",
+     "test/adapters/exemplar/helper.rb",
+     "test/adapters/exemplar/index_operator.rb",
+     "test/adapters/exemplar/reject_test.rb",
+     "test/adapters/exemplar/select_test.rb",
+     "test/adapters/exemplar/slice_test.rb",
+     "test/adapters/exemplar/sort_test.rb",
+     "test/helper.rb"
+  ]
 
-  s.add_dependency(%q<ParseTree>, ["= 2.1.1"])
-  s.add_dependency(%q<ruby2ruby>, ["= 1.1.8"])
-  s.add_dependency(%q<rubigen>, [">= 1.1.1"])
-end
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
 
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ParseTree>, ["= 2.1.1"])
+      s.add_runtime_dependency(%q<ruby2ruby>, ["= 1.1.8"])
+      s.add_runtime_dependency(%q<rubigen>, [">= 1.1.1"])
+    else
+      s.add_dependency(%q<ParseTree>, ["= 2.1.1"])
+      s.add_dependency(%q<ruby2ruby>, ["= 1.1.8"])
+      s.add_dependency(%q<rubigen>, [">= 1.1.1"])
+    end
+  else
+    s.add_dependency(%q<ParseTree>, ["= 2.1.1"])
+    s.add_dependency(%q<ruby2ruby>, ["= 1.1.8"])
+    s.add_dependency(%q<rubigen>, [">= 1.1.1"])
+  end
+end
 
-# # Original Rakefile source (requires the Echoe gem):
-# 
-# require 'rake'
-# require 'rake/testtask'
-# require 'rake/rdoctask'
-# 
-# Version = '0.5.4'
-# 
-# module Rake::TaskManager
-#   def delete_task(task_class, *args, &block)
-#     task_name, deps = resolve_args(args)
-#     @tasks.delete(task_class.scope_name(@scope, task_name).to_s)
-#   end
-# end
-# class Rake::Task
-#   def self.delete_task(args, &block) Rake.application.delete_task(self, args, &block) end
-# end
-# def delete_task(args, &block) Rake::Task.delete_task(args, &block) end
-# 
-# begin
-#   require 'rubygems'
-#   gem 'echoe', '>=2.7'
-#   ENV['RUBY_FLAGS'] = ""
-#   require 'echoe'
-# 
-#   Echoe.new('ambition', Version) do |p|
-#     p.project        = 'err'
-#     p.summary        = "Ambition builds yer API calls from plain jane Ruby."
-#     p.description    = "Ambition builds yer API calls from plain jane Ruby."
-#     p.url            = "http://errtheblog.com/"
-#     p.author         = 'Chris Wanstrath'
-#     p.email          = "chris@ozmm.org"
-#     p.ruby_version   = '>= 1.8.6'
-#     p.ignore_pattern = /^(\.git|site|adapters).+/
-#     p.test_pattern   = 'test/*_test.rb'
-#     p.dependencies  << 'ParseTree =2.1.1'
-#     p.dependencies  << 'ruby2ruby =1.1.8'
-#     p.dependencies  << 'rubigen =1.1.1'
-#   end
-# 
-# rescue LoadError 
-#   puts "Not doing any of the Echoe gemmy stuff, because you don't have the specified gem versions"
-# end
-# 
-# delete_task :test
-# delete_task :install_gem
-# 
-# Rake::TestTask.new('test') do |t|
-#   t.pattern = 'test/*_test.rb'
-# end
-# 
-# Rake::TestTask.new('test:adapters') do |t|
-#   t.pattern = 'adapters/*/test/*_test.rb'
-# end
-# 
-# Dir['adapters/*'].each do |adapter|
-#   adapter = adapter.split('/').last
-#   Rake::TestTask.new("test:adapters:#{adapter.sub('ambitious_','')}") do |t|
-#     t.pattern = "adapters/#{adapter}/test/*_test.rb"
-#   end
-# end
-# 
-# desc 'Default: run unit tests.'
-# task :default => :test
-# 
-# desc 'Generate RDoc documentation'
-# Rake::RDocTask.new(:rdoc) do |rdoc|
-#   files = ['README', 'LICENSE', 'lib/**/*.rb']
-#   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.rdoc_dir = 'doc' 
-#   rdoc.options << '--inline-source'
-# end
-# 
-# desc 'Generate coverage reports'
-# task :rcov do
-#   `rcov -e gems test/*_test.rb`
-#   puts 'Generated coverage reports.'
-# end
-# 
-# desc 'Install as a gem'
-# task :install_gem do
-#   puts `rake manifest package && gem install pkg/ambition-#{Version}.gem`
-# end

data/deps.rip

@@ -0,0 +1,3 @@
+git://github.com/drnic/rubigen.git REL-1.3.0
+git://github.com/seattlerb/ruby2ruby.git e3cf57559 # 1.1.8
+git://github.com/seattlerb/parsetree.git 480ede9d9 # 2.1.1

data/lib/ambition/processors/base.rb

@@ -109,7 +109,7 @@ module Ambition #:nodoc:
         # * clauses
         # * stash
         # * negated?
-        unless instance.respond_to? :context
+        unless instance.respond_to? :context=
           klass.class_eval do
             attr_accessor :context, :negated
             def owner;    @context.owner   end

data/site/Rakefile

@@ -0,0 +1,61 @@
+require 'rubygems'
+require 'redcloth'
+require 'rake'
+require 'rake/contrib/sshpublisher'
+
+    StaticFiles = %w( png gif jpeg jpg css js )
+LiveDirectories = %w( adapters textile static )
+
+task :default => [ :clean, :build ]
+
+desc "Clean generated files"
+task :clean do
+  FileUtils.rm_rf 'live'
+end
+
+def compile(file)
+  layout = File.read('src/layout.textile')
+  layout.sub('%CONTENT%', compile_without_layout(file)).gsub('%PAGE%', File.basename(file).split('.').first)
+end
+
+def compile_without_layout(file)
+  textile = File.read(file).
+    gsub(/%INCLUDE (.+)%/) { |match| File.read("src/#{$1}") }.
+    gsub('<ruby>', '<pre class="ruby">').gsub('</ruby>', '</pre>')
+  RedCloth.new(textile).to_html
+end
+
+desc "Build live HTML files"
+task :build do
+  LiveDirectories.each { |dir| FileUtils.mkdir_p "live/#{dir}" }
+  Dir['src/**/*.textile'].each do |file|
+    next if File.basename(file) == 'layout.textile'
+
+    file_name = file.sub('src/', '').sub('.textile', '.html')
+    live_file = "live/#{file_name}"
+
+    unless uptodate?(live_file, file) && uptodate?(live_file, "src/layout.textile")
+      File.open(live_file, 'w') { |f| f.puts(compile(file)); f.flush }
+      puts "created #{live_file}"
+      cp file, 'live/textile/' + file.split('/').last.sub('.textile', '.txt')
+    end
+  end
+
+  static_files = "{#{StaticFiles.join(',')}}"
+  Dir["src/**/*.#{static_files}"].each do |file|
+    file = file.sub('src/','')
+    src, live = "src/#{file}", "live/#{file}"
+    unless uptodate? live, src
+      cp src, live 
+      puts "copied #{file}"
+    end
+  end
+end
+
+desc "Publish the documentation"
+task :publish => [ :build ] do
+Rake::SshDirPublisher.new(
+  "defunkt@rubyforge.org",
+  "/var/www/gforge-projects/ambition/",
+  "live" ).upload
+end

data/site/src/_adapters.textile

@@ -0,0 +1,23 @@
+Adapters are gems named @ambitious-something@, where _something_ corresponds to the data
+store they are adapting.  They can be required in code via @ambition/adapters/something@.
+
+To install and test the ActiveRecord adapter:
+
+<pre>
+$ gem install ambitious-activerecord
+$ irb 
+>> require 'rubygems'
+>> require 'ambition/adapters/active_record'
+</pre>
+
+Adapters typically inject themselves into their target automatically, so that should be
+all you need.
+
+There are a few adapters in development or released currently:
+
+  * "ActiveRecord":adapters/activerecord.html
+  * ActiveLDAP
+  * Facebook
+  * XPath
+  * CouchDB
+  * DataMapper

data/site/src/adapters.textile

@@ -0,0 +1,163 @@
+h2. The Adapters
+
+%INCLUDE _adapters.textile%
+
+If you're interested in writing your own adapter, read on.
+
+h2. The Anatomy of an Adapter
+
+Ambition adapters consist of two parts: *Translators* and the *Query*.  Translators
+are used to translate plane jane Ruby into strings while the Query is used to build
+and execute a query from those strings.
+
+The three translators are @Select@, @Slice@, and @Sort@.  Their names correspond to the
+API method they represent. Each translator consists of methods which convert passed 
+arguments into a string.
+
+Here's how the ActiveRecord adapter maps translator classes to SQL clauses:
+
+  * @Select@ => @WHERE@
+  * @Slice@ => @LIMIT@ and @OFFSET@
+  * @Sort@ => @ORDER BY@
+
+Your translators and the Query have three special methods available at all times:
+
+  * @owner@
+  * @clauses@
+  * @stash@
+
+@owner@ is the class from which the request was generated.
+
+<ruby>
+User.select { |u| u.name == 'Pork' }
+# => owner == User
+</ruby>
+
+@clauses@ is the hash of translated string arrays, keyed by processors.
+
+<ruby>
+User.select { |u| u.name == 'Pork' }
+# => clauses ==  { :select => [ "users.name = 'Pork'" ] }
+</ruby>
+
+@stash@ is your personal private stash.  A hash you can use for
+keeping stuff around.  Translators are free to set things which 
+can later be picked up by the Query class.
+
+For instance, the @ActiveRecord@ adapter's @Select@ translator adds to the
+@stash[:include]@ array whenever it thinks it needs to do a join.  The
+Query class picks this up and adds it to the hash it feeds
+@find(:all)@.  
+
+<ruby>
+User.select { |u| u.profile.name == 'Pork' }
+# => stash == { :include => [ :profile ] }
+</ruby>
+
+@stash@ is basically a way for your translators to talk to each other and, 
+more importantly, to the Query.
+
+The Query is what kicks off the actual data store query, after all the translators have done
+their business.  Its @clauses@ and @stash@ hashes are as full as they will ever be.  
+
+The kicking is done by one of two methods:
+
+  * @kick@ 
+  * @count@
+  
+While two other methods are generally expected to turn the @clauses@ hash into something
+semantically valid:
+
+  * @to_s@
+  * @to_hash@
+
+So, for instance, @Query#kick@ may look like this:
+
+<ruby>
+def kick
+  owner.find(:all, to_hash)
+end
+</ruby>
+
+A straightforward translator/query API reference can be found on the "api":api.html page.
+
+The easiest way to understand translators is to check out the source of the existing adapters
+or by using the adapter generator.
+
+h2. The Adapter Generator
+
+Ambition ships with an @ambition_adapter@ script which can generate an adapter skeleton.  Built 
+using Dr Nic's "Rubigen":http://rubigen.rubyforge.org/, it spits out all the files, tests, and 
+Rakefiles your adapter needs.
+
+Run it:
+
+<pre>
+$ ambition_adapter flickr
+      create  
+      create  lib/ambition/adapters/flickr
+      create  test
+      create  lib/ambition/adapters/flickr/base.rb
+      create  lib/ambition/adapters/flickr/query.rb
+      create  lib/ambition/adapters/flickr/select.rb
+      create  lib/ambition/adapters/flickr/slice.rb
+      create  lib/ambition/adapters/flickr/sort.rb
+      create  lib/ambition/adapters/flickr.rb
+      create  test/helper.rb
+      create  test/select_test.rb
+      create  test/slice_test.rb
+      create  test/sort_test.rb
+      create  README
+      create  Rakefile
+</pre>
+
+Presto, you've got a ready and willing adapter skeleton in place now.  Check out the comments
+and you're on your way.
+
+h2. The Flow: Ambition + Adapters
+
+Let us examine the flow of a typical call, using the @ActiveRecord@ adapter for reference.
+
+The call:
+
+<ruby>
+User.select { |u| u.name == 'Chris' && u.age == 22 }.to_s
+</ruby>
+
+The first few steps:
+
+  * @Ambition::API#select@ is called.
+  * An @Ambition::Context@ is created.
+  * An @Ambition::Processors::Select@ is created and added to the context.
+  * The context calls @to_s@ on the new @Select@ processor
+  * The block passed to @select@ is processed.
+  
+This processing is the real meat.  Ambition will instantiate your @Select@ translator and 
+pass values to it, saving the return value of these method calls.
+
+  * @Ambition::Adapters::ActiveRecord::Select@ is instantiated.
+  * The translator's @call@ method is passed @:name@, returning @"users.name"@
+  * The translator's @==@ method is passed @"users.name"@ and @"Chris"@, returning @"users.name = 'Chris'"@
+  * @call@ is passed @:age@, returning @"users.age"@
+  * @==@ is passed @"users.age"@ and @22@, returning @"users.age = 22"@
+  * The translator's @both@ method is passed @"users.name = 'Chris'"@ and @"users.age = 22"@, 
+returning @"(users.name = 'Chris' AND users.age = 22)"@
+
+At this point we leave adapter-land.  The final string is stored in the @clauses@ hash 
+(available to your @Query@) by the context.  The @clauses@ hash is keyed by the translator 
+name -- in this case, @:select@.
+  
+  * The context is returned by @Ambition::API#select@.
+  * @to_s@ is called on the context
+  * The context forwards this @to_s@ call to an instance of the adapter's @Query@ class
+  * The ActiveRecord adapter's @to_s@ calls @to_hash@
+  * @to_hash@ uses the @clauses@ hash to build an AR hash
+  * @to_s@ then uses the hash's members to build a SQL string
+
+The final string is then returned:
+
+<ruby>
+"SELECT * FROM users WHERE (users.name = 'Chris' AND users.age = 22)"
+</ruby>
+
+And that's all there is to it.  Except, of course, for the "api":api.html page.