bhm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: deba451efeb03dbbbc84340918f311129808c08401b98cdbe9e2b309cae64b3d
+  data.tar.gz: 8aca882d42fedbc4fc01f0317aea620eeadbd6b63034de4e197a5855bd774c42
+SHA512:
+  metadata.gz: 9b643a56b5e6689e4013de3a035609b222dc895cd416634be0bf889e15d0aca574cc66ccdd4f8c93fdb98a0590ae7c38142fddcf6a8a01e8dcb3ff0b7da4c71f
+  data.tar.gz: b9c2c24d3e2147eb0fd67534fce82c74675fc1bc639ed939666d88ca4b8faa08ee54a6642fe17c99d0bdef92cad5ccd1659276669534c75e1cb95c75dc9a817d

data/README.md

@@ -0,0 +1,40 @@
+# Hsah
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hsah`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hsah'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install hsah
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hsah.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/examples/meta.rb

@@ -0,0 +1,10 @@
+# Example of a shared schema, `meta`, to be re-used in multiple places
+require "bhm"
+
+module Meta
+  include Bhm::Validation
+  validator :created_at, DateTime
+  validator :updated_at, DateTime
+
+  validator :uuid, ->(value) { value.match?(/\A(\{)?([a-fA-F0-9]{4}-?){8}(?(1)\}|)\z/) }
+end

data/examples/team.rb

@@ -0,0 +1,21 @@
+# Example of validating a team resource, using the validation helpers
+require "bhm"
+require "date"
+require_relative "meta"
+require_relative "user"
+
+module Team
+  include Bhm::Validation
+  validator :name, String
+  validator :rank, Integer
+  validator :users, ->(value) { value.is_a?(Array) && value.each { |user_hash| user_hash.extend(User).validate! } }
+
+  module Budget
+    include Bhm::Validation
+
+    validator :amount, Integer
+    validator :meta, ->(value) { value.extend(Meta).validate! }
+  end
+
+  validator :meta, ->(value) { value.extend(Meta).validate! }
+end

data/examples/user.rb

@@ -0,0 +1,21 @@
+# Example of validating a user resource, using scaffolding
+require "bhm"
+require_relative "meta"
+
+module User
+  @name = String
+  @email = ->(value) { value.is_a?(String) && value.match?(/[^\s]@[^\s]/) }
+  @tos_acceptance = TrueClass
+  module Address
+    @street = String
+  end
+
+  module Profile
+    @introduction = ->(value) { value.is_a?(String) && value.length < 255 }
+    @hobbies = Array
+  end
+
+  @meta = ->(value) { value.extend(Meta).validate! }
+end
+
+User.include(Bhm::Scaffold)

data/lib/bhm.rb

@@ -0,0 +1,5 @@
+require_relative "bhm/errors"
+require_relative "bhm/utils"
+require_relative "bhm/scaffold"
+require_relative "bhm/validation"
+require_relative "bhm/version"

data/lib/bhm/errors.rb

@@ -0,0 +1,90 @@
+module Bhm
+  module Errors
+    module Chainable
+      # Helper for re-raising easily
+      def self.included(klass)
+        # Add new class method, without needing to prepend the class
+        klass.define_singleton_method(:raise!) do |*args, **kwargs|
+          fail new(args[0], **kwargs)
+        end
+      end
+
+      # Retrieve the chain of errors up to the most recent included module
+      # Eg.
+      # hash.extend(Document)
+      # error_chain == [Document, Components, Schemas, Primitive]
+      #
+      # hash.extend(Document::Components)
+      # error_chain == [Components, Schemas, Primitive]
+      def error_chain
+        @error_chain ||= -> {
+          out, parent = [self], cause
+          loop do
+            break out if parent.nil?
+            out.push(parent)
+            parent = parent.cause
+          end
+        }.call
+      end
+    end
+
+    # Pre-validation check indicates this should not be validated
+    class WontValidate < ArgumentError
+      include Chainable
+      attr_accessor :receiver
+      def initialize(message = nil, receiver:)
+        message ||= "A guard raised; Will not attempt validation for this hash"
+        self.receiver = receiver
+        super(message)
+      end
+    end
+
+    # Generic error -- the hash could not be fully validated
+    class InvalidHash < KeyError
+      include Chainable
+      def initialize(message = nil, receiver:, key:)
+        message ||= "the hash could not be fully validated"
+        super(message, receiver: receiver, key: key)
+      end
+
+      # From the invalid hash, get a period-joined string of keys leading to the invalid key or value
+      def ref
+        error_chain.map(&:key).join(".")
+      end
+
+      # TODO: Import absolute_ref
+    end
+
+    # The key does not adhere to the asserted key typing
+    class InvalidKeyType < InvalidHash
+      def initialize(message = nil, receiver:, key:, type:)
+        message ||= "all keys must be #{type} (got #{key.inspect})"
+        super(message, receiver: receiver, key: key)
+      end
+    end
+
+    # The key does not adhere to the asserted key casing
+    class InvalidKeyCasing < InvalidHash
+      def initialize(message = nil, receiver:, key:, casing:)
+        message ||= "the key #{key.inspect} is not in #{casing} casing"
+        super(message, receiver: receiver, key: key)
+      end
+    end
+
+    # A required value was not found
+    class MissingKey < InvalidHash
+      def initialize(message = nil, receiver:, key:)
+        message ||= "could not find key: #{key.inspect}"
+        super(message, receiver: receiver, key: key)
+      end
+    end
+
+    # The value was found, but calling `validate!` on it raised a validation error
+    class InvalidValue < InvalidHash
+      def initialize(message = nil, receiver:, key:)
+        message ||= "a value exists for key #{key.inspect} -- but it did not pass validation"
+        super(message, receiver: receiver, key: key)
+      end
+    end
+  end
+end

data/lib/bhm/scaffold.rb

@@ -0,0 +1,47 @@
+require_relative "utils"
+require_relative "validation"
+
+module Bhm
+  # Quick way to start including hash validation. May be the only module some projects need :)
+  module Scaffold
+    # Upon being included do the following:
+    # - define any validators based on the declared instance_variables
+    # (then)
+    # - fetch all declared modules
+    ## And recursively do the following:
+    ## - extend it with Bhm::Validation
+    ## - define a new validator, using the module name as a key
+    ## (a nested module assumes it's a nested hash)
+    #### @mod_name = ->(hash) { hash.extend(ModName).validate! }
+    def self.included(klass)
+      # Include the validation suite in self
+      klass.include(Validation)
+
+      # Find all modules (we are assuming these are hashes)
+      klass.constants.each do |sym|
+        const = const_get([klass, sym].join("::"))
+        next unless const.is_a?(Module)
+
+        # Then, define the validator for the current class (calls validate! on the hash)
+        # default_key_case may return `nil` if no global config is set.
+        casing_transform = klass.default_key_case || :lower_snake
+        key = Utils.transform_module_casing(sym, casing_transform, klass.default_key_type)
+
+        klass.validator key, ->(hash) { hash.extend(const).validate! }
+
+        # Lastly, recursively include the scaffolding suite in these child modules
+        const.include(Scaffold)
+      end
+    end
+  end
+end
+
+# Usage:
+# 1. Define a group of nested modules:
+# module Apex
+#   module Hash1
+#     module NestedHash
+#       # IF this nested hash is the bottommost "leaf", we will not traverse any further.
+#       # Defining instance variables is still respected
+#   module Hash2
+#     module NestedHash

data/lib/bhm/utils.rb

@@ -0,0 +1,61 @@
+module Bhm
+  module Utils
+    module_function
+
+    # Transform a stringified module to an accessible hash key
+    # Assume we want symbols by default
+    def transform_module_casing(module_name, key_casing, key_type)
+      transformed_module = case key_casing
+      when :lower_snake
+        module_name.to_s.gsub(/[A-Z]/) { |mtch| "_" + mtch.downcase }.sub(/^_/, "")
+      when :lowerCamel
+        module_name.to_s.sub(/^./) { |first_char| first_char.downcase }
+      when :UpperCamel
+        module_name.to_s
+      when :SCREAMING_SNAKE
+        module_name.to_s.gsub(/[A-Z]/) { |mtch| "_" + mtch }.upcase.sub(/^_/, "")
+      else
+        fail ArgumentError, "invalid casing provided: #{key_casing.inspect}"
+      end
+
+      # Coerce into symbols if key_type was explicitly passed as `nil`
+      key_type ||= :symbols
+      transformed_module = transformed_module.to_sym if key_type == :symbols
+      transformed_module
+    end
+
+    # Take a hash which includes Bhm::Validation & traverse upward nested module which also includes Validation
+    def traverse_ancestors(hash)
+      all = hash.singleton_class.included_modules.select { |mod| mod.include? Validation }
+      current = all.first
+      traversed_ancestors = []
+
+      while current.include?(Validation)
+        as_ary = current.to_s.split("::")
+        # Truncating the final ::(string), then rejoin
+
+        # Now that we have the module in question, transform the case using the module's method, if it has it defined
+        accessed_key = as_ary[-1]
+
+        # HACK: make an instance which extends the current module to use its #default_key values
+        transformed_key = -> do
+          hack = {}.extend(current)
+          key_casing = hack.default_key_case
+          key_type = hack.default_key_type
+
+          transform_module_casing(accessed_key, key_casing, key_type)
+        end.call
+
+        traversed_ancestors << transformed_key
+
+        last = current
+        current = Object.const_get(as_ary[0, (as_ary.length - 1)].join("::"))
+      end
+
+      # Array
+      # idx 0 is an array of the module names as formatted strings
+      # idx 1 is the apex, highest "entry" module
+      [traversed_ancestors, last]
+    end
+  end
+end

data/lib/bhm/validation.rb

@@ -0,0 +1,194 @@
+require_relative "errors"
+require_relative "utils"
+
+module Bhm
+  # The meat of the library
+  module Validation
+    def self.included(receiver)
+      # NOTE: Methods **MUST** be in the included block -- otherwise we pollute the module constants with
+      # any "initializer" module we include/extend
+      receiver.singleton_class.class_eval do
+        def config(**cfg)
+          pending_case, pending_keys = cfg.values_at(:default_key_case, :default_key_type)
+
+          case_options = [:lower_snake, :lowerCamel, :UpperCamel, :SCREAMING_SNAKE, nil]
+          fail ArgumentError, "casing must be one of #{case_options.inspect}" unless case_options.include? pending_case
+          @___default_key_case = pending_case
+
+          key_options = [:symbols, :strings, nil]
+          fail ArgumentError, "keys must be one of #{key_options.inspect}" unless key_options.include? pending_keys
+          @___default_key_type = pending_keys
+        end
+
+        # Concise API for setting both case assertion & key conformity simultaneously
+        def keys(arg)
+          key_option = arg.is_a?(String) ? :strings : :symbols
+          config(
+            default_key_type: key_option,
+            default_key_case: arg.to_sym
+          )
+        end
+
+        def default_key_case
+          # @___default_key_case ||= TODO_GLOBAL_CONFIG
+          @___default_key_case
+        end
+
+        def default_key_type
+          # @___default_key_type ||= TODO_GLOBAL_CONFIG
+          @___default_key_type
+        end
+
+        # TODO: `nullable` method
+
+        def guard(handler)
+          guards << handler
+        end
+
+        def guards
+          @___guards ||= []
+        end
+
+        #### 4 ways to define a validator:
+        ## Explicit key+proc:
+        # validator "KEY", ->(){}
+        # @KEY = "KEY", ->(){}
+        #
+        ## Explicit key+typecheck
+        # validator "KEY", String
+        # @KEY = "KEY", String
+        #
+        ## Implicit proc
+        # @___default_key_type = :strings
+        # @KEY = ->(){}
+        #
+        ## Implicit typecheck
+        # @___default_key_type = :strings
+        # @KEY = String
+        def validators
+          instance_variables.each_with_object({}) do |ivar, out|
+            # Skip our internals
+            next if ivar.to_s.start_with? "@___"
+
+            arg = instance_variable_get(ivar)
+            final_key, ambiguous_arg = case arg
+            when Array
+              # Assume the array idx0 is the key, idx1 is the handler or a Ruby class
+              arg.slice(0, 2)
+            else
+              # Assume some implicit flow. Use ivar name as key value
+              subbed = ivar.to_s.gsub(/^@/, "")
+              formatted_key = case default_key_type
+              when :strings then subbed
+              when :symbols then subbed.to_sym
+              else
+                # In the event no default settings are provided, default to sym assertion
+                subbed.to_sym
+              end
+
+              # Re-send the original arg
+              [formatted_key, arg]
+            end
+
+            # Lastly, check the ambiguous arg & set the finalized handler
+            out[final_key] = case ambiguous_arg
+            when Proc then ambiguous_arg # It is a dedicated proc handler
+            when Class then ->(fetched_value) { fetched_value.is_a?(ambiguous_arg) } # They want us to typecheck
+            else
+              # Assume bad user input
+              fail ArgumentError, "could not implement validator (supplied arg: #{ambiguous_arg.inspect}"
+            end
+          end
+        end
+
+        # Explicit API to set a key & handler, ignoring case/key-type config
+        def validator(key, handler)
+          # Use our array handling, to specifically bypass key checks
+          instance_variable_set("@#{key}", [key, handler])
+        end
+      end
+
+      # Define getters for each of these methods
+      %i[validators guards default_key_case default_key_type].each do |method_name|
+        define_method(method_name) do
+          singleton_class.included_modules.find { |mod|
+            mod.include? Validation
+          }.public_send(method_name)
+        end
+      end
+    end
+
+    # TODO: Assert the keys hash conform to a casing stantard
+    def validate_keys!
+      if default_key_type
+        klass = case default_key_type
+        when :symbols then Symbol
+        when :strings then String
+        end
+
+        keys.each do |string_or_sym|
+          Errors::InvalidKeyType.raise!(receiver: self, key: string_or_sym, type: default_key_type) unless string_or_sym.is_a? klass
+        end
+      end
+
+      case default_key_case
+      when :lower_snake
+        # TODO
+      when :lowerCamel
+        # TODO
+      when :UpperCamel
+        # TODO
+      when :SCREAMING_SNAKE
+        # TODO
+      end
+    end
+
+    def validate!
+      validate_keys!
+
+      run_guards!
+
+      # Run validation
+      run_validators!
+
+      # If we reach this line, the schema is valid.
+      self
+    end
+
+    def errors
+      @errors ||= []
+    end
+
+    def valid?
+      @errors = []
+      return true if validate!
+
+      # Only rescue lib-defined classes here. Let all other errors surface
+    rescue Errors::InvalidHash, Errors::WontValidate => e
+      @errors = e.error_chain
+      false
+    end
+
+    private
+
+    def run_validators!
+      validators.each do |key, handler|
+        hash = fetch(key)
+
+        result = handler.call(hash)
+        Errors::InvalidValue.raise!(key: key, receiver: self) unless result
+      rescue KeyError
+        mod = (singleton_class.included_modules.select { |mod| mod.include? Validation }).first
+        Errors::InvalidHash.raise!("could not validate: #{mod}", key: key, receiver: self)
+      end
+    end
+
+    def run_guards!
+      guards.each do |handler|
+        result = handler.call(self)
+
+        Errors::WontValidate.raise!(receiver: self) unless result
+      end
+    end
+  end
+end

data/lib/bhm/version.rb

@@ -0,0 +1,3 @@
+module Bhm
+  VERSION = "0.1.0".freeze
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: bhm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Trevor James
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-09-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: amazing_print
+  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'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: standard
+  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: 
+email: trevor@osrs-stat.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- examples/meta.rb
+- examples/team.rb
+- examples/user.rb
+- lib/bhm.rb
+- lib/bhm/errors.rb
+- lib/bhm/scaffold.rb
+- lib/bhm/utils.rb
+- lib/bhm/validation.rb
+- lib/bhm/version.rb
+homepage: https://github.com/fire-pls/bhm
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.4
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Modular hash validation
+test_files: []