Ruby's Ambition

Ambition::API

Your data store target (e.g. ActiveRecord) is extended or injected with this module.

Processors

These methods do not fire off a query and can be chained. They return a Context object which can be inspected or kicked.

select
sort_by
slice
first(length)

Kickers

Kickers cause a query to execute. All method calls on a context are accumulated until kicked, at which point they’re turned into a query and run.

entries
to_a
detect
first (no arguments)
size

Custom Enumerables

These Enumerable methods are written special for Ambition. Other Enumerable methods, like each_with_index, should work out of the box as they mostly wrap each.

each
any?
all?
empty?

Translators and Query

Methods available to translator and Query instance methods:

owner – constant, adapter target
clauses – hash, keyed by translator name
stash – hash, arbitrary

Ambition::Adapters::YourAdapter::Select

All translators are instantiated and have access to owner and stash. They should not touch clauses directly.

call – passed a symbol. e.g. call(:name)
chained_call – passed an array of symbols. e.g. call(:name, :downcase)
include? – passed the array it’s called on and the argument.

The following methods are passed the left and right side of the expression they represent.

both – &&
either – ||
not_equal – !=
not_regexp – !~
==
=~
<
<=
>
>=

Ambition::Adapters::YourAdapter::Slice

All translators are instantiated and have access to owner and stash. They should not touch clauses directly.

The Slice translator has only one method: slice(start, length)

Some examples:

first(5) becomes slice(0, 5)
first becomes slice(0, 1)
User[10, 20] becomes slice(10, 20)
User[10..20] becomes slice(10, 10)

Ambition::Adapters::YourAdapter::Sort

All translators are instantiated and have access to owner and stash. They should not touch clauses directly.

sort_by – passed a symbol
reverse_sort_by – passed a symbol
chained_sort_by – passed an array of symbols
chained_reverse_sort_by – passed an array of symbols
to_proc – passed a symbol
rand

Ambition::Adapters::YourAdapter::Query

The Query is instantiated and has access to owner, clauses, and stash. It should use the information these methods provide to build its domain specific query.

When any of the following methods are called on a Context they are forwarded to the Query instance.

kick – the API’s kickers call this
size
to_hash
to_s