validated_object 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 97d91eb8801c44a0daecab2f6bf5e66c1dc34908
-  data.tar.gz: b53ae1848ed9176217969907ff95d4ceb6f0d06b
+SHA256:
+  metadata.gz: beeec5e7c798a88c65b4f5a492ce3e59505dacf6a0a1f8de4da90ca59c73f873
+  data.tar.gz: 3c18ec02b076c71a020eaf7825fa2014321e09ee43a5490373698bfd8deb3c59
 SHA512:
-  metadata.gz: 7df6a6cacb4a691183fe606828b572a74e08b139d136e8e6826e5fd2ff3f441443b2f4ef451da96a65040075a46ecfee7e123da9f1ed911308c26b586e0482fe
-  data.tar.gz: 86ff719a5c3f23f76f843c049a1071b5ff79e6b20953ca482a3cedf33904adde167553d6efce284e067a0f69bb3841534f1bceb2d29a6bd01ed1dacd77bd8931
+  metadata.gz: 279331de46a2f201ee2eafcb1633ab0ad3b428fa7651276e7754a4e06b6a740f1c473fd14e6296d428d74e3ee39c962bdbcc0e0ebaf6f7bbc7a7fdd393bc56c1
+  data.tar.gz: afe9a3252da50c7bd028ebbfec81729e0ecf71e0c8c5ff1272d31e616593d41e031a87b11602cfb0337dac3c21d0abad1af024007757c3cab462df66c79fa163

data/.travis.yml

@@ -1,5 +1,6 @@
 language: ruby
 rvm:
-  - 2.1
   - 2.2.2
-before_install: gem install bundler -v 1.10.6
+  - 2.3.1
+  - 2.7.1
+before_install: gem install bundler

data/README.md

@@ -1,28 +1,18 @@
-[![Gem Version](https://badge.fury.io/rb/validated_object.svg)](https://badge.fury.io/rb/validated_object) [![Build Status](https://travis-ci.org/dogweather/validated_object.svg?branch=master)](https://travis-ci.org/dogweather/validated_object) [![Code Climate](https://codeclimate.com/github/dogweather/validated_object/badges/gpa.svg)](https://codeclimate.com/github/dogweather/validated_object)
+[![Gem Version](https://badge.fury.io/rb/validated_object.svg)](https://badge.fury.io/rb/validated_object) [![Build Status](https://travis-ci.org/public-law/validated_object.svg?branch=master)](https://travis-ci.org/public-law/validated_object) [![Code Climate](https://codeclimate.com/github/dogweather/validated_object/badges/gpa.svg)](https://codeclimate.com/github/dogweather/validated_object)
 
 # ValidatedObject
 
-Uses
-[ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates)
-to create self-validating Plain Old Ruby objects. I wrote it for helping with CSV data imports into my Rails apps.
-Very readable error messages are also important in that context, to track down parsing errors. This gem provides those too.
+Plain Old Ruby Objects + Rails Validations = **self-checking Ruby objects**.
 
 
-## Installation
+## Goals
 
-Add this line to your application's Gemfile:
+* Very readable error messages
+* Clean, minimal syntax
 
-```ruby
-gem 'validated_object'
-```
+This is a small layer around
+[ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates). (About 18 lines of code.) So if you know how to use Rails Validations, you're good to go. I wrote this to help with CSV data imports and [website microdata generation](https://github.com/dogweather/schema-dot-org).
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install validated_object
 
 ## Usage
 
@@ -33,47 +23,119 @@ All of the [ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveM
 
 ```ruby
 class Dog < ValidatedObject::Base
-  attr_accessor :name, :birthday
+  # Plain old Ruby
+  attr_accessor :name, :birthday  # attr_reader is supported as well for read-only attributes
 
+  # Plain old Rails
   validates :name, presence: true
-  validates :birthday, type: Date, allow_nil: true
+  
+  # A new type-validation if you'd like to use it
+  validates :birthday, type: Date, allow_nil: true  # Strongly typed but optional
 end
 ```
 
+The included `TypeValidator` is what enables `type: Date`, above. All classes can be checked, as well as a pseudo-class `Boolean`. E.g.:
+
+```ruby
+#...
+validates :premium_membership, type: Boolean
+#...
+```
+
 ### Instantiating and automatically validating
 
 ```ruby
-# The dog1 instance validates itself at the end of instantiation.
-# Here, it succeeds and so doesn't raise an exception.
-dog1 = Dog.new do |d|
-  d.name = 'Spot'
-end
+# This Dog instance validates itself at the end of instantiation.
+spot = Dog.new(name: 'Spot')
+```
 
-# We can also explicitly test for validity
-dog1.valid?  # => true
+```ruby
+# We can also explicitly test for validity because all of
+# ActiveModel::Validations is available.
+spot.valid?  # => true
 
-dog1.birthday = Date.new(2015, 1, 23)
-dog1.valid?  # => true
+spot.birthday = Date.new(2015, 1, 23)
+spot.valid?  # => true
 ```
 
-### Making an instance _invalid_
+### Good error messages
+
+Any of the standard Validations methods can be
+used to test an instance, plus the custom `check_validations!` convenience method:
 
 ```ruby
-dog1.birthday = '2015-01-23'
-dog1.valid?  # => false
-dog1.check_validations!  # => ArgumentError: Birthday is class String, not Date
+spot.birthday = '2015-01-23'
+spot.valid?  # => false
+spot.check_validations!  # => ArgumentError: Birthday is a String, not a Date
 ```
 
+Note the clear, explicit error message. These are great when reading a log
+file following a data import. It describes all the invalid conditions. Let's 
+test it by making another attribute invalid:
+
+```ruby
+spot.name = nil
+spot.check_validations!  # => ArgumentError: Name can't be blank; Birthday is a String, not a Date
+```
+
+
+### Use in parsing data
+
+I often use a validated object in a loop to import data, e.g.:
+
+```ruby
+# Import a CSV file of dogs
+dogs = []
+csv.next_row do |row|
+  begin
+    dogs << Dog.new(name: row.name)
+  rescue ArgumentError => e
+    logger.warn(e)
+  end
+end
+```
+
+The result is that `dogs` is an array of guaranteed valid Dog objects. And the
+error log lists unparseable rows with good info for tracking down problems in
+the data.
+
+### Use in code generation
+
+My [Schema.org microdata generation gem](https://github.com/dogweather/schema-dot-org) uses ValidatedObjects to recursively create well formed HTML / JSON-LD. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'validated_object'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install validated_object
+
+
 
 ## Development
 
-(TODO: Verify these instructions.) After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+(TODO: Verify these instructions.) After checking out the repo, run `bin/setup`
+to install dependencies. Then, run `rake spec` to run the tests. You can also
+run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/dogweather/validated_object.
+Bug reports and pull requests are welcome on GitHub.
 
 
 ## License

data/lib/validated_object.rb

@@ -1,11 +1,15 @@
+# typed: true
+# frozen_string_literal: true
+
 require 'active_model'
+require 'sorbet-runtime'
 require 'validated_object/version'
 
 module ValidatedObject
   # @abstract Subclass and add `attr_accessor` and validations
   #   to create custom validating objects.
   #
-  # Uses [ActiveModel::Validations](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates)
+  # Uses {http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates ActiveModel::Validations}
   # to create self-validating Plain Old Ruby objects. This is especially
   # useful when importing data from one system into another. This class also
   # creates very readable error messages.
@@ -21,9 +25,7 @@ module ValidatedObject
   # @example Instantiating and automatically validating
   #   # The dog1 instance validates itself at the end of instantiation.
   #   # Here, it succeeds and so doesn't raise an exception.
-  #   dog1 = Dog.new do |d|
-  #     d.name = 'Spot'
-  #   end
+  #   dog1 = Dog.new name: 'Spot'
   #
   #   # We can also explicitly test for validity
   #   dog1.valid?  # => true
@@ -41,28 +43,41 @@ module ValidatedObject
   # @see http://www.rubyinside.com/rails-3-0s-activemodel-how-to-give-ruby-classes-some-activerecord-magic-2937.html Rails 3.0′s ActiveModel: How To Give Ruby Classes Some ActiveRecord Magic, Peter Cooper
   class Base
     include ActiveModel::Validations
+    extend T::Sig
+
+    SymbolHash = T.type_alias { T::Hash[Symbol, T.untyped] }
+
+    EMPTY_HASH = T.let({}.freeze, SymbolHash)
 
-    # Implements a pseudo-boolean class.
+    # A private class definition, not intended to
+    # be used directly. Implements a pseudo-boolean class
+    # enabling validations like this:
+    #
+    #   validates :enabled, type: Boolean
     class Boolean
     end
 
     # Instantiate and validate a new object.
-    #
-    # @yieldparam [ValidatedObject] new_object the yielded new object
-    #   for configuration.
+    # @example
+    #   maru = Dog.new(birthday: Date.today, name: 'Maru')
     #
     # @raise [ArgumentError] if the object is not valid at the
-    #   end of initialization.
-    def initialize
-      yield(self)
+    #   end of initialization or `attributes` is not a Hash.
+    sig { params(attributes: SymbolHash).returns(ValidatedObject::Base)}
+    def initialize(attributes = EMPTY_HASH)
+      set_instance_variables from_hash: attributes
       check_validations!
       self
     end
 
     # Run any validations and raise an error if invalid.
+    #
     # @raise [ArgumentError] if any validations fail.
+    # @return [ValidatedObject::Base] the receiver
+    sig {returns(ValidatedObject::Base)}
     def check_validations!
       raise ArgumentError, errors.full_messages.join('; ') if invalid?
+
       self
     end
 
@@ -70,25 +85,79 @@ module ValidatedObject
     # or a subclass. It supports a pseudo-boolean class for convenient
     # validation. (Ruby doesn't have a built-in Boolean.)
     #
+    # Automatically used in a `type` validation:
+    #
     # @example Ensure that weight is a number
     #   class Dog < ValidatedObject::Base
     #     attr_accessor :weight, :neutered
-    #     validates :weight, type: Numeric
-    #     validates :neutered, type: Boolean
+    #     validates :weight, type: Numeric  # Typed and required
+    #     validates :neutered, type: Boolean, allow_nil: true  # Typed but optional
     #   end
     class TypeValidator < ActiveModel::EachValidator
+      extend T::Sig
+
       # @return [nil]
+      sig do
+        params(
+          record: T.untyped,
+          attribute: T.untyped,
+          value: T.untyped
+        )
+          .void
+      end
       def validate_each(record, attribute, value)
-        expected_class = options[:with]
+        validation_options = T.let(options, SymbolHash)
+
+        expected_class = validation_options[:with]
+
+        return if pseudo_boolean?(expected_class, value) ||
+                  expected_class?(expected_class, value)
+
+        save_error(record, attribute, value, validation_options)
+      end
+
+      private
+
+      sig {params(expected_class: T.untyped, value: T.untyped).returns(T.untyped)}
+      def pseudo_boolean?(expected_class, value)
+        expected_class == Boolean && boolean?(value)
+      end
+
+      sig {params(expected_class: T.untyped, value: T.untyped).returns(T.untyped)}
+      def expected_class?(expected_class, value)
+        value.is_a?(expected_class)
+      end
+
+      sig {params(value: T.untyped).returns(T.untyped)}
+      def boolean?(value)
+        value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      end
+
+      sig do
+        params(
+          record: T.untyped,
+          attribute: T.untyped,
+          value: T.untyped,
+          validation_options: SymbolHash
+        )
+          .void
+      end
+      def save_error(record, attribute, value, validation_options)
+        record.errors.add attribute,
+                          validation_options[:message] || "is a #{value.class}, not a #{validation_options[:with]}"
+      end
+    end
+
+    private
 
-        if expected_class == Boolean
-          return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
-        else
-          return if value.is_a?(expected_class)
-        end
+    sig {params(from_hash: SymbolHash).void}
+    def set_instance_variables(from_hash:)
+      from_hash.each do |variable_name, variable_value|
+        # Test for the attribute reader
+        send variable_name.to_sym
 
-        msg = options[:message] || "is class #{value.class}, not #{expected_class}"
-        record.errors.add attribute, msg
+        # Set value in a way that succeeds even if attr is read-only
+        instance_variable_set "@#{variable_name}".to_sym, variable_value
       end
     end
   end

data/lib/validated_object/version.rb

@@ -1,3 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
 module ValidatedObject
-  VERSION = '1.1.0'.freeze
+  VERSION = '2.1.0'
 end

data/script/demo.rb

@@ -0,0 +1,18 @@
+# typed: ignore
+require 'date'
+require 'validated_object'
+
+class Dog < ValidatedObject::Base
+  attr_reader :name, :birthday
+  validates :name, presence: true
+  validates :birthday, type: Date, allow_nil: true
+end
+
+phoebe = Dog.new(name: 'Phoebe')
+puts phoebe.inspect
+
+maru = Dog.new(birthday: Date.today, name: 'Maru')
+puts maru.inspect
+
+hiro = Dog.new(birthday: 'today')
+puts hiro.inspect

data/sorbet/config

@@ -0,0 +1,2 @@
+--dir
+.

data/sorbet/rbi/gems/activemodel.rbi

@@ -0,0 +1,210 @@
+# This file is autogenerated. Do not edit it by hand. Regenerate it with:
+#   srb rbi gems
+
+# typed: ignore
+#
+# If you would like to make changes to this file, great! Please create the gem's shim here:
+#
+#   https://github.com/sorbet/sorbet-typed/new/master?filename=lib/activemodel/all/activemodel.rbi
+#
+# activemodel-6.0.3.2
+
+module ActiveModel
+  def self.eager_load!; end
+  def self.gem_version; end
+  def self.version; end
+  extend ActiveSupport::Autoload
+end
+module ActiveModel::VERSION
+end
+module ActiveModel::Serializers
+  extend ActiveSupport::Autoload
+end
+module ActiveModel::Validations
+  def errors; end
+  def initialize_dup(other); end
+  def invalid?(context = nil); end
+  def raise_validation_error; end
+  def read_attribute_for_validation(*arg0); end
+  def run_validations!; end
+  def valid?(context = nil); end
+  def validate!(context = nil); end
+  def validate(context = nil); end
+  def validates_with(*args, &block); end
+  extend ActiveSupport::Concern
+end
+module ActiveModel::Validations::ClassMethods
+  def _parse_validates_options(options); end
+  def _validates_default_keys; end
+  def attribute_method?(attribute); end
+  def clear_validators!; end
+  def inherited(base); end
+  def validate(*args, &block); end
+  def validates!(*attributes); end
+  def validates(*attributes); end
+  def validates_each(*attr_names, &block); end
+  def validates_with(*args, &block); end
+  def validators; end
+  def validators_on(*attributes); end
+end
+module ActiveModel::Validations::Clusivity
+  def check_validity!; end
+  def delimiter; end
+  def include?(record, value); end
+  def inclusion_method(enumerable); end
+end
+class ActiveModel::Validator
+  def initialize(options = nil); end
+  def kind; end
+  def options; end
+  def self.kind; end
+  def validate(record); end
+end
+class ActiveModel::EachValidator < ActiveModel::Validator
+  def attributes; end
+  def check_validity!; end
+  def initialize(options); end
+  def validate(record); end
+  def validate_each(record, attribute, value); end
+end
+class ActiveModel::BlockValidator < ActiveModel::EachValidator
+  def initialize(options, &block); end
+  def validate_each(record, attribute, value); end
+end
+class ActiveModel::Validations::InclusionValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value); end
+  include ActiveModel::Validations::Clusivity
+end
+module ActiveModel::Validations::HelperMethods
+  def _merge_attributes(attr_names); end
+  def validates_absence_of(*attr_names); end
+  def validates_acceptance_of(*attr_names); end
+  def validates_confirmation_of(*attr_names); end
+  def validates_exclusion_of(*attr_names); end
+  def validates_format_of(*attr_names); end
+  def validates_inclusion_of(*attr_names); end
+  def validates_length_of(*attr_names); end
+  def validates_numericality_of(*attr_names); end
+  def validates_presence_of(*attr_names); end
+  def validates_size_of(*attr_names); end
+end
+class ActiveModel::Validations::AbsenceValidator < ActiveModel::EachValidator
+  def validate_each(record, attr_name, value); end
+end
+class ActiveModel::Validations::NumericalityValidator < ActiveModel::EachValidator
+  def allow_only_integer?(record); end
+  def check_validity!; end
+  def filtered_options(value); end
+  def is_hexadecimal_literal?(raw_value); end
+  def is_integer?(raw_value); end
+  def is_number?(raw_value); end
+  def parse_as_number(raw_value); end
+  def record_attribute_changed_in_place?(record, attr_name); end
+  def validate_each(record, attr_name, value); end
+end
+module ActiveModel::Validations::Callbacks
+  def run_validations!; end
+  extend ActiveSupport::Concern
+end
+module ActiveModel::Validations::Callbacks::ClassMethods
+  def after_validation(*args, &block); end
+  def before_validation(*args, &block); end
+end
+class ActiveModel::Validations::ExclusionValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value); end
+  include ActiveModel::Validations::Clusivity
+end
+class ActiveModel::Validations::ConfirmationValidator < ActiveModel::EachValidator
+  def confirmation_value_equal?(record, attribute, value, confirmed); end
+  def initialize(options); end
+  def setup!(klass); end
+  def validate_each(record, attribute, value); end
+end
+class ActiveModel::Validations::FormatValidator < ActiveModel::EachValidator
+  def check_options_validity(name); end
+  def check_validity!; end
+  def option_call(record, name); end
+  def record_error(record, attribute, name, value); end
+  def regexp_using_multiline_anchors?(regexp); end
+  def validate_each(record, attribute, value); end
+end
+class ActiveModel::Validations::PresenceValidator < ActiveModel::EachValidator
+  def validate_each(record, attr_name, value); end
+end
+class ActiveModel::Validations::LengthValidator < ActiveModel::EachValidator
+  def check_validity!; end
+  def initialize(options); end
+  def skip_nil_check?(key); end
+  def validate_each(record, attribute, value); end
+end
+class ActiveModel::Validations::AcceptanceValidator < ActiveModel::EachValidator
+  def acceptable_option?(value); end
+  def initialize(options); end
+  def setup!(klass); end
+  def validate_each(record, attribute, value); end
+end
+class ActiveModel::Validations::AcceptanceValidator::LazilyDefineAttributes < Module
+  def ==(other); end
+  def attributes; end
+  def define_on(klass); end
+  def included(klass); end
+  def initialize(attributes); end
+  def matches?(method_name); end
+end
+class ActiveModel::Validations::WithValidator < ActiveModel::EachValidator
+  def validate_each(record, attr, val); end
+end
+class ActiveModel::ValidationError < StandardError
+  def initialize(model); end
+  def model; end
+end
+class ActiveModel::Name
+  def !~(**, &&); end
+  def <=>(**, &&); end
+  def ==(arg); end
+  def ===(arg); end
+  def =~(**, &&); end
+  def _singularize(string); end
+  def as_json(**, &&); end
+  def cache_key; end
+  def collection; end
+  def element; end
+  def eql?(**, &&); end
+  def human(options = nil); end
+  def i18n_key; end
+  def initialize(klass, namespace = nil, name = nil); end
+  def match?(**, &&); end
+  def name; end
+  def param_key; end
+  def plural; end
+  def route_key; end
+  def singular; end
+  def singular_route_key; end
+  def to_s(**, &&); end
+  def to_str(**, &&); end
+  include Comparable
+end
+module ActiveModel::Naming
+  def model_name; end
+  def self.extended(base); end
+  def self.model_name_from_record_or_class(record_or_class); end
+  def self.param_key(record_or_class); end
+  def self.plural(record_or_class); end
+  def self.route_key(record_or_class); end
+  def self.singular(record_or_class); end
+  def self.singular_route_key(record_or_class); end
+  def self.uncountable?(record_or_class); end
+end
+module ActiveModel::Callbacks
+  def _define_after_model_callback(klass, callback); end
+  def _define_around_model_callback(klass, callback); end
+  def _define_before_model_callback(klass, callback); end
+  def define_model_callbacks(*callbacks); end
+  def self.extended(base); end
+end
+module ActiveModel::Translation
+  def human_attribute_name(attribute, options = nil); end
+  def i18n_scope; end
+  def lookup_ancestors; end
+  include ActiveModel::Naming
+end