ambition 0.5.1 → 0.5.2

Sign up to get free protection for your applications and to get access to all the features.
data/README CHANGED
@@ -1,10 +1,24 @@
1
- Ambition
2
- ========
1
+ = Ambition
2
+
3
+
4
+ == Get it
5
+
3
6
 
4
- http://github.com/defunkt/ambition
5
7
 
6
8
  $ git clone git://github.com/defunkt/ambition.git
7
9
 
10
+ == Resources
11
+
12
+ * http://ambition.rubyforge.org/
13
+ * http://groups.google.com/group/ambition-rb/
14
+ * http://errtheblog.com/posts/63-full-of-ambition
15
+ * http://errtheblog.com/posts/82-adapting-ambitiously
16
+ * http://errtheblog.com/posts/86-sugary-adapters
17
+ * http://errtheblog.com/posts/64-even-more-ambitious
18
+
19
+
20
+
21
+ == Author
8
22
 
9
23
  Chris Wanstrath
10
24
  chris@ozmm.org
@@ -1,11 +1,11 @@
1
1
 
2
- # Gem::Specification for Ambition-0.5.1
2
+ # Gem::Specification for Ambition-0.5.2
3
3
  # Originally generated by Echoe
4
4
 
5
5
  Gem::Specification.new do |s|
6
6
  s.name = %q{ambition}
7
- s.version = "0.5.1"
8
- s.date = %q{2008-02-16}
7
+ s.version = "0.5.2"
8
+ s.date = %q{2008-02-29}
9
9
  s.summary = %q{Ambition builds yer API calls from plain jane Ruby.}
10
10
  s.email = %q{chris@ozmm.org}
11
11
  s.homepage = %q{http://errtheblog.com/}
@@ -29,7 +29,7 @@ end
29
29
  # require 'rake/testtask'
30
30
  # require 'rake/rdoctask'
31
31
  #
32
- # Version = '0.5.1'
32
+ # Version = '0.5.2'
33
33
  #
34
34
  # module Rake::TaskManager
35
35
  # def delete_task(task_class, *args, &block)
@@ -94,7 +94,7 @@ end
94
94
  # rdoc.rdoc_files.add(files)
95
95
  # rdoc.main = "README"
96
96
  # rdoc.title = "ambition"
97
- # rdoc.template = File.exists?(t="/Users/chris/ruby/projects/err/rock/template.rb") ? t : "/var/www/rock/template.rb"
97
+ # # rdoc.template = File.exists?(t="/Users/chris/ruby/projects/err/rock/template.rb") ? t : "/var/www/rock/template.rb"
98
98
  # rdoc.rdoc_dir = 'doc'
99
99
  # rdoc.options << '--inline-source'
100
100
  # end
@@ -1,4 +1,8 @@
1
- module Ambition
1
+ module Ambition #:nodoc:
2
+ # Module that you will extend from in your adapters in your toplevel file.
3
+ #
4
+ # For example, for ambitious_sphinx in lib/ambition/adapters/ambitious_sphinx.rb, we have:
5
+ # ActiveRecord::Base.extend Ambition::API
2
6
  module API
3
7
  include Enumerable
4
8
 
@@ -14,6 +18,7 @@ module Ambition
14
18
  context << Processors::Sort.new(context, block)
15
19
  end
16
20
 
21
+ # Entries that our context is able to find.
17
22
  def entries
18
23
  ambition_context.kick
19
24
  end
@@ -31,45 +36,60 @@ module Ambition
31
36
 
32
37
  ##
33
38
  # Convenience methods
39
+
40
+ # See Enumerable#detect
34
41
  def detect(&block)
35
42
  select(&block).first
36
43
  end
37
44
 
45
+ # See Array#first
38
46
  def first(count = 1)
39
47
  sliced = slice(0, count)
40
48
  count == 1 ? Array(sliced.kick).first : sliced
41
49
  end
42
50
 
51
+ # See Array#each, applied to +entries+
43
52
  def each(&block)
44
53
  entries.each(&block)
45
54
  end
46
55
 
56
+ # See Enumerable#any?
47
57
  def any?(&block)
48
58
  select(&block).size > 0
49
59
  end
50
60
 
61
+ # See Enumerable#all?
51
62
  def all?(&block)
52
63
  size == select(&block).size
53
64
  end
54
65
 
66
+ # See Array#empty?
55
67
  def empty?
56
68
  size.zero?
57
69
  end
58
70
 
59
- ##
60
- # Plumbing
71
+
72
+ # Builds a new +Context+.
61
73
  def ambition_context
62
74
  Context.new(self)
63
75
  end
64
76
 
77
+ # Gives you the current ambitious adapter.
65
78
  def ambition_adapter
66
79
  name = respond_to?(:name) ? name : self.class.name
67
80
  parent = respond_to?(:superclass) ? superclass : self.class.superclass
68
81
  @@ambition_adapter[name] || @@ambition_adapter[parent.name]
69
82
  end
70
83
 
84
+
85
+ # Assign the ambition adapter. Typically, you use this in the toplevel file of your adapter.
86
+ #
87
+ # For example, for ambitious_sphinx, in our lib/ambition/adapters/ambitious_sphinx.rb:
88
+ #
89
+ # ActiveRecord::Base.ambition_adapter = Ambition::Adapters::AmbitiousSphinx
71
90
  def ambition_adapter=(klass)
72
91
  @@ambition_adapter ||= {}
92
+ # should this be doing the same check for respond_to?(:name) like above?
73
93
  @@ambition_adapter[name] = klass
74
94
  end
75
95
 
@@ -1,22 +1,32 @@
1
- module Ambition
1
+ module Ambition #:nodoc:
2
+ # This class includes several methods you will likely want to be accessing through your
3
+ # Query and Translator classes:
4
+ #
5
+ # * +clauses+
6
+ # * +owner+
7
+ # * +stash+
2
8
  class Context
9
+ undef_method :to_s
3
10
  include API
4
-
5
- ##
6
- # These are the methods your Query and Translator classes will
7
- # want to access.
8
- #
9
- # +owner+ The class everything was called on. Like `User'
11
+
12
+ # A hash of arrays, one key per processor.
13
+ # So, if someone called User.select, your
14
+ # +clauses+ hash would have a :select key with
15
+ # an array of translated strings via your Select
16
+ # class.
17
+ #
18
+ # This is accessible from your Query and Translator classes.
19
+ attr_reader :clauses
20
+
21
+ # The class everything was called on. Like `User`
10
22
  #
11
- # +clauses+ A hash of arrays, one key per processor.
12
- # So, if someone called User.select, your
13
- # +clauses+ hash would have a :select key with
14
- # an array of translated strings via your Select
15
- # class.
23
+ # This is accessible from your Query and Translator classes.
24
+ attr_reader :owner
25
+
26
+ # A place for you to stick stuff. Available to all Translators and your Query class.
16
27
  #
17
- # +stash+ A place for you to stick stuff. Available to
18
- # all Translators and your Query class.
19
- attr_reader :clauses, :owner, :stash
28
+ # This is accessible from your Query and Translator classes.
29
+ attr_reader :stash
20
30
 
21
31
  def initialize(owner)
22
32
  @owner = owner
@@ -24,10 +34,12 @@ module Ambition
24
34
  @stash = {}
25
35
  end
26
36
 
37
+ # Gets the ambition_context. From a Ambition::Context, this is actually +self+.
27
38
  def ambition_context
28
39
  self
29
40
  end
30
41
 
42
+ # Adds a clause to this context.
31
43
  def <<(clause)
32
44
  @clauses[clause.key] ||= []
33
45
  @clauses[clause.key] << clause.to_s
@@ -38,22 +50,10 @@ module Ambition
38
50
  Processors::Base.translator(self, :Query)
39
51
  end
40
52
 
41
- def to_hash
42
- adapter_query.to_hash
43
- end
44
-
45
- def to_s
46
- adapter_query.to_s
47
- end
48
-
49
- def kick
50
- adapter_query.kick
51
- end
52
-
53
- def size
54
- adapter_query.size
53
+ def method_missing(method, *args, &block)
54
+ return super unless adapter_query.respond_to? method
55
+ adapter_query.send(method, *args, &block)
55
56
  end
56
- alias_method :length, :size
57
57
 
58
58
  def inspect
59
59
  "(Query object: call #to_s or #to_hash to inspect, call an Enumerable (such as #each or #first) to request data)"
@@ -1,3 +1,4 @@
1
+ # Object extensions to make metaprogramming a little easier.
1
2
  class Object
2
3
  def metaclass; (class << self; self end) end
3
4
  def meta_eval(&blk) metaclass.instance_eval(&blk) end
@@ -1,4 +1,4 @@
1
- module Ambition
1
+ module Ambition #:nodoc:
2
2
  Enumerable = ::Enumerable.dup
3
3
  Enumerable.class_eval do
4
4
  remove_method :find, :find_all
@@ -1,5 +1,5 @@
1
- module Ambition
2
- module Processors
1
+ module Ambition #:nodoc:
2
+ module Processors #:nodoc:
3
3
  class Base
4
4
  ##
5
5
  # Processing methods
@@ -93,15 +93,26 @@ module Ambition
93
93
  eval variable, @block
94
94
  end
95
95
 
96
+ # Gives you the current translator. Uses +self.translator+ to look it up,
97
+ # if it isn't known yet.
96
98
  def translator
97
99
  @translator ||= self.class.translator(@context)
98
100
  end
99
101
 
100
102
  def self.translator(context, name = nil)
103
+ # Grok the adapter name
101
104
  name ||= self.name.split('::').last
105
+ # Get the module for it
102
106
  klass = context.owner.ambition_adapter.const_get(name)
103
107
  instance = klass.new
104
108
 
109
+ # Make sure that the instance has everything it will need:
110
+ #
111
+ # * context
112
+ # * owner
113
+ # * clauses
114
+ # * stash
115
+ # * negated?
105
116
  unless instance.respond_to? :context
106
117
  klass.class_eval do
107
118
  attr_accessor :context, :negated
@@ -1,7 +1,7 @@
1
1
  require 'ruby2ruby'
2
2
 
3
- module Ambition
4
- module Processors
3
+ module Ambition #:nodoc:
4
+ module Processors #:nodoc:
5
5
  class Ruby < RubyToRuby
6
6
  def self.process(node)
7
7
  @processor ||= new
@@ -1,5 +1,5 @@
1
- module Ambition
2
- module Processors
1
+ module Ambition #:nodoc:
2
+ module Processors #:nodoc:
3
3
  class Select < Base
4
4
  def initialize(context, block)
5
5
  @context = context
@@ -1,5 +1,5 @@
1
- module Ambition
2
- module Processors
1
+ module Ambition #:nodoc:
2
+ module Processors #:nodoc:
3
3
  class Slice < Base
4
4
  def initialize(context, start, length=nil)
5
5
  @context = context
@@ -1,5 +1,5 @@
1
- module Ambition
2
- module Processors
1
+ module Ambition #:nodoc:
2
+ module Processors #:nodoc:
3
3
  class Sort < Base
4
4
  def initialize(context, block)
5
5
  @context = context
@@ -1,6 +1,6 @@
1
1
  require 'parse_tree'
2
2
 
3
- module Ambition
3
+ module Ambition #:nodoc:
4
4
  class SexpTranslator
5
5
  @@block_cache = {}
6
6
 
metadata CHANGED
@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
3
3
  specification_version: 1
4
4
  name: ambition
5
5
  version: !ruby/object:Gem::Version
6
- version: 0.5.1
7
- date: 2008-02-16 00:00:00 -08:00
6
+ version: 0.5.2
7
+ date: 2008-02-29 00:00:00 -08:00
8
8
  summary: Ambition builds yer API calls from plain jane Ruby.
9
9
  require_paths:
10
10
  - lib