scrivener 0.0.1

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,123 @@
+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
+chose 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:
+
+    # 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 other is a minor obstacle.
+
+Now see what happens with Scrivener:
+
+    # 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 ask the name on signup.
+    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 /^(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: title)
+    #=> 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.
+
+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,56 @@
+require File.expand_path("scrivener/validations", File.dirname(__FILE__))
+
+class Scrivener
+  VERSION = "0.0.1"
+
+  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|
+        att = ivar.to_s.sub(/@/, "").to_sym
+        atts[att] = send(att)
+      end
+    end
+  end
+end
+

data/lib/scrivener/validations.rb

@@ -0,0 +1,152 @@
+class Scrivener
+
+  # Provides a base implementation for extensible validation routines.
+  # {Scrivener::Validations} currently only provides the following assertions:
+  #
+  # * assert
+  # * assert_present
+  # * assert_format
+  # * assert_numeric
+  #
+  # 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, /^\d+$/, error)
+      end
+    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              = "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/soveran/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,82 @@
+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
+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

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: scrivener
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Michel Martens
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-18 00:00:00.000000000 -03:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: &2154104200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2154104200
+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
+has_rdoc: true
+homepage: http://github.com/soveran/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.6.2
+signing_key: 
+specification_version: 3
+summary: Validation frontend for models.
+test_files: []