drpentode-scrivener 0.0.3

data/AUTHORS

@@ -0,0 +1,3 @@
+* Cyril David (cyx)
+* Lucas Nasif (ehqhvm)
+* Michel Martens (soveran)

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Michel Martens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+Scrivener
+=========
+
+Validation frontend for models.
+
+Description
+-----------
+
+Scrivener removes the validation responsibility from models and acts as a
+filter for whitelisted attributes.
+
+A model may expose different APIs to satisfy different purposes. For example,
+the set of validations for a User in a Sign up process may not be the same
+as the one exposed to an Admin when editing a user profile. While you want
+the User to provide an email, a password and a password confirmation, you
+probably don't want the admin to mess with those attributes at all.
+
+In a wizard, different model states ask for different validations, and a single
+set of validations for the whole process is not the best solution.
+
+Scrivener is Bureaucrat's little brother. It draws all the inspiration from it
+and its features are a subset of Bureaucrat's. For a more robust and tested
+solution, please [check it](https://github.com/tizoc/bureaucrat).
+
+This library exists to satify the need of extracting Ohm's validations for
+reuse in other scenarios. By doing this, all projects using `Ohm::Validations`
+will be able to profit from extra assertions such as those provided by
+[ohm-contrib](https://github.com/cyx/ohm-contrib).
+
+Usage
+-----
+
+Using Scrivener feels very natural no matter what underlying model you are
+using. As it provides its own validation and whitelisting features, you can
+choose to ignore the ones that come bundled with ORMs.
+
+This short example illustrates how to move the validation and whitelisting
+responsibilities away from the model and into Scrivener:
+
+```ruby
+# We use Sequel::Model in this example, but it applies to other ORMs such
+# as Ohm or ActiveRecord.
+class Article < Sequel::Model
+
+  # Whitelist for mass assigned attributes.
+  set_allowed_columns :title, :body, :state
+
+  # Validations for all contexts.
+  def validate
+    validates_presence :title
+    validates_presence :body
+    validates_presence :state
+  end
+end
+
+title = "Bartleby, the Scrivener"
+body  = "I am a rather elderly man..."
+
+# When using the model...
+article = Article.new(title: title, body: body)
+
+article.valid?            #=> false
+article.errors.on(:state) #=> ["cannot be empty"]
+```
+
+Of course, what you would do instead is declare `:title` and `:body` as allowed
+columns, then assign `:state` using the attribute accessor. The reason for this
+example is to show how you need to work around the fact that there's a single
+declaration for allowed columns and validations, which in many cases is a great
+feature and in others is a minor obstacle.
+
+Now see what happens with Scrivener:
+
+```ruby
+# Now the model has no validations or whitelists. It may still have schema
+# constraints, which is a good practice to enforce data integrity.
+class Article < Sequel::Model
+end
+
+# The attribute accessors are the only fields that will be set. If more
+# fields are sent when using mass assignment, a NoMethodError exception is
+# raised.
+#
+# Note how in this example we don't accept the status attribute.
+class Edit < Scrivener
+  attr_accessor :title
+  attr_accessor :body
+
+  def validate
+    assert_present :title
+    assert_present :body
+  end
+end
+
+edit = Edit.new(title: title, body: body)
+edit.valid?               #=> true
+
+article = Article.new(edit.attributes)
+article.save
+
+# And now we only ask for the status.
+class Publish < Scrivener
+  attr_accessor :status
+
+  def validate
+    assert_format :status, /^(published|draft)$/
+  end
+end
+
+publish = Publish.new(status: "published")
+publish.valid?            #=> true
+
+article.update_attributes(publish.attributes)
+
+# If we try to change other fields...
+publish = Publish.new(status: "published", title: "foo")
+#=> NoMethodError: undefined method `title=' for #<Publish...>
+```
+
+It's important to note that using Scrivener implies a greater risk than using
+the model validations. Having a central repository of mass assignable
+attributes and validations is more secure in most scenarios.
+
+Assertions
+-----------
+
+Scrivener ships with some basic assertions. The following is a brief description
+for each of them:
+
+### assert
+
+The `assert` method is used by all the other assertions. It pushes the
+second parameter to the list of errors if the first parameter evaluates
+to false.
+
+``` ruby
+def assert(value, error)
+   value or errors[error.first].push(error.last) && false
+end
+```
+
+### assert_present
+
+Checks that the given field is not nil or empty. The error code for this
+assertion is `:not_present`.
+
+### assert_format
+
+Checks that the given field matches the provided regular expression.
+The error code for this assertion is `:format`.
+
+### assert_numeric
+
+Checks that the given field holds a number as a Fixnum or as a string
+representation. The error code for this assertion is `:not_numeric`.
+
+### assert_url
+
+Provides a pretty general URL regular expression match. An important
+point to make is that this assumes that the URL should start with
+`http://` or `https://`. The error code for this assertion is
+`:not_url`.
+
+### assert_email
+
+In this current day and age, almost all web applications need to
+validate an email address. This pretty much matches 99% of the emails
+out there. The error code for this assertion is `:not_email`.
+
+### assert_member
+
+Checks that a given field is contained within a set of values (i.e.
+like an `ENUM`).
+
+``` ruby
+def validate
+  assert_member :state, %w{pending paid delivered}
+end
+```
+
+The error code for this assertion is `:not_valid`
+
+### assert_length
+
+Checks that a given field's length falls under a specified range.
+
+``` ruby
+def validate
+  assert_length :username, 3..20
+end
+```
+
+The error code for this assertion is `:not_in_range`.
+
+### assert_decimal
+
+Checks that a given field looks like a number in the human sense
+of the word. Valid numbers are: 0.1, .1, 1, 1.1, 3.14159, etc.
+
+The error code for this assertion is `:not_decimal`.
+
+Installation
+------------
+
+    $ gem install scrivener

data/Rakefile

@@ -0,0 +1,6 @@
+task :test do
+  require "cutest"
+  Cutest.run(Dir["test/*.rb"])
+end
+
+task :default => :test

data/lib/scrivener.rb

@@ -0,0 +1,58 @@
+require_relative "scrivener/validations"
+
+class Scrivener
+  VERSION = "0.0.3"
+
+  include Validations
+
+  # Initialize with a hash of attributes and values.
+  # If extra attributes are sent, a NoMethodError exception will be raised.
+  #
+  # The grand daddy of all assertions. If you want to build custom
+  # assertions, or even quick and dirty ones, you can simply use this method.
+  #
+  # @example
+  #
+  #   class EditPost < Scrivener
+  #     attr_accessor :title
+  #     attr_accessor :body
+  #
+  #     def validate
+  #       assert_present :title
+  #       assert_present :body
+  #     end
+  #   end
+  #
+  #   edit = EditPost.new(title: "Software Tools")
+  #
+  #   edit.valid? #=> false
+  #
+  #   edit.errors[:title] #=> []
+  #   edit.errors[:body]  #=> [:not_present]
+  #
+  #   edit.body = "Recommended reading..."
+  #
+  #   edit.valid? #=> true
+  #
+  #   # Now it's safe to initialize the model.
+  #   post = Post.new(edit.attributes)
+  #   post.save
+  def initialize(attrs)
+    attrs.each do |key, val|
+      send(:"#{key}=", val)
+    end
+  end
+
+  # Return hash of attributes and values.
+  def attributes
+    Hash.new.tap do |atts|
+      instance_variables.each do |ivar|
+        next if ivar == :@errors
+
+        att = ivar[1..-1].to_sym
+        atts[att] = send(att)
+      end
+    end
+  end
+end
+

data/lib/scrivener/validations.rb

@@ -0,0 +1,193 @@
+class Scrivener
+  require "uri"
+
+  # Provides a base implementation for extensible validation routines.
+  # {Scrivener::Validations} currently only provides the following assertions:
+  #
+  # * assert
+  # * assert_present
+  # * assert_format
+  # * assert_numeric
+  # * assert_url
+  # * assert_email
+  # * assert_member
+  # * assert_length
+  # * assert_decimal
+  #
+  # The core tenets that Scrivener::Validations advocates can be summed up in a
+  # few bullet points:
+  #
+  # 1. Validations are much simpler and better done using composition rather
+  #    than macros.
+  # 2. Error messages should be kept separate and possibly in the view or
+  #    presenter layer.
+  # 3. It should be easy to write your own validation routine.
+  #
+  # Other validations are simply added on a per-model or per-project basis.
+  #
+  # If you want other validations you may want to take a peek at Ohm::Contrib
+  # and all of the validation modules it provides.
+  #
+  # @see http://cyx.github.com/ohm-contrib/doc/Ohm/WebValidations.html
+  # @see http://cyx.github.com/ohm-contrib/doc/Ohm/NumberValidations.html
+  # @see http://cyx.github.com/ohm-contrib/doc/Ohm/ExtraValidations.html
+  #
+  # @example
+  #
+  #   class Quote
+  #     attr_accessor :title
+  #     attr_accessor :price
+  #     attr_accessor :date
+  #
+  #     def validate
+  #       assert_present :title
+  #       assert_numeric :price
+  #       assert_format  :date, /\A[\d]{4}-[\d]{1,2}-[\d]{1,2}\z
+  #     end
+  #   end
+  #
+  #   s = Quote.new
+  #   s.valid?
+  #   # => false
+  #
+  #   s.errors
+  #   # => { :title => [:not_present],
+  #          :price => [:not_numeric],
+  #          :date  => [:format] }
+  #
+  module Validations
+
+    # Check if the current model state is valid. Each call to {#valid?} will
+    # reset the {#errors} array.
+    #
+    # All validations should be declared in a `validate` method.
+    #
+    # @example
+    #
+    #   class Login
+    #     attr_accessor :username
+    #     attr_accessor :password
+    #
+    #     def validate
+    #       assert_present :user
+    #       assert_present :password
+    #     end
+    #   end
+    #
+    def valid?
+      errors.clear
+      validate
+      errors.empty?
+    end
+
+    # Base validate implementation. Override this method in subclasses.
+    def validate
+    end
+
+    # Hash of errors for each attribute in this model.
+    def errors
+      @errors ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+  protected
+
+    # Allows you to do a validation check against a regular expression.
+    # It's important to note that this internally calls {#assert_present},
+    # therefore you need not structure your regular expression to check
+    # for a non-empty value.
+    #
+    # @param [Symbol] att The attribute you want to verify the format of.
+    # @param [Regexp] format The regular expression with which to compare
+    #                 the value of att with.
+    # @param [Array<Symbol, Symbol>] error The error that should be returned
+    #                                when the validation fails.
+    def assert_format(att, format, error = [att, :format])
+      if assert_present(att, error)
+        assert(send(att).to_s.match(format), error)
+      end
+    end
+
+    # The most basic and highly useful assertion. Simply checks if the
+    # value of the attribute is empty.
+    #
+    # @param [Symbol] att The attribute you wish to verify the presence of.
+    # @param [Array<Symbol, Symbol>] error The error that should be returned
+    #                                when the validation fails.
+    def assert_present(att, error = [att, :not_present])
+      assert(!send(att).to_s.empty?, error)
+    end
+
+    # Checks if all the characters of an attribute is a digit. If you want to
+    # verify that a value is a decimal, try looking at Ohm::Contrib's
+    # assert_decimal assertion.
+    #
+    # @param [Symbol] att The attribute you wish to verify the numeric format.
+    # @param [Array<Symbol, Symbol>] error The error that should be returned
+    #                                when the validation fails.
+    # @see http://cyx.github.com/ohm-contrib/doc/Ohm/NumberValidations.html
+    def assert_numeric(att, error = [att, :not_numeric])
+      if assert_present(att, error)
+        assert_format(att, /\A\d+\z/, error)
+      end
+    end
+
+    URL = URI::regexp(%w(http https))
+
+    def assert_url(att, error = [att, :not_url])
+      if assert_present(att, error)
+        assert_format(att, URL, error)
+      end
+    end
+
+    EMAIL = /\A([\w\!\#$\%\&\'\*\+\-\/\=\?\^\`{\|\}\~]+\.)*
+            [\w\!\#$\%\&\'\*\+\-\/\=\?\^\`{\|\}\~]+@
+            ((((([a-z0-9]{1}[a-z0-9\-]{0,62}[a-z0-9]{1})|[a-z])\.)+
+            [a-z]{2,6})|(\d{1,3}\.){3}\d{1,3}(\:\d{1,5})?)\z/ix
+
+    def assert_email(att, error = [att, :not_email])
+      if assert_present(att, error)
+        assert_format(att, EMAIL, error)
+      end
+    end
+
+    def assert_member(att, set, err = [att, :not_valid])
+      assert(set.include?(send(att)), err)
+    end
+
+    def assert_length(att, range, error = [att, :not_in_range])
+      if assert_present(att, error)
+        val = send(att).to_s
+        assert range.include?(val.length), error
+      end
+    end
+
+    DECIMAL = /\A(\d+)?(\.\d+)?\z/
+
+    def assert_decimal(att, error = [att, :not_decimal])
+      assert_format att, DECIMAL, error
+    end
+
+    # The grand daddy of all assertions. If you want to build custom
+    # assertions, or even quick and dirty ones, you can simply use this method.
+    #
+    # @example
+    #
+    #   class CreatePost
+    #     attr_accessor :slug
+    #     attr_accessor :votes
+    #
+    #     def validate
+    #       assert_slug :slug
+    #       assert votes.to_i > 0, [:votes, :not_valid]
+    #     end
+    #
+    #   protected
+    #     def assert_slug(att, error = [att, :not_slug])
+    #       assert send(att).to_s =~ /\A[a-z\-0-9]+\z/, error
+    #     end
+    #   end
+    def assert(value, error)
+      value or errors[error.first].push(error.last) && false
+    end
+  end
+end

data/scrivener.gemspec

@@ -0,0 +1,21 @@
+require "./lib/scrivener"
+
+Gem::Specification.new do |s|
+  s.name              = "drpentode-scrivener"
+  s.version           = Scrivener::VERSION
+  s.summary           = "Validation frontend for models."
+  s.description       = "Scrivener removes the validation responsibility from models and acts as a filter for whitelisted attributes."
+  s.authors           = ["Michel Martens"]
+  s.email             = ["michel@soveran.com"]
+  s.homepage          = "http://github.com/drpentode/scrivener"
+  s.files = Dir[
+    "LICENSE",
+    "AUTHORS",
+    "README.md",
+    "Rakefile",
+    "lib/**/*.rb",
+    "*.gemspec",
+    "test/**/*.rb"
+  ]
+  s.add_development_dependency "cutest"
+end

data/test/scrivener_test.rb

@@ -0,0 +1,197 @@
+require File.expand_path("../lib/scrivener", File.dirname(__FILE__))
+
+class S < Scrivener
+  attr_accessor :a
+  attr_accessor :b
+end
+
+scope do
+  test "raise when there are extra fields" do
+    atts = { :a => 1, :b => 2, :c => 3 }
+
+    assert_raise NoMethodError do
+      s = S.new(atts)
+    end
+  end
+
+  test "not raise when there are less fields" do
+    atts = { :a => 1 }
+
+    assert s = S.new(atts)
+  end
+
+  test "return attributes" do
+    atts = { :a => 1, :b => 2 }
+
+    s = S.new(atts)
+
+    assert_equal atts, s.attributes
+  end
+end
+
+class T < Scrivener
+  attr_accessor :a
+  attr_accessor :b
+
+  def validate
+    assert_present :a
+    assert_present :b
+  end
+end
+
+scope do
+  test "validations" do
+    atts = { :a => 1, :b => 2 }
+
+    t = T.new(atts)
+
+    assert t.valid?
+  end
+
+  test "validation errors" do
+    atts = { :a => 1 }
+
+    t = T.new(atts)
+
+    assert_equal false, t.valid?
+    assert_equal [], t.errors[:a]
+    assert_equal [:not_present], t.errors[:b]
+  end
+
+  test "attributes without @errors" do
+    atts = { :a => 1, :b => 2 }
+
+    t = T.new(atts)
+
+    t.valid?
+    assert_equal atts, t.attributes
+  end
+end
+
+class Quote
+  include Scrivener::Validations
+
+  attr_accessor :foo
+
+  def validate
+    assert_present :foo
+  end
+end
+
+scope do
+  test "validations without Scrivener" do
+    q = Quote.new
+    q.foo = 1
+    assert q.valid?
+
+    q = Quote.new
+    assert_equal false, q.valid?
+    assert_equal [:not_present], q.errors[:foo]
+  end
+end
+
+class Post < Scrivener
+  attr_accessor :url, :email
+
+  def validate
+    assert_url :url
+    assert_email :email
+  end
+end
+
+scope do
+  test "email & url" do
+    p = Post.new({})
+
+    assert ! p.valid?
+    assert_equal [:not_url],  p.errors[:url]
+    assert_equal [:not_email],  p.errors[:email]
+
+    p = Post.new(url: "google.com", email: "egoogle.com")
+
+    assert ! p.valid?
+    assert_equal [:not_url],  p.errors[:url]
+    assert_equal [:not_email],  p.errors[:email]
+
+    p = Post.new(url: "http://google.com", email: "me@google.com")
+    assert p.valid?
+
+    # server name without a / but a ? is a valid URL
+    p = Post.new(url: "http://google.com?blah=blah", email: "me@google.com")
+    assert p.valid?
+  end
+end
+
+class Person < Scrivener
+  attr_accessor :username
+
+  def validate
+    assert_length :username, 3..10
+  end
+end
+
+scope do
+  test "length validation" do
+    p = Person.new({})
+
+    assert ! p.valid?
+    assert p.errors[:username].include?(:not_in_range)
+
+    p = Person.new(username: "fo")
+    assert ! p.valid?
+    assert p.errors[:username].include?(:not_in_range)
+
+    p = Person.new(username: "foofoofoofo")
+    assert ! p.valid?
+    assert p.errors[:username].include?(:not_in_range)
+
+    p = Person.new(username: "foo")
+    assert p.valid?
+  end
+end
+
+class Order < Scrivener
+  attr_accessor :status
+
+  def validate
+    assert_member :status, %w{pending paid delivered}
+  end
+end
+
+scope do
+  test "member validation" do
+    o = Order.new({})
+    assert ! o.valid?
+    assert_equal [:not_valid], o.errors[:status]
+
+    o = Order.new(status: "foo")
+    assert ! o.valid?
+    assert_equal [:not_valid], o.errors[:status]
+
+    %w{pending paid delivered}.each do |status|
+      o = Order.new(status: status)
+      assert o.valid?
+    end
+  end
+end
+
+class Product < Scrivener
+  attr_accessor :price
+
+  def validate
+    assert_decimal :price
+  end
+end
+
+scope do
+  test "decimal validation" do
+    p = Product.new({})
+    assert ! p.valid?
+    assert_equal [:not_decimal], p.errors[:price]
+
+    %w{10 10.1 10.100000 0.100000 .1000}.each do |price|
+      p = Product.new(price: price)
+      assert p.valid?
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: drpentode-scrivener
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+  prerelease: 
+platform: ruby
+authors:
+- Michel Martens
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Scrivener removes the validation responsibility from models and acts
+  as a filter for whitelisted attributes.
+email:
+- michel@soveran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- AUTHORS
+- README.md
+- Rakefile
+- lib/scrivener/validations.rb
+- lib/scrivener.rb
+- scrivener.gemspec
+- test/scrivener_test.rb
+homepage: http://github.com/drpentode/scrivener
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Validation frontend for models.
+test_files: []