scrivener 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d856e30f00eb2fbb898b1f436706d513921d7b6b
-  data.tar.gz: 2cee2565f0507e0ebf8177d2cb57626f683528c1
+SHA256:
+  metadata.gz: ca36d57e390df275cd0365e9b8d0b9a8f3d0dda7b00a39aaaf4a7da37a9f0202
+  data.tar.gz: b48a3d6ab1a6646fc649d12f501d97b36dfde4729d377848b0b4d97c8147b53b
 SHA512:
-  metadata.gz: 068427019df2072dc56517932811d744dd8fcbc4ad9842880382c9e8a3dfc46f118e066d24b73a51364dbbf6dcce42e5ffeb3d1121b714acf61e8066acff9c56
-  data.tar.gz: c2acd1812ffc52b268d1294c2c744cda6e92f17c5a0011e8777400b39215f276ce5ff43fbae5d1f1e17dcc440aaad160a83b851c224a1bd7b51e62f5bacfe29d
+  metadata.gz: cbe35ddb7f28d6cbee5d7f31731af970cef677060f6428f4aec67da1ec11ab11e6f78edb3aee2dfda56b4a950cf9e16a2a6326eb65e5119d3e4fb1bbd615396a
+  data.tar.gz: 45e428e8d5204f8493199d020bd5af06fd857cfa42b67aac4b03e078b23db7a47bce1ed7588621198ad5fb797f102aab1178cc7245444a25bdd2cc446ba51f51

data/CONTRIBUTING

@@ -0,0 +1,19 @@
+This code tries to solve a particular problem with a very simple
+implementation. We try to keep the code to a minimum while making
+it as clear as possible. The design is very likely finished, and
+if some feature is missing it is possible that it was left out on
+purpose. That said, new usage patterns may arise, and when that
+happens we are ready to adapt if necessary.
+
+A good first step for contributing is to meet us on IRC and discuss
+ideas. We spend a lot of time on #lesscode at freenode, always ready
+to talk about code and simplicity. If connecting to IRC is not an
+option, you can create an issue explaining the proposed change and
+a use case. We pay a lot of attention to use cases, because our
+goal is to keep the code base simple. Usually the result of a
+conversation is the creation of a different tool.
+
+Please don't start the conversation with a pull request. The code
+should come at last, and even though it may help to convey an idea,
+more often than not it draws the attention to a particular
+implementation.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Michel Martens
+Copyright (c) 2011-2015 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

data/README.md

@@ -6,81 +6,18 @@ 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.
+Scrivener removes the validation responsibility from models and
+acts as a filter for whitelisted attributes. Read about the
+[motivation](#motivation) to understand why this separation of
+concerns is important.
 
 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:
+A very basic example would be creating a blog post:
 
 ```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[:state] #=> [:not_present]
-```
-
-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
+class CreateBlogPost < Scrivener
   attr_accessor :title
   attr_accessor :body
 
@@ -89,40 +26,42 @@ class Edit < Scrivener
     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
+In order to use it, you have to create an instance of `CreateBlogPost`
+by passing a hash with the attributes `title` and `body` and their
+corresponding values:
 
-  def validate
-    assert_format :status, /^(published|draft)$/
-  end
-end
+```ruby
+params = {
+  title: "Bartleby",
+  body: "I am a rather elderly man..."
+}
 
-publish = Publish.new(status: "published")
-publish.valid?            #=> true
+filter = CreateBlogPost.new(params)
+```
 
-article.update_attributes(publish.attributes)
+Now you can run the validations by calling `filter.valid?`, and you
+can retrieve the attributes by calling `filter.attributes`. If the
+validation fails, a hash of attributes and error codes will be
+available by calling `filter.errors`. For example:
 
-# Extra fields are discarded
-publish = Publish.new(status: "published", title: "foo")
-publish.attributes #=> { :status => "published" }
+```ruby
+if filter.valid?
+  puts filter.attributes
+else
+  puts filter.errors
+end
 ```
 
-Slices
-------
+For now, we are just printing the attributes and the list of errors,
+but often you will use the attributes to create an instance of a
+model, and you will display the error messages in a view.
 
-If you don't need all the attributes after the filtering is done,
-you can fetch just the ones you need. For example:
+Let's consider the case of creating a new user:
 
 ```ruby
-class SignUp < Scrivener
+class CreateUser < Scrivener
   attr_accessor :email
   attr_accessor :password
   attr_accessor :password_confirmation
@@ -135,33 +74,75 @@ class SignUp < Scrivener
     end
   end
 end
+```
+
+The filter looks very similar, but as you can see the validations
+return booleans, thus they can be nested. In this example, we don't
+want to bother asserting if the password and the password confirmation
+are equal if the password was not provided.
+
+Let's instantiate the filter:
+
+```ruby
+params = {
+  email: "info@example.com",
+  password: "monkey",
+  password_confirmation: "monkey"
+}
 
-filter = SignUp.new(email: "info@example.com",
-                    password: "monkey",
-                    password_confirmation: "monkey")
+filter = CreateUser.new(params)
+```
 
+If the validation succeeds, we only need email and password to
+create a new user, and we can discard the password_confirmation.
+The `filter.slice` method receives a list of attributes and returns
+the attributes hash with any other attributes removed. In this
+example, the hash returned by `filter.slice` will contain only the
+`email` and `password` fields:
 
-# If the validation succeeds, we only need email and password to
-# create a new user, and we can discard the password_confirmation.
+```ruby
 if filter.valid?
   User.create(filter.slice(:email, :password))
 end
 ```
 
-By calling `slice` with a list of attributes, you get a hash with only
-those key/value pairs.
+Sometimes we might want to use parameters from the outside for validation,
+but don't want the validator to treat them as attributes. In that case we
+can pass arguments to `#valid?`, and they will be forwarded to `#validate`.
+
+```ruby
+class CreateComment < Scrivener
+  attr_accessor :content
+  attr_accessor :article_id
+
+  def validate(available_articles:)
+    assert_present :content
+    assert_member :article_id, available_articles.map(&:id)
+  end
+end
+```
+
+```ruby
+params = {
+  content:    "this is a comment",
+  article_id: 57,
+}
+
+filter = CreateComment.new(params)
+
+filter.valid?(available_articles: user.articles)
+```
 
 Assertions
 -----------
 
-Scrivener ships with some basic assertions. The following is a brief description
-for each of them:
+Scrivener ships with some basic assertions.
 
 ### 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.
+to `false` or `nil`.
 
 ``` ruby
 def assert(value, error)
@@ -169,10 +150,23 @@ def assert(value, error)
 end
 ```
 
+New assertions can be built upon existing ones. For example, let's
+define an assertion for positive numbers:
+
+```ruby
+def assert_positive(att, error = [att, :not_positive])
+  assert(send(att) > 0, error)
+end
+```
+
+This assertion calls `assert` and passes both the result of evaluating
+`send(att) > 0` and the array with the attribute and the error code.
+All assertions respect this API.
+
 ### assert_present
 
-Checks that the given field is not nil or empty. The error code for this
-assertion is `:not_present`.
+Checks that the given field is not nil or empty. The error code for
+this assertion is `:not_present`.
 
 ### assert_equal
 
@@ -237,6 +231,36 @@ of the word. Valid numbers are: 0.1, .1, 1, 1.1, 3.14159, etc.
 
 The error code for this assertion is `:not_decimal`.
 
+Motivation
+----------
+
+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.
+
+This library exists to satisfy the need for extracting
+[Ohm](http://ohm.keyvalue.org)'s validations for reuse in other
+scenarios.
+
+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 those that come bundled with
+ORMs.
+
+See also
+--------
+
+Scrivener is [Bureaucrat](https://github.com/tizoc/bureaucrat)'s
+little brother. It draws all the inspiration from it and its features
+are a subset of Bureaucrat's.
+
 Installation
 ------------
 

data/lib/scrivener.rb

@@ -1,7 +1,7 @@
 require_relative "scrivener/validations"
 
 class Scrivener
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 
   include Validations
 

data/lib/scrivener/validations.rb

@@ -67,14 +67,14 @@ class Scrivener
     #     end
     #   end
     #
-    def valid?
+    def valid?(*args)
       errors.clear
-      validate
+      validate(*args)
       errors.empty?
     end
 
     # Base validate implementation. Override this method in subclasses.
-    def validate
+    def validate(*args)
     end
 
     # Hash of errors for each attribute in this model.

data/test/scrivener_test.rb

@@ -207,61 +207,97 @@ end
 
 class H < Scrivener
   attr_accessor :a
+  attr_accessor :b
 
   def validate
-    assert_length :a, 3..10
+    assert_equal :a, "foo"
+    assert_equal :b, Integer
   end
 end
 
 scope do
-  test "length validation" do
+  test "equality validation" do
     filter = H.new({})
 
     assert ! filter.valid?
-    assert filter.errors[:a].include?(:not_in_range)
+    assert filter.errors[:a].include?(:not_equal)
+    assert filter.errors[:b].include?(:not_equal)
 
-    filter = H.new(a: "fo")
+    filter = H.new(a: "foo", b: "bar")
     assert ! filter.valid?
-    assert filter.errors[:a].include?(:not_in_range)
 
-    filter = H.new(a: "foofoofoofo")
+    filter = H.new(a: "foo")
     assert ! filter.valid?
-    assert filter.errors[:a].include?(:not_in_range)
+    assert filter.errors[:a].empty?
+    assert filter.errors[:b].include?(:not_equal)
 
-    filter = H.new(a: "foo")
+    filter = H.new(a: "foo", b: 42)
+    filter.valid?
     assert filter.valid?
   end
 end
 
-class I < Scrivener
-  attr_accessor :a
-  attr_accessor :b
+class Scrivener
+  def assert_filter(att, filter, error = nil)
+    filter = filter.new(send(att))
+    
+    unless filter.valid?
+      assert(false, error || [att, filter.errors])
+    end
+  end
+end
 
+class I < Scrivener
+  attr_accessor :name
+  
   def validate
-    assert_equal :a, "foo"
-    assert_equal :b, Fixnum
+    assert_equal :name, "I"
   end
 end
 
+class J < Scrivener
+  attr_accessor :name
+  attr_accessor :i
+
+  def validate
+    assert_equal :name, "J"
+    assert_filter :i, I
+  end
+end
 
 scope do
-  test "equality validation" do
-    filter = I.new({})
+  test "nested filters" do
+    j1 = J.new(name: "J", i: { name: "I" })
+    j2 = J.new(name: "J", i: { name: "H" })
 
-    assert ! filter.valid?
-    assert filter.errors[:a].include?(:not_equal)
-    assert filter.errors[:b].include?(:not_equal)
+    assert_equal true, j1.valid?
+    assert_equal false, j2.valid?
 
-    filter = I.new(a: "foo", b: "bar")
-    assert ! filter.valid?
+    errors = {
+      i: [{ name: [:not_equal] }]
+    }
 
-    filter = I.new(a: "foo")
-    assert ! filter.valid?
-    assert filter.errors[:a].empty?
-    assert filter.errors[:b].include?(:not_equal)
+    assert_equal errors, j2.errors
+  end
+end
 
-    filter = I.new(a: "foo", b: 42)
-    filter.valid?
-    assert filter.valid?
+class K < Scrivener
+  def validate(argument)
+    assert argument == "K", [:k, :not_valid]
+  end
+end
+
+scope do
+  test "passing arguments" do
+    k = K.new({})
+
+    assert_equal true,  k.valid?("K")
+    assert_equal false, k.valid?("L")
+
+    errors = {
+      k: [:not_valid]
+    }
+
+    assert_equal errors, k.errors
   end
 end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: scrivener
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Michel Martens
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-18 00:00:00.000000000 Z
+date: 2018-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cutest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Scrivener removes the validation responsibility from models and acts
@@ -32,10 +32,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gems
-- .gitignore
+- ".gems"
+- ".gitignore"
 - AUTHORS
 - CHANGELOG.md
+- CONTRIBUTING
 - LICENSE
 - README.md
 - lib/scrivener.rb
@@ -53,17 +54,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Validation frontend for models.