LICENSE adapters/ambitious_activerecord/LICENSE adapters/ambitious_activerecord/README app_generators/ambition_adapter/templates/LICENSE @@ -23,6 +23,7 @@ lib/ambition/processors/select.rb lib/ambition/processors/slice.rb lib/ambition/processors/sort.rb lib/ambition.rb +LICENSE Manifest README test/adapters/exemplar/association_test.rb Manifest @@ -42,7 +42,7 @@ class AmbitionAdapterGenerator < RubiGen::Base ## # Normal files - files = %w( README Rakefile ) + files = %w( LICENSE README Rakefile ) files.each do |file| m.template file, file end app_generators/ambition_adapter/ambition_adapter_generator.rb @@ -35,7 +35,7 @@ task :build do live_file = "live/#{file_name}" unless uptodate?(live_file, file) && uptodate?(live_file, "src/layout.textile") - File.new(live_file, 'w') { |f| f.puts(compile(file)); f.flush } + 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 site/Rakefile @@ -1 +1,234 @@ -Hi. +h2. An Ambitious ActiveRecord Adapter + +I could tell you all about how awesome the internals are, or +how fun it was to write, or how it'll make you rich and famous, +but instead I'm just going to show you some examples. + +h2. Get It + +@$ sudo gem install ambitious-activerecord@ + +This will suck in the adapter and its dependencies (ActiveRecord & Ambition). +It's fully usable outside of Rails (I use it in a Camping app or two), as long +as you're riding ActiveRecord. + +To use with Rails, after installing the gem: + +<pre> +$ cd vendor/plugins +$ gem unpack ambitious-activerecord +</pre> + +h2. Examples + +Basically, you write your SQL in Ruby. No, not in Ruby. As Ruby. + +<ruby> +User.select { |u| u.city == 'San Francisco' }.each do |user| + puts user.name +end +</ruby> + +And that's it. + +The key is that queries aren't actually run until the data they represent is +requested. Usually this is done with what I call a kicker method. You can call them +that, too. + +Kicker methods are guys like @detect@, @each@, @each_with_index@, @map@, @entries@, +@to_a@, and @first@ (with no argument). Methods like @select@, @sort_by@, and @first@ +(with an argument) are not kicker methods and return a @Context@ object without running any SQL. + +Our @Context@ object has two useful methods: @to_s@ and @to_hash@. With these, +we can check out what exactly we're building. Not everyone has @to_s@, +though. Mostly ignore these methods and treat everything like you normally +would. + +See, @to_s@: + +<ruby> +>> User.select { |m| m.name == 'jon' }.to_s +=> "SELECT * FROM users WHERE users.name = 'jon'" +</ruby> + +See, @to_hash@: + +<ruby> +>> User.select { |m| m.name == 'jon' }.to_hash +=> { :conditions => "users.name = 'jon'" } +</ruby> + +h2. Equality - select { |u| u.field == 'bob' } + +<ruby> +User.select { |m| m.name == 'jon' } +"SELECT * FROM users WHERE users.name = 'jon'" + +User.select { |m| m.created_at > 2.days.ago } +"SELECT * FROM users WHERE users.created_at > '2007-09-26 20:37:47'" + +User.select { |m| m.name == 'jon' } +"SELECT * FROM users WHERE users.name = 'jon'" + +User.select { |m| m.name != 'jon' } +"SELECT * FROM users WHERE users.name <> 'jon'" + +User.select { |m| m.name == 'jon' && m.age == 21 } +"SELECT * FROM users WHERE (users.name = 'jon' AND users.age = 21)" + +User.select { |m| m.name == 'jon' || m.age == 21 } +"SELECT * FROM users WHERE (users.name = 'jon' OR users.age = 21)" + +User.select { |m| m.name == 'jon' || m.age == 21 && m.password == 'pass' } +"SELECT * FROM users WHERE + (users.name = 'jon' OR (users.age = 21 AND users.password = 'pass'))" + +User.select { |m| (m.name == 'jon' || m.name == 'rick') && m.age == 21 } +"SELECT * FROM users WHERE + ((users.name = 'jon' OR users.name = 'rick') AND users.age = 21)" +</ruby> + +h2. Associations - select { |u| u.field == 'bob' && u.association.field == 'bob@bob.com' } + +The @to_s@ method doesn't work on associations yet, but that's okay: they can +still query through ActiveRecord just fine. + +<ruby> +User.select do |u| + u.email == 'chris@ozmm.org' && u.profile.name == 'chris wanstrath' +end.map(&:title) + +"SELECT users.id AS t0_r0, ... FROM users + LEFT OUTER JOIN profiles ON profiles.user_id = users.id + WHERE ((users.email = 'chris@ozmm.org' AND profiles.name = 'chris wanstrath'))" +</ruby> + +h2. Comparisons - select { |u| u.age > 21 } + +<ruby> +User.select { |m| m.age > 21 } +"SELECT * FROM users WHERE users.age > 21" + +User.select { |m| m.age < 21 }.to_s +"SELECT * FROM users WHERE users.age < 21" + +User.select { |m| [1, 2, 3, 4].include? m.id } +"SELECT * FROM users WHERE users.id IN (1, 2, 3, 4)" +</ruby> + +h2. LIKE and REGEXP (RLIKE) - select { |m| m.name =~ 'chris' } + +<ruby> +User.select { |m| m.name =~ 'chris' } +"SELECT * FROM users WHERE users.name LIKE 'chris'" + +User.select { |m| m.name =~ 'chri%' } +"SELECT * FROM users WHERE users.name LIKE 'chri%'" + +User.select { |m| m.name !~ 'chris' } +"SELECT * FROM users WHERE users.name NOT LIKE 'chris'" + +User.select { |m| !(m.name =~ 'chris') } +"SELECT * FROM users WHERE users.name NOT LIKE 'chris'" + +User.select { |m| m.name =~ /chris/ } +"SELECT * FROM users WHERE users.name REGEXP 'chris'" +</ruby> + +h2. #detect + +<ruby> +User.detect { |m| m.name == 'chris' } +"SELECT * FROM users WHERE users.name = 'chris' LIMIT 1" +</ruby> + +h2. LIMITs - first, first(x), [offset, limit], [range], slice + +<ruby> +User.select { |m| m.name == 'jon' }.first +"SELECT * FROM users WHERE users.name = 'jon' LIMIT 1" + +User.select { |m| m.name == 'jon' }.first(5) +"SELECT * FROM users WHERE users.name = 'jon' LIMIT 5" + +User.select { |m| m.name == 'jon' }[10, 20] +"SELECT * FROM users WHERE users.name = 'jon' LIMIT 10, 20" + +User.select { |m| m.name == 'jon' }[10..20] +"SELECT * FROM users WHERE users.name = 'jon' LIMIT 10, 10" +</ruby> + +h2. ORDER - sort_by { |u| u.field } + +<ruby> +User.select { |m| m.name == 'jon' }.sort_by { |m| m.name } +"SELECT * FROM users WHERE users.name = 'jon' ORDER BY users.name" + +User.select { |m| m.name == 'jon' }.sort_by { |m| [ m.name, m.age ] } +"SELECT * FROM users WHERE users.name = 'jon' ORDER BY users.name, users.age" + +User.select { |m| m.name == 'jon' }.sort_by { |m| [ m.name, -m.age ] } +"SELECT * FROM users WHERE users.name = 'jon' + ORDER BY users.name, users.age DESC" + +User.select { |m| m.name == 'jon' }.sort_by { |m| [ -m.name, -m.age ] } +"SELECT * FROM users WHERE users.name = 'jon' + ORDER BY users.name DESC, users.age DESC" + +User.select { |m| m.name == 'jon' }.sort_by { |m| -m.age } +"SELECT * FROM users WHERE users.name = 'jon' ORDER BY users.age DESC" + +User.select { |m| m.name == 'jon' }.sort_by { |m| -m.profiles.title } +"SELECT users.id AS t0_r0, ... FROM users + LEFT OUTER JOIN profiles ON profiles.user_id = users.id + WHERE (users.name = 'jon') ORDER BY profiles.title DESC" + +User.select { |m| m.name == 'jon' }.sort_by { rand } +"SELECT * FROM users WHERE users.name = 'jon' ORDER BY RAND()" +</ruby> + +h2. COUNT - select { |u| u.name == 'jon' }.size + +<ruby> +User.select { |m| m.name == 'jon' }.size +"SELECT count(*) AS count_all FROM users WHERE (users.name = 'jon')" + +>> User.select { |m| m.name == 'jon' }.size +=> 21 +</ruby> + +h2. Other Enumerables + +These methods perform COUNT() operations rather than loading your array into memory. They're all +kickers. + +<ruby> +User.any? { |m| m.name == 'jon' } +User.all? { |m| m.name == 'jon' } +User.select { |m| m.name == 'jon' }.empty? +</ruby> + +h2. More Sugar + +The @downcase@ and @upcase@ methods will map to LOWER() and UPPER(), respectively. + +<ruby> +>> User.select { |m| m.name.downcase =~ 'jon%' }.to_s +=> "SELECT * FROM users WHERE LOWER(users.name) LIKE 'jon%'" +</ruby> + +h2. Quoting + +Columns and values will be quoted using ActiveRecord's quote_column_name and quote methods, if +possible. + +h2. SELECT * FROM bugs + +Found a bug? Sweet. Add it at "the Lighthouse":http://err.lighthouseapp.com/projects/466-plugins/tickets/new. + +More information on Ambition: + + * "http://ambition.rubyforge.org":http://ambition.rubyforge.org + * "http://groups.google.com/group/ambition-rb/":http://groups.google.com/group/ambition-rb/ + +- Chris Wanstrath [ chris@ozmm.org ] \ No newline at end of file site/src/adapters/activerecord.textile @@ -113,9 +113,7 @@ pre { .ruby .brackets { color: #777; } -.ruby .symbol { - color: #00fb79; -} + .ruby .regex { color: #37ffff; } site/src/static/hubris.css 189244070fd4dca0fa36a0e6c8745814ccd603e8 Chris Wanstrath chris@ozmm.org http://github.com/defunkt/ambition/commit/42b276419222e6fa372da1f6fc50ec9a6f348f01 42b276419222e6fa372da1f6fc50ec9a6f348f01 2007-11-28T19:01:44-08:00 2007-11-28T19:01:44-08:00 license and readme stuff fc0d8a69cde541a1620f8ef965a9c1e13034305c Chris Wanstrath chris@ozmm.org