aspect 0.0.1 → 0.0.2

data/lib/aspect/verifier/check.rb

@@ -0,0 +1,125 @@
+require "aspect/has_registry" if Kernel.respond_to?(:require)
+
+module Aspect
+  class Verifier
+    # A single verification check.
+    #
+    # To define a new check, you must first register it, then define an attribute for it on the {Aspect::Verifier} class.
+    #
+    # If the check's block returns a falsey value or raises an error, the check is considered failed.
+    # When a truthy value is return, the check has passed.
+    #
+    # @example Basic usage.
+    #   require "aspect/verifier/check"
+    #
+    #   check = Aspect::Verifier::Check[:greater_than_or_equal_to]
+    #
+    #   loop do
+    #     age = gets
+    #
+    #     if check.call(age, 18)
+    #       puts "Welcome!"
+    #
+    #       break
+    #     else
+    #       puts "Must be 18 or older"
+    #     end
+    #   end
+    # @example Defining a new {Verifier} check.
+    #   require "aspect/verifier"
+    #
+    #   Aspect::Verifier::Check.register(:length_of_at_least) { |value, expectation| value.length >= expectation }
+    #   Aspect::Verifier.attribute(:length_of_at_least) { |value| value.to_i }
+    #
+    #   verifier = Aspect::Verifier.new(length_of_at_least: 3)
+    #
+    #   verifier.verify("12") # => { length_of_at_least: 3 } # Invalid
+    #   verifier.verify("123") # => nil                      # Valid
+    class Check
+      extend HasRegistry
+
+      class << self
+        # Get a registered `Check` instance by it's name.
+        #
+        # @param [#to_sym] name
+        # @return [Check]
+        def [](name)
+          registry[name.to_sym]
+        end
+      end
+
+      def initialize(&block)
+        self.block = block
+      end
+
+      # Get or set the block for the check.
+      #
+      # @return [Proc]
+      def block(&block)
+        self.block = block if block_given?
+
+        @block
+      end
+
+      # Set the block for the check.
+      #
+      # @param [Proc] value
+      # @return [Proc]
+      def block=(value)
+        if block_given?
+          raise ArgumentError, "block must have 1 block argument" unless value.arity == 1
+
+          @block = value
+        end
+
+        @block
+      end
+
+      # Call the block.
+      #
+      # @param [Object] value
+      # @return [Boolean]
+      def call(value, expectation)
+        !!@block.call(value, expectation) rescue false
+      end
+
+      register(:equal_to) do |value, expectation|
+        value == expectation
+      end
+
+      register(:presence) do |value|
+        value = value.is_a?(String) ? value.gsub(/\s+/, "") : value
+
+        value.nil? || value.respond_to?(:empty?) && value.empty?
+      end
+
+      register(:integer) { |value| Kernel.Integer(value.to_s) }
+
+      register(:float) { |value| Kernel.Float(value.to_s) }
+
+      register(:greater_than) do |value, expectation|
+        value = Kernel.Float(value.to_s)
+
+        value > expectation
+      end
+
+      register(:greater_than_or_equal_to) do |value, expectation|
+        value = Kernel.Float(value.to_s)
+
+        value >= expectation
+      end
+
+      register(:less_than) do |value, expectation|
+        value = Kernel.Float(value.to_s)
+
+        value < expectation
+      end
+
+      register(:less_than_or_equal_to) do |value, expectation|
+        value = Kernel.Float(value.to_s)
+
+        value <= expectation
+      end
+    end
+  end
+end

data/lib/aspect/verifier.rb

@@ -0,0 +1,212 @@
+if Kernel.respond_to?(:require)
+  require "aspect/has_attributes"
+  require "aspect/verifier/check"
+end
+
+module Aspect
+  # Verify a set of checks on an object.
+  #
+  # The result is a `Hash` where the keys are the check name and the value is the expectation or `nil` when
+  # the object is verified to be valid.
+  #
+  # This allows for it to easily be transformed into messages using {Aspect::MessageTransform}, if needed.
+  #
+  # @example Simple boolean checks.
+  #   require "aspect/verifier"
+  #
+  #   verifier = Aspect::Verifier.new(:presence, :integer)
+  #
+  #   verifier.verify(nil)     # => { presence: true, integer: true } # Invalid
+  #   verifier.verify("")      # => { presence: true, integer: true } # Invalid
+  #   verifier.verify("hello") # => { integer: true }                 # Invalid
+  #   verifier.verify("24")    # => nil                               # Valid
+  # @example Simple checks with arguments.
+  #   require "aspect/verifier"
+  #
+  #   verifier = Aspect::Verifier.new(integer: true, greater_than: 10)
+  #
+  #   verifier.verify(10) # => { greater_than: 10 }                     # Invalid
+  #   verifier.verify("hello") # => { integer: true, greater_than: 10 } # Invalid
+  #   verifier.verify("24") # => nil                                    # Valid
+  # @example Break on fail.
+  #   require "aspect/verifier"
+  #
+  #   verifier = Aspect::Verifier.new(integer: true, greater_than: 10)
+  #
+  #   verifier.verify("hello") # => { integer: true, greater_than: 10 }
+  #   verifier.verify("hello", break_on_fail: true) # => { integer: true }
+  # @example Fake application usage example
+  #   require "aspect/verifier"
+  #
+  #   age_verifier = Aspect::Verifier.new(:integer, greater_than_or_equal_to: 18)
+  #
+  #   loop do
+  #     print "age? "
+  #
+  #     input = gets
+  #     error = age_verifier.verify(input, break_on_fail: true)
+  #
+  #     if error
+  #       puts "  Must give a number." if error[:integer]
+  #       puts "  Must be #{error[:greater_than_or_equal_to]} or older." if error[:greater_than_or_equal_to]
+  #     else
+  #       puts "  Welcome, appropriately-aged user!"
+  #
+  #       break
+  #     end
+  #   end
+  #
+  #   # Command line:
+  #   #   age? foobar
+  #   #     Must give a number.
+  #   #   age? 17
+  #   #     Must be 18 or older.
+  #   #   age? 25
+  #   #     Welcome, appropriately-aged user!
+  # @example Fake application usage example with {Aspect::MessageTransform}
+  #   require "aspect/verifier"
+  #   require "aspect/message_transform"
+  #
+  #   age_verifier = Aspect::Verifier.new(:integer, greater_than_or_equal_to: 18)
+  #   message = Aspect::MessageTransform.new(
+  #     welcome: "Welcome, appropriately-aged user!",
+  #     error: {
+  #       integer: "Must give a number.",
+  #       greater_than_or_equal_to: "Must be %{greater_than_or_equal_to} or older."
+  #     }
+  #   )
+  #
+  #   loop do
+  #     print "age? "
+  #
+  #     input = gets
+  #     error = age_verifier.verify(input, break_on_fail: true)
+  #
+  #     print "  "
+  #     if error
+  #       puts message.to_s(error: error)
+  #     else
+  #       puts message.to_s(:welcome)
+  #
+  #       break
+  #     end
+  #   end
+  #
+  #   # Command line:
+  #   #   age? foobar
+  #   #     Must give a number.
+  #   #   age? 17
+  #   #     Must be 18 or older.
+  #   #   age? 25
+  #   #     Welcome, appropriately-aged user!
+  class Verifier
+    include HasAttributes
+
+    # @example Multiple flags, for boolean checks.
+    #   Aspect::Verifier.new(:presence, :integer)
+    # @example `Array` of flags, for boolean checks.
+    #   Aspect::Verifier.new([:presence, :integer])
+    # @example Passing a `Hash`, for non-boolean checks.
+    #   Aspect::Verifier.new(presence: true, integer: true, greater_than: 10)
+    # @example Mixing both boolean and non-boolean checks.
+    #   Aspect::Verifier.new(:presence, :integer, greater_than: 10)
+    def initialize(*arguments)
+      attributes = {}
+
+      if arguments.length == 1 && arguments[0].respond_to?(:to_h)
+        attributes = arguments[0]
+      else
+        arguments = arguments[0] if arguments.length == 1 && arguments[0].is_a?(Array)
+
+        arguments.collect(&:to_sym).each { |check| attributes[check] = true }
+      end
+
+      update_attributes(attributes)
+    end
+
+    # Validate a value.
+    #
+    # @param value
+    # @param [#to_h] options
+    # @option options [Boolean] :break_on_fail Set to `true` to stop running checks as soon as one fails.
+    # @return [<Symbol, Object>] The result is a `Hash` where the keys are the check name and the value is the expectation or `nil` when the object is verified to be valid.
+    def validate(value, options={})
+      options = { break_on_fail: false }.merge(options.to_h)
+      errors = {}
+
+      Check.registry.each do |check_name, check|
+        check_iv = instance_variable_get("@#{check_name}")
+
+        errors[check_name] = check_iv if check_iv && !check.call(value, check_iv)
+
+        break if options[:break_on_fail]
+      end
+
+      errors
+    end
+
+    # @method presence=
+    # Set whether to check for presence.
+    #
+    # Objects that are `nil`, or respond to `empty?` and return `true`, are considered blank.
+    #
+    # @param [Boolean] value
+    # @return [Boolean]
+
+    # @method presence?
+    # Get whether to check for presence.
+    #
+    # @return [Boolean]
+    attribute(:presence, query: true)
+
+    # @method integer=
+    # Set whether to check for `Integer`.
+    #
+    # The values `123` and `"123"` will both pass, but `123.4` and `"123.4"` will both fail.
+    #
+    # @param [Boolean] value
+    # @return [Boolean]
+
+    # @method integer?
+    # Get whether to check for `Integer`.
+    #
+    # @return [Boolean]
+    attribute(:integer, query: true)
+
+    # @method float=
+    # Set whether to check for `Float`.
+    #
+    # The values `123.4` and `"123.4"` will both pass.
+    #
+    # @param [Boolean] value
+    # @return [Boolean]
+
+    # @method float?
+    # Get whether to check for `Float`.
+    #
+    # @return [Boolean]
+    attribute(:float, query: true)
+
+    # @method equal_to=
+    # Set the object to check equality against.
+    #
+    # @param [nil, Object] value
+    # @return [nil, Object]
+
+    # @method equal_to
+    # Get whether to for equality against a given object.
+    #
+    # @return [Boolean]
+    attribute(:equal_to)
+
+    attribute(:greater_than) { |value| value.to_f }
+
+    attribute(:greater_than_or_equal_to) { |value| value.to_f }
+
+    attribute(:less_than) { |value| value.to_f }
+
+    attribute(:less_than_or_equal_to) { |value| value.to_f }
+
+    # TODO: documentation for equal_to, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to
+  end
+end

data/lib/aspect/version.rb

@@ -0,0 +1,3 @@
+module Aspect
+  VERSION = "0.0.1".freeze
+end

data/lib/aspect.rb

@@ -1,8 +1,7 @@
-require "version"
+require "aspect/version"
 
 # A small collection of useful mixins for plain old Ruby objects.
 module Aspect
-  is_versioned
 end
 
 require "aspect/has_attributes"