valid 0.2.0 → 0.2.1

data/README.md

@@ -0,0 +1,88 @@
+# Validator
+
+Validator is a simple ruby validation class. You don't use it directly inside your classes like just about every other ruby validation class out there. I chose to implement it in this way so I didn't automatically pollute the namespace of the objects I wanted to validate.
+
+This also solves the problem of validating forms very nicely. Frequently you will have a form that represents many different data objects in your system, and you can pre-validate everything before doing any saving.
+
+## Usage
+
+Validator is useful for validating the state of any existing ruby object.
+
+```ruby
+  object = OpenStruct.new(:email => 'foo@bar.com', :password => 'foobar')
+  validator = Validation::Validator.new(object)
+  validator.rule(:email, [:email, :not_empty]) # multiple rules in one line
+  validator.rule(:password, :not_empty) # a single rule on a line
+  validator.rule(:password, :length => {:minimum => 3}) # a rule that takes parameters
+
+  if validator.valid?
+    # save the data somewhere
+  else
+    @errors = validator.errors
+  end
+```
+
+The first paramater can be any message that the object responds to.
+
+### Writing your own rules
+
+If you have a custom rule you need to write, just put it inside the `Validation::Rule` namespace:
+
+```ruby
+  module Validation
+    module Rule
+      class MyCustomRule
+        def error_key
+          :my_custom_rule
+        end
+
+        def valid_value?(value)
+          # Logic for determining the validity of the value
+        end
+
+        def params
+          {}
+        end
+      end
+    end
+  end
+```
+
+A rule class should have the following methods on it:
+
+  - `error_key` a symbol to represent the error. This shows up in the errors hash
+  - `valid_values?(value)` the beef of the rule. This is where you determine if the value is valid or not
+  - `params` the params hash that was passed into the constructor
+
+### Writing self-contained validators
+
+You can also create self-contained validation classes if you don't like the dynamic creation approach:
+
+```ruby
+  require 'validation'
+  require 'validation/rule/not_empty'
+
+  class MyFormValidator < Validation::Validator
+    include Validation
+
+    rule :email, :not_empty
+  end
+```
+
+Now you can use this anywhere in your code:
+
+```ruby
+  form_validator = MyFormValidator.new(OpenStruct.new(params))
+  form_validator.valid?
+```
+
+# Contributing
+
+Have an improvement? Have an awesome rule you want included? Simple!
+
+ 1. Fork the repository
+ 2. Write specs for the change
+ 3. Add your change
+ 4. Submit a pull request
+
+Don't change any version files or gemspec files in your change.

data/lib/validation/rule/email.rb

@@ -1,8 +1,8 @@
 module Validation
   module Rule
-    class Email
+    # Email rule class. This rule was adapted from https://github.com/emmanuel/aequitas/blob/master/lib/aequitas/rule/format/email_address.rb
 
-      # taken from: https://github.com/emmanuel/aequitas/blob/master/lib/aequitas/rule/format/email_address.rb
+    class Email
       EMAIL_ADDRESS = begin
         letter         = 'a-zA-Z'
         digit          = '0-9'
@@ -28,15 +28,17 @@ module Validation
         pattern        = /\A#{addr_spec}\z/u
       end
 
+      # Determines if value is a valid email
       def valid_value?(value)
         !!EMAIL_ADDRESS.match(value)
       end
 
-
+      # The error key for this rule
       def error_key
         :email
       end
 
+      # This rule has no params
       def params
         {}
       end

data/lib/validation/rule/length.rb

@@ -1,14 +1,27 @@
 module Validation
   module Rule
+    # Length rule
     class Length
+      # params can be any of the following:
+      #
+      #  - :minimum - at least this many chars
+      #  - :maximum - at most this many chars
+      #  - :exact - exactly this many chars
+      #
+      #  Example:
+      #
+      #  {:minimum => 3, :maximum => 10}
+      #  {:exact => 10}
       def initialize(params)
         @params = params
       end
 
+      # returns the params given in the constructor
       def params
         @params
       end
 
+      # determines if value is valid according to the constructor params
       def valid_value?(value)
         valid = true
 

data/lib/validation/rule/matches.rb

@@ -1,20 +1,29 @@
 module Validation
   module Rule
+    # Matches rule
     class Matches
       attr_writer :obj
 
+      # This class should take the field to match with in the constructor:
+      #
+      # rule = Validation::Rule::Matches(:password)
+      # rule.obj = OpenStruct.new(:password => 'foo')
+      # rule.valid_value?('foo')
       def initialize(matcher_field)
         @matcher_field = matcher_field
       end
 
+      # The error key for this rule
       def error_key
         :matches
       end
 
+      # Params is the matcher_field given in the constructor
       def params
         @matcher_field
       end
 
+      # Determines if value matches the field given in the constructor
       def valid_value?(value)
         matcher_value = @obj.send(@matcher_field)
         matcher_value == value

data/lib/validation/rule/not_empty.rb

@@ -1,14 +1,18 @@
 module Validation
   module Rule
+    # Rule for not empty
     class NotEmpty
+      # This rule has no params
       def params
         {}
       end
 
+      # Determines if value is empty or not. In this rule, nil is empty
       def valid_value?(value)
         ! (value.nil? || value.empty?)
       end
 
+      # The error key for this field
       def error_key
         :not_empty
       end

data/lib/validation/rule/numeric.rb

@@ -1,14 +1,18 @@
 module Validation
   module Rule
+    # rule for numeric values
     class Numeric
+      # Determines if value is numeric. It can only contain whole numbers
       def valid_value?(value)
        !!/^[0-9]+$/.match(value.to_s)
       end
 
+      # The error key for this rule
       def error_key
         :numeric
       end
 
+      # this rule has no params
       def params
         {}
       end

data/lib/validation/validator.rb

@@ -1,13 +1,24 @@
 module Validation
   module Rules
+    # A hash of rules for this object
     def rules
       @rules ||= {}
     end
 
+    # A hash of errors for this object
     def errors
       @errors ||= {}
     end
 
+    # Define a rule for this object
+    #
+    # The rule parameter can be one of the following:
+    #
+    # * a symbol that matches to a class in the Validation::Rule namespace
+    #  * e.g. rule(:field, :not_empty)
+    # * a hash containing the rule as the key and it's parameters as the values
+    #  * e.g. rule(:field, :length => {:minimum => 3, :maximum => 5})
+    # * an array combining the two previous types
     def rule(field, rule)
       field = field.to_sym
       if rules[field].nil?
@@ -37,6 +48,9 @@ module Validation
       end
     end
 
+    # Determines if this object is valid. When a rule fails for a field,
+    # this will stop processing further rules. In this way, you'll only get
+    # one error per field
     def valid?
       valid = true
 
@@ -59,6 +73,7 @@ module Validation
 
     protected
 
+    # Adds a parameterized rule to this object
     def add_parameterized_rule(field, rule)
       rule.each_pair do |key, value|
         r = Validation::Rule.const_get(camelize(key)).new(value)
@@ -67,12 +82,14 @@ module Validation
       end
     end
 
+    # Adds this validation object to a rule if it can accept it
     def add_object_to_rule(rule)
       if rule.respond_to?(:obj=)
         rule.obj = @obj
       end
     end
 
+    # Converts a symbol to a class name, taken from rails
     def camelize(term)
       string = term.to_s
       string = string.sub(/^[a-z\d]*/) { $&.capitalize }
@@ -80,6 +97,14 @@ module Validation
     end
   end
 
+  # Validator is a simple ruby validation class. You don't use it directly
+  # inside your classes like just about every other ruby validation class out
+  # there. I chose to implement it in this way so I didn't automatically
+  # pollute the namespace of the objects I wanted to validate.
+  #
+  # This also solves the problem of validating forms very nicely. Frequently
+  # you will have a form that represents many different data objects in your
+  # system, and you can pre-validate everything before doing any saving.
   class Validator
     include Validation::Rules
 
@@ -88,9 +113,11 @@ module Validation
     end
   end
 
+  # InvalidKey is raised if a rule is added to a field that doesn't exist
   class InvalidKey < RuntimeError
   end
 
+  # InvalidRule is raised if a rule is added that doesn't exist
   class InvalidRule < RuntimeError
   end
 end

data/lib/validation/version.rb

@@ -1,3 +1,3 @@
 module Validation
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: valid
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -18,15 +18,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/validation.rb
 - lib/validation/rule/email.rb
-- lib/validation/rule/not_empty.rb
+- lib/validation/rule/length.rb
 - lib/validation/rule/matches.rb
+- lib/validation/rule/not_empty.rb
 - lib/validation/rule/numeric.rb
-- lib/validation/rule/length.rb
 - lib/validation/validator.rb
 - lib/validation/version.rb
-homepage: https://github.com/zombor/validation
+- lib/validation.rb
+- README.md
+homepage: https://github.com/zombor/Validator
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -46,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A standalone, generic object validator for ruby