Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 281 lines (186 sloc) 7.177 kb
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
1 Pacecar
2 =======
3
ecaddd3 @mjankowski Add travis build indicator image
mjankowski authored
4 [![Build Status](https://secure.travis-ci.org/thoughtbot/pacecar.png?branch=master)](http://travis-ci.org/thoughtbot/pacecar)
5
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
6 Pacecar adds scope methods and other common functionality to ActiveRecord classes via database column introspection.
7
8 Pacecar automatically includes the Pacecar::Helpers module into all ActiveRecord::Base classes.
9
10 To get all Pacecar functionality, you need to "include Pacecar" in your class.
11
12 class User < ActiveRecord::Base
13 include Pacecar
14 end
15
16 To get some subset (for example, only the state functionality), you can do something like "include Pacecar::State" to get only the module(s) you want.
17
18 class Post < ActiveRecord::Base
19 include Pacecar::State
20 end
21
fd9f685 @mjankowski note about rails 3.1 compatibility
mjankowski authored
22 Pacecar supports mysql, postgres and sqlite database drivers, and is compatible with Rails 3.0.x and 3.1.x versions.
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
23
24 Installation
25 ------------
26
27 For rails 3, just include in your Gemfile
28
29 gem 'pacecar'
30
31 For prior rails versions, there is a rails2 branch to use:
32
33 gem 'pacecar', :git => 'git://github.com/thoughtbot/pacecar.git', :branch => 'rails2'
34
35 Usage
36 -----
37
84e1fe7 @gabebw README formatting.
gabebw authored
38 Assuming a database schema:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
39
40 class CreateSchema < ActiveRecord::Migration
41 def self.up
42 create_table :users, :force => true do |t|
43 t.boolean :admin, :default => false, :null => false
44 t.datetime :approved_at
45 t.datetime :rejected_at
46 t.string :first_name
47 t.string :last_name
48 t.text :description
49 t.timestamps
50 end
51 create_table :posts, :force => true do |t|
52 t.string :owner_type
53 t.integer :owner_id
54 t.string :publication_state
55 t.string :post_type
56 t.timestamps
57 end
58 create_table :comments, :force => true do |t|
59 t.integer :user_id
60 t.text :description
b4abc54 @mjankowski add association calculation method to order by results of a sql funct…
mjankowski authored
61 t.integer :rating
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
62 t.timestamps
63 end
64 end
65 end
66
84e1fe7 @gabebw README formatting.
gabebw authored
67 And some basic model declarations:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
68
69 class User < ActiveRecord::Base
70 include Pacecar
71 has_many :posts, :as => :owner
72 has_many :comments
73 has_many :articles
74 has_ranking :comments
75 has_recent_records :comments
76 has_recent_records :articles, :comments
b4abc54 @mjankowski add association calculation method to order by results of a sql funct…
mjankowski authored
77 has_calculated_records :comments, :on => :rating
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
78 end
84e1fe7 @gabebw README formatting.
gabebw authored
79
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
80 class Post < ActiveRecord::Base
81 include Pacecar
82 PUBLICATION_STATES = %w(Draft Submitted Rejected Accepted)
83 TYPES = %w(Free Open Private Anonymous PostModern)
84 belongs_to :owner, :polymorphic => true
85 has_state :publication_state
86 has_state :post_type, :with => TYPES
87 has_polymorph :owner
88 end
84e1fe7 @gabebw README formatting.
gabebw authored
89
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
90 class Comment < ActiveRecord::Base
91 include Pacecar
92 belongs_to :user
93 end
84e1fe7 @gabebw README formatting.
gabebw authored
94
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
95 class Article < ActiveRecord::Base
96 belongs_to :user
97 end
98
99 All columns
100 -----------
101
84e1fe7 @gabebw README formatting.
gabebw authored
102 Records where approved\_at is not null, or where it is null:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
103
104 User.approved_at_present
105 User.approved_at_missing
106
84e1fe7 @gabebw README formatting.
gabebw authored
107 Records where first\_name is not null, or where it is null:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
108
109 User.first_name_present
110 User.first_name_missing
111
84e1fe7 @gabebw README formatting.
gabebw authored
112 Records ordered by first\_name (default to 'asc', can specify to override):
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
113
114 User.by_first_name
115 User.by_first_name(:asc)
116 User.by_first_name(:desc)
117
84e1fe7 @gabebw README formatting.
gabebw authored
118 Records where an attribute matches a search term (column LIKE "%term%"):
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
119
120 User.first_name_matches('John')
121
84e1fe7 @gabebw README formatting.
gabebw authored
122 Records where an attribute starts or ends with a search term:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
123
124 User.first_name_starts_with('A')
125 User.first_name_ends_with('a')
126
84e1fe7 @gabebw README formatting.
gabebw authored
127 Records where an attribute matches exactly a term:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
128
129 User.first_name_equals('John')
130
84e1fe7 @gabebw README formatting.
gabebw authored
131 Records where any non-state text or string column matches term:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
132
133 User.search_for('test')
134
84e1fe7 @gabebw README formatting.
gabebw authored
135 Records where any of a list of columns match the term:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
136
137 User.search_for 'test', :on => [:first_name, :last_name]
138
84e1fe7 @gabebw README formatting.
gabebw authored
139 Records where all of a list of columns match the term:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
140
141 User.search_for 'test', :on => [:first_name, :last_name], :require => :all
142
143 Boolean columns
144 ---------------
145
84e1fe7 @gabebw README formatting.
gabebw authored
146 Records that are all admins or non-admins:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
147
148 User.admin
149 User.not_admin
150
84e1fe7 @gabebw README formatting.
gabebw authored
151 The "balance" (count of true minus false for column in question):
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
152
153 User.admin_balance
154
155 Datetime columns
156 ----------------
157
84e1fe7 @gabebw README formatting.
gabebw authored
158 Records approved before or after certain times:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
159
160 User.approved_at_before(5.days.ago)
161 User.approved_at_after(4.weeks.ago)
162
84e1fe7 @gabebw README formatting.
gabebw authored
163 Records with approved\_at in the past or future:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
164
165 User.approved_at_in_past
166 User.approved_at_in_future
167
84e1fe7 @gabebw README formatting.
gabebw authored
168 Records with approved\_at inside or outside of two times:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
169
170 User.approved_at_inside(10.days.ago, 1.day.ago)
171 User.approved_at_outside(2.days.ago, 1.day.ago)
172
84e1fe7 @gabebw README formatting.
gabebw authored
173 Records with certain year, month or day:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
174
175 User.approved_at_in_year(2000)
176 User.approved_at_in_month(01)
177 User.approved_at_in_day(01)
178
84e1fe7 @gabebw README formatting.
gabebw authored
179 Records with a duration (time delta between two columns) of, over or under a certain number of days:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
180
181 User.with_duration_of(14, :approved_at, :rejected_at)
182 User.with_duration_over(14, :approved_at, :rejected_at)
183 User.with_duration_under(14, :approved_at, :rejected_at)
184
185 Polymorphic relationships
186 -------------------------
187
84e1fe7 @gabebw README formatting.
gabebw authored
188 Records which have an owner\_type of User:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
189
190 Post.for_owner_type(User)
191
192 Associations
193 ------------
194
84e1fe7 @gabebw README formatting.
gabebw authored
195 Records with the most and least associated records:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
196
197 User.maximum_comments
198 User.minimum_comments
199
84e1fe7 @gabebw README formatting.
gabebw authored
200 Records with associated records since a certain time:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
201
202 User.recent_comments_since(2.days.ago)
203 User.recent_comments_and_posts_since(3.days.ago)
204 User.recent_comments_or_posts_since(4.days.ago)
205
84e1fe7 @gabebw README formatting.
gabebw authored
206 Records with highest and lowest association column average:
b4abc54 @mjankowski add association calculation method to order by results of a sql funct…
mjankowski authored
207
208 User.by_comments_highest_rating_average
209 User.by_comments_lowest_rating_average
210
84e1fe7 @gabebw README formatting.
gabebw authored
211 Records with highest and lowest association column total:
b4abc54 @mjankowski add association calculation method to order by results of a sql funct…
mjankowski authored
212
213 User.by_comments_highest_rating_total
214 User.by_comments_lowest_rating_total
215
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
216 State columns
217 -------------
218
84e1fe7 @gabebw README formatting.
gabebw authored
219 Records which are in a particular state, or not in a state:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
220
221 Post.publication_state_draft
222 Post.post_type_not_open
223
84e1fe7 @gabebw README formatting.
gabebw authored
224 Query methods on instances to check state:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
225
226 Post.first.publication_state_draft?
227 Post.last.post_type_not_open?
228
229 Numeric columns
230 ---------------
231
84e1fe7 @gabebw README formatting.
gabebw authored
232 Records which are greater than or less than a certain value:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
233
234 User.age_greater_than(21)
235 User.age_greater_than_or_equal_to(21)
236 User.age_less_than(21)
237 User.age_less_than_or_equal_to(21)
238
239 Limits
240 ------
241
84e1fe7 @gabebw README formatting.
gabebw authored
242 First x records:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
243
244 User.limited(10)
245
246 Named scopes
247 ------------
248
249 Because these are all scope, you can combine them.
250
84e1fe7 @gabebw README formatting.
gabebw authored
251 To get all users that have a first\_name set, who are admins and approved more than 2 weeks ago, ordered by their first name:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
252
253 User.first_name_present.admin.approved_at_before(2.weeks.ago).by_first_name
254
84e1fe7 @gabebw README formatting.
gabebw authored
255 To get the top 10 commenters:
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
256
91f56cb @dipth Fixed a small typo
dipth authored
257 User.maximum_comments.limited(10)
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
258
259 Supported Databases
260 -------------------
261
262 * MySQL
263 * SQLite
1737a7c @mjankowski Add postgres to supported database list
mjankowski authored
264 * Postgres
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
265
266 Credits
267 -------
268
269 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
270
271 Pacecar is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
272
3aa70c9 @mjankowski add link to contributors page
mjankowski authored
273 Thank you to all [the contributors](https://github.com/thoughtbot/pacecar/contributors)!
274
2deab80 convert readme to markdown and update credit and license info
Chad Pytel authored
275 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
276
277 License
278 -------
279
280 Pacecar is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
Something went wrong with that request. Please try again.