jsi 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e03bfff724257e11f9001d2845666d25f317b3761d5b62dc39816ad3fa3c28e
-  data.tar.gz: d315e1424f2bd8eef67a2ad562c7668b6b8582b9bda25c8ba74cc892b1a9b1e4
+  metadata.gz: '0659cc34b129717ffb69089f1d3a25ba3c3ec5364d49a6c0cc93dd5979ac7638'
+  data.tar.gz: 5b0298a9843a61e6f5693d46dd6d86021d53767638e1f3f84e23fff4b167276e
 SHA512:
-  metadata.gz: e62b9bf206486a77a3d1202388ddcd0fb29d326abf5a0b19fd6e74454ae05a494e4f88dcddaa42c7fc0b8b071877a406f213cde4589b21383778d9c713aa91b7
-  data.tar.gz: a07b6d591b0cd8bfe28d5923018931f4ee8fc3dba393b240dbefd74a26e813e0a759ecab482be4da7a7e2fa3d4c74a0542c98fcef35364a1a07684e0dc24d2f0
+  metadata.gz: 8b68dcbb479756b8fa58a43f7a8e83accda02a8b0aa87617dabb6623a4b1a8aa05f94cb03de601cf7bf88c943ce62e42963b533ef125729847159e3b775f32c2
+  data.tar.gz: 49997a70900b9d250e4888bcf3e5470e68b116c3a558651db9e5551f73027ea4abd18b0585d23f5201b15e8d80f1d72b46488d1870ac530d40368c7577d3b048

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+# v0.7.0
+
+- JSI::Base instances include Array/Hash-like modules on subclasses rather than extending each instance; are only Enumerable when appropriate instead of always
+- PathedHashNode -> Base::HashNode, PathedArrayNode -> Base::ArrayNode, PathedNode merged with Base
+- change application of conditional schemas to instances which do not validate, always apply them
+- fix nomenclature: child is immediately below parent; descendent is anywhere at/below an ancestor
+  - deprecate previous misnamed methods
+- Base#jsi_descendent_node, Base#jsi_ancestor_nodes
+- add Schema#describes_schema!, deprecate Schema#jsi_schema_instance_modules
+- Schema#keyword?
+- Base#jmespath_search
+- MetaschemaNode keeps its jsi_root_node (reducing an enormous number of unnecessary instantiations of MetaschemaNode)
+- /metaschema_instance_modules/schema_implementation_modules/
+- separate JSI::Util (public) and JSI::Util::Private
+- support ruby 3
+- Schema.default_metaschema is nil unless set by the application
+- deprecate JSI::Typelike module, merged with Util; Arraylike -> Util::Arraylike, Hashlike -> Util::Hashlike
+
 # v0.6.0
 
 - initial validation; remove gem `json-schema` dependency

data/LICENSE.md

@@ -2,7 +2,7 @@ Copright © [Ethan](https://github.com/notEthan/) <ethan.jsi@unth.net>
 
 [<img align="right" src="https://github.com/notEthan/jsi/raw/master/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
 
-JSI is Open Source Software licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
+JSI is licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 
 GNU Affero General Public License
 =================================

data/README.md

@@ -1,6 +1,6 @@
 # JSI: JSON Schema Instantiation
 
-[![Build Status](https://travis-ci.org/notEthan/jsi.svg?branch=master)](https://travis-ci.org/notEthan/jsi)
+![Test CI Status](https://github.com/notEthan/jsi/actions/workflows/test.yml/badge.svg?branch=stable)
 [![Coverage Status](https://coveralls.io/repos/github/notEthan/jsi/badge.svg)](https://coveralls.io/github/notEthan/jsi)
 
 JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby modules and classes which are used to instantiate your JSON data. These modules let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
@@ -46,6 +46,8 @@ We name the module that JSI will use when instantiating a contact. Named modules
 Contact = contact_schema.jsi_schema_module
 ```
 
+Note: it is more concise to instantiate the schema module with the shortcut {JSI.new_schema_module}, i.e. `Contact = JSI.new_schema_module(...)`. This example includes the intermediate step to help show all that is happening.
+
 To instantiate the schema, we need some JSON data (expressed here as YAML)
 
 ```yaml
@@ -173,17 +175,20 @@ module Contact
   end
 end
 
+bill.phone_numbers
+# => ["555"]
+
 bill.name
 # => "bill esq."
 bill.name = 'rob esq.'
 # => "rob esq."
 bill['name']
 # => "rob"
-bill.phone_numbers
-# => ["555"]
 ```
 
-Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers. You can alternatively use `[]` and `[]=` with the same effect.
+`#phone_numbers` is a new method returning each number in the `phone` array - pretty straightforward.
+
+For `#name` and `#name=`, we're overriding existing accessor methods. note the use of `super` - this invokes the accessor methods defined by JSI which these override. You could alternatively use `self['name']` and `self['name']=` in these methods, with the same effect as `super`.
 
 Working with subschemas is just about as easy as with root schemas.
 
@@ -269,7 +274,7 @@ Let's say you're sticking to JSON types in the database - you have to do so if y
 
 But if your database contains JSON, then your deserialized objects in ruby are likewise Hash / Array / basic types. You have to use subscripts instead of accessors, and you don't have any way to add methods to your data types.
 
-JSI gives you the best of both with JSICoder. This coder dumps objects which are simple JSON types, and loads instances of a specified JSI schema. Here's an example, supposing a `users` table with a JSON column `contact_info`:
+JSI gives you the best of both with {JSI::JSICoder}. This coder dumps objects which are simple JSON types, and loads instances of a specified JSON Schema. Here's an example, supposing a `users` table with a JSON column `contact_info` to be instantiated using the `Contact` schema module defined in the Example section above:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -277,7 +282,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-Now `user.contact_info` will be instantiated as a Contact JSI instance, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
+Now `user.contact_info` will be instantiated as a `Contact` JSI instance, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
 
 See the gem [`arms`](https://github.com/notEthan/arms) if you wish to serialize the dumped JSON-compatible objects further as text.
 

data/jsi.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "jsi/version"
+
+Gem::Specification.new do |spec|
+  spec.name    = "jsi"
+  spec.version = JSI::VERSION
+  spec.authors = ["Ethan"]
+  spec.email   = ["ethan.jsi@unth.net"]
+
+  spec.summary     = "JSI: JSON Schema Instantiation"
+  spec.description = "JSI offers an Object-Oriented representation for JSON data using JSON Schemas"
+  spec.homepage    = "https://github.com/notEthan/jsi"
+  spec.license     = "AGPL-3.0"
+
+  spec.files = [
+    'LICENSE.md',
+    'CHANGELOG.md',
+    'README.md',
+    'readme.rb',
+    '.yardopts',
+    'jsi.gemspec',
+    *Dir['lib/**/*'],
+    *Dir['\\{resources\\}/schemas/**/*'],
+  ].reject { |f| File.lstat(f).ftype == 'directory' }
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "addressable", '~> 2.3'
+end

data/lib/jsi/base/node.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module JSI
+  module Base::Enumerable
+    include ::Enumerable
+
+    # an Array containing each item in this JSI.
+    #
+    # @param kw keyword arguments are passed to {Base#[]} - see its keyword params
+    # @return [Array]
+    def to_a(**kw)
+      # TODO remove eventually (keyword argument compatibility)
+      # discard when all supported ruby versions Enumerable#to_a delegate keywords to #each (3.0.1 breaks; 2.7.x warns)
+      # https://bugs.ruby-lang.org/issues/18289
+      ary = []
+      each(**kw) do |e|
+        ary << e
+      end
+      ary
+    end
+
+    alias_method :entries, :to_a
+
+    # a jsonifiable representation of the node content
+    # @return [Object]
+    def as_json(*opt)
+      # include Enumerable (above) means, if ActiveSupport is loaded, its undesirable #as_json is included
+      # https://github.com/rails/rails/blob/v7.0.0/activesupport/lib/active_support/core_ext/object/json.rb#L139-L143
+      # although Base#as_json does clobber activesupport's, I want as_json defined correctly on the module too.
+      Typelike.as_json(jsi_node_content, *opt)
+    end
+  end
+
+  # module extending a {JSI::Base} object when its instance (its {Base#jsi_node_content})
+  # is a Hash (or responds to `#to_hash`)
+  module Base::HashNode
+    include Base::Enumerable
+
+    # yields each hash key and value of this node.
+    #
+    # each yielded key is a key of the instance hash, and each yielded value is the result of {Base#[]}.
+    #
+    # returns an Enumerator if no block is given.
+    #
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @yield [Object, Object] each key and value of this hash node
+    # @return [self, Enumerator] an Enumerator if invoked without a block; otherwise self
+    def each(**kw, &block)
+      return to_enum(__method__, **kw) { jsi_node_content_hash_pubsend(:size) } unless block
+      if block.arity > 1
+        jsi_node_content_hash_pubsend(:each_key) { |k| yield k, self[k, **kw] }
+      else
+        jsi_node_content_hash_pubsend(:each_key) { |k| yield [k, self[k, **kw]] }
+      end
+      self
+    end
+
+    # a hash in which each key is a key of the instance hash and each value is the result of {Base#[]}
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @return [Hash]
+    def to_hash(**kw)
+      {}.tap { |h| jsi_node_content_hash_pubsend(:each_key) { |k| h[k] = self[k, **kw] } }
+    end
+
+    include Util::Hashlike
+
+    if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_hash
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_hash
+      def jsi_node_content_hash_pubsend(method_name, *a, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, &b)
+        else
+          jsi_node_content.to_hash.public_send(method_name, *a, &b)
+        end
+      end
+    else
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_hash
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param kw keyword arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_hash
+      def jsi_node_content_hash_pubsend(method_name, *a, **kw, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, **kw, &b)
+        else
+          jsi_node_content.to_hash.public_send(method_name, *a, **kw, &b)
+        end
+      end
+    end
+
+    # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_hash)
+    SAFE_KEY_ONLY_METHODS.each do |method_name|
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) do |*a, &b|
+          jsi_node_content_hash_pubsend(method_name, *a, &b)
+        end
+      else
+        define_method(method_name) do |*a, **kw, &b|
+          jsi_node_content_hash_pubsend(method_name, *a, **kw, &b)
+        end
+      end
+    end
+  end
+
+  # module extending a {JSI::Base} object when its instance (its {Base#jsi_node_content})
+  # is an Array (or responds to `#to_ary`)
+  module Base::ArrayNode
+    include Base::Enumerable
+
+    # yields each array element of this node.
+    #
+    # each yielded element is the result of {Base#[]} for each index of the instance array.
+    #
+    # returns an Enumerator if no block is given.
+    #
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @yield [Object] each element of this array node
+    # @return [self, Enumerator] an Enumerator if invoked without a block; otherwise self
+    def each(**kw, &block)
+      return to_enum(__method__, **kw) { jsi_node_content_ary_pubsend(:size) } unless block
+      jsi_node_content_ary_pubsend(:each_index) { |i| yield(self[i, **kw]) }
+      self
+    end
+
+    # an array, the same size as the instance array, in which the element at each index is the
+    # result of {Base#[]}.
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @return [Array]
+    def to_ary(**kw)
+      to_a(**kw)
+    end
+
+    include Util::Arraylike
+
+    if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_ary
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_ary
+      def jsi_node_content_ary_pubsend(method_name, *a, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, &b)
+        else
+          jsi_node_content.to_ary.public_send(method_name, *a, &b)
+        end
+      end
+    else
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_ary
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param kw keyword arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_ary
+      def jsi_node_content_ary_pubsend(method_name, *a, **kw, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, **kw, &b)
+        else
+          jsi_node_content.to_ary.public_send(method_name, *a, **kw, &b)
+        end
+      end
+    end
+
+    # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_a).
+    # we override these methods from Arraylike
+    SAFE_INDEX_ONLY_METHODS.each do |method_name|
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) do |*a, &b|
+          jsi_node_content_ary_pubsend(method_name, *a, &b)
+        end
+      else
+        define_method(method_name) do |*a, **kw, &b|
+          jsi_node_content_ary_pubsend(method_name, *a, **kw, &b)
+        end
+      end
+    end
+  end
+end