Skip to content
Browse files

Added some documentation

  • Loading branch information...
1 parent 4cbce1e commit 38aa5f31f952ae5d3f54da0b681fff408f8e4614 @dim dim committed
View
12 lib/bsm/constrainable/model.rb
@@ -1,3 +1,4 @@
+# Includable module, for ActiveRecord::Base
module Bsm::Constrainable::Model
extend ActiveSupport::Concern
@@ -8,6 +9,17 @@ module Bsm::Constrainable::Model
module ClassMethods
+ # Constraint definition for a model. Example:
+ #
+ # class Post < ActiveRecord::Base
+ # constrainable do
+ # # Add your default constraints
+ # end
+ # constrainable :custom do
+ # # Add your custom constraints
+ # end
+ # end
+ #
def constrainable(name = nil, &block)
name = name.present? ? name.to_sym : :default
_constrainable[name] ||= Bsm::Constrainable::Schema.new(self)
View
9 lib/bsm/constrainable/relation.rb
@@ -1,5 +1,14 @@
+# Extension for ActiveRecord::Relation
module Bsm::Constrainable::Relation
+ # Apply contraints. Example:
+ #
+ # Post.constrain("created_at" => { "lt" => "2011-01-01" }})
+ #
+ # You can also combine it with multiple scopes:
+ #
+ # Post.archived.includes(:author).constrain(params[:where]).paginate :page => 1
+ #
def constrain(*args)
params = args.extract_options!
schema = @klass.constrainable(args.first)
View
36 lib/bsm/constrainable/schema.rb
@@ -1,12 +1,20 @@
+# Schema definition.
class Bsm::Constrainable::Schema < Hash
include ::Bsm::Constrainable::Util
Field = ::Bsm::Constrainable::Field
- def initialize(klass)
+ def initialize(klass) # :nodoc:
@klass = klass
super()
end
+ # Define multiple constrainable columns. Expects 1-n column names (must be
+ # real columns) and an options Hash. Examples:
+ #
+ # fields :id
+ # fields :id, :author_id
+ # fields :id, :author_id, :with => [:in, :not_in]
+ #
def fields(*names)
options = names.extract_options!
names.map(&:to_s).each do |name|
@@ -17,6 +25,28 @@ def fields(*names)
end
end
+ # Define constrainable names (don't have to be real columns). Expects 1-n
+ # names and an options Hash. Options, must specify the type via <tt>:as</tt>.
+ # Examples:
+ #
+ # # One match
+ # match :id, :as => :number
+ #
+ # # Multiple matches
+ # match :id, :author_id, :as => :integer, :with => [:in, :not_in]
+ #
+ # # Use a specific column
+ # match :created, :using => :created_at, :as => :timestamp, :with => [:lt, :between]
+ #
+ # # Complex example, using an attribute from another table, and ensure it's included (LEFT OUTER JOIN)
+ # match :author, :using => lambda { Author.scope.table[:name] }, :scope => { includes(:author) }, :as => :string, :with => [:eq, :matches]
+ #
+ # There are also several short-cutrs available. Examples:
+ #
+ # timestamp :created, :using => :created_at, :with => [:lt, :between]
+ # number :id, :author_id
+ # string :title, :with => [:eq, :matches]
+ #
def match(*names)
options = names.extract_options!
kind = options.delete(:as)
@@ -27,11 +57,11 @@ def match(*names)
end
alias_method :field, :match
- def respond_to?(sym)
+ def respond_to?(sym) # :nodoc:
super || Field.registered?(sym)
end
- def merge(relation, params)
+ def merge(relation, params) # :nodoc:
each_part(params) do |name, part|
self[name].each do |constrain|
relation = constrain.merge(relation, part)
View
2 lib/bsm/constrainable/util.rb
@@ -1,4 +1,4 @@
-module Bsm::Constrainable::Util
+module Bsm::Constrainable::Util # :nodoc:
extend self
def normalized_hash(hash)

0 comments on commit 38aa5f3

Please sign in to comment.
Something went wrong with that request. Please try again.