jsi 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec49b425e6253b4ff1bf14b1d2218fe1bd5c905194d169faab948820a2e17302
-  data.tar.gz: 56d79d38177b3272ba094e21def5083896a12c8157346909b739927fbe52e542
+  metadata.gz: 61dd1e2dc8c145ccf5acdcd6a0d6eaeef0d61dd85e876347af89f7168e838319
+  data.tar.gz: de6f01e5e859f2b3039b7d2c6f734b1e30b97b8c946f2444783581931d5939e9
 SHA512:
-  metadata.gz: cd3d72c29b166c0bb7b1a5970742e5538a79fda1a16359fadb35dd3b6ea65911481f40ab8e4f79ec9da56247f385ee6168ad2aeeaec0f4a6735da7370aba8005
-  data.tar.gz: c476fb40d83d9b98568bc067375ddf2f95953fe886284ab889fed11df51b12bd3c8c079bb6dc7e0dec52fa38175e61eb1d784b83d3b707cc984100670f8a592a
+  metadata.gz: c15c232306814b19a3b84f94c9bd5bacfa261c7124e007ad8961e6e7a28495c23e675963aca024d2abb29613ba9092313cf11b0344feb3e20f38dec6dcf511b1
+  data.tar.gz: c00160e62da570c862b694d516bb157019b1799dcff24f594f494fa695c45fcfaa4a5e34e93b8bf35978c28e9bf13e84ed86b3938eff3b7443c6e4cae81118af

data/.yardopts

@@ -0,0 +1 @@
+--main README.md --markup=markdown {lib}/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.0.2
+
+- JSI::JSON::Node and other utilities duck-type better with #to_hash and #to_ary
+- much improved documentation
+- much improved test coverage
+- code improvements too numerous to list
+
 # v0.0.1
 
 - extracted JSI from Scorpio

data/README.md

@@ -5,7 +5,7 @@
 
 JSI represents JSON-schemas as ruby classes, and schema instances as instances of those classes.
 
-A JSI class aims to be a fairly unobtrusive wrapper around its instance. It adds accessors for known property names, validation methods, and a few other nice things. Mostly though, you use a JSI as you would use its underlying data.
+A JSI class aims to be a fairly unobtrusive wrapper around its instance. It adds accessors for known property names, validation methods, and a few other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting #to_ary or #to_hash.
 
 ## Example
 
@@ -25,25 +25,29 @@ properties:
         number: {type: "string"}
 ```
 
-And here's an instance of that schema with JSI:
+And here's the class for that schema from JSI:
 
 ```ruby
 Contact = JSI.class_for_schema(YAML.load_file('contact.schema.yml'))
+# you can copy/paste this line instead, to follow along in irb:
+Contact = JSI.class_for_schema({"description" => "A Contact", "type" => "object", "properties" => {"name" => {"type" => "string"}, "phone" => {"type" => "array", "items" => {"type" => "object", "properties" => {"location" => {"type" => "string"}, "number" => {"type" => "string"}}}}}})
 ```
 
 This definition gives you not just the Contact class, but classes for the whole nested structure. So, if we construct an instance like:
 
 ```ruby
-bill = Contact.new(name: 'bill', phone: [{location: 'home', number: '555'}], nickname: 'big b')
+bill = Contact.new('name' => 'bill', 'phone' => [{'location' => 'home', 'number' => '555'}], 'nickname' => 'big b')
 # => #{<Contact fragment="#">
 # #{<Contact fragment="#">
-#   "phone" => #[<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone"] fragment="#/phone">
-#     #{<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone/items"] fragment="#/phone/0"> "location" => "home", "number" => "555"}
+#   "phone" => #[<JSI::SchemaClasses["1f97#/properties/phone"] fragment="#/phone">
+#     #{<JSI::SchemaClasses["1f97#/properties/phone/items"] fragment="#/phone/0"> "location" => "home", "number" => "555"}
 #   ],
 #   "nickname" => "big b"
 # }
 ```
 
+Note that the keys are strings. JSI, being designed with JSON in mind, is geared toward string keys. Symbol keys will not match to schema properties, and so act the same as any other key not recognized from the schema.
+
 The nested classes can be seen as `JSI::SchemaClasses[schema_id]` where schema_id is a generated value.
 
 We get accessors for the Contact:
@@ -70,18 +74,20 @@ bill.validate
 ... and validations on the nested schema instances (#phone here), showing in this example validation failure:
 
 ```ruby
-bad = Contact.new(phone: [{number: [5, 5, 5]}])
+bad = Contact.new('phone' => [{'number' => [5, 5, 5]}])
 # => #{<Contact fragment="#">
-#   "phone" => #[<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone"] fragment="#/phone">
-#     #{<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone/items"] fragment="#/phone/0">
-#       "number" => #[<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone/items/properties/number"] fragment="#/phone/0/number"> 5, 5, 5]
+#   "phone" => #[<JSI::SchemaClasses["1f97#/properties/phone"] fragment="#/phone">
+#     #{<JSI::SchemaClasses["1f97#/properties/phone/items"] fragment="#/phone/0">
+#       "number" => #[<JSI::SchemaClasses["1f97#/properties/phone/items/properties/number"] fragment="#/phone/0/number"> 5, 5, 5]
 #     }
 #   ]
 # }
 bad.phone.fully_validate
-# => ["The property '#/0/number' of type array did not match the following type: string in schema 594126e3-ea3c-5d9a-b5f4-7423a8701f97"]
+# => ["The property '#/0/number' of type array did not match the following type: string in schema 1f97"]
 ```
 
+These validations are done by the [`json-schema` gem](https://github.com/ruby-json-schema/json-schema) - JSI does not do validations on its own.
+
 Since the underlying instance is a ruby hash (json object), we can use it like a hash with #[] or, say, #transform_values:
 
 ```ruby
@@ -93,18 +99,18 @@ bill['nickname']
 
 There's plenty more JSI has to offer, but this should give you a pretty good idea of basic usage.
 
-## Terminology
+## Terminology and Concepts
 
 - JSI::Base is the base class from which other classes representing JSON-Schemas inherit.
 - a JSI class refers to a class representing a schema, a subclass of JSI::Base.
 - "instance" is a term that is significantly overloaded in this space, so documentation will attempt to be clear what kind of instance is meant:
   - a schema instance refers broadly to a data structure that is described by a json-schema.
-  - a JSI instance is a ruby object instantiating a JSI class. it has a method #instance which contains the underlying data.
-- a schema refers to a json-schema. a JSI::Schema represents such a json-schema. a JSI class allow instantiation of such a schema.
+  - a JSI instance (or just "a JSI") is a ruby object instantiating a JSI class. it has a method #instance which contains the underlying data.
+- a schema refers to a json-schema. a JSI::Schema represents such a json-schema. a JSI class allows instantiation of such a schema.
 
 ## JSI classes
 
-A JSI class (that is, subclass of JSI::Base) is a starting point but obviously you want your own methods, so you reopen the class as you would any other. referring back to the Example section above, here's an example:
+A JSI class (that is, subclass of JSI::Base) is a starting point but obviously you want your own methods, so you reopen the class as you would any other. referring back to the Example section above, we reopen the Contact class:
 
 ```ruby
 class Contact
@@ -123,11 +129,37 @@ bill.name
 # => "bill esq."
 bill.name = 'rob esq.'
 # => "rob esq."
-bill.instance['name']
+bill['name']
 # => "rob"
 ```
 
-Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers (these accessor methods are defined on an included class instead of the JSI class for this reason). You can also use [] and []=, of course, with the same effect.
+Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers (these accessor methods are defined on an included module instead of the JSI class for this reason). You can also use [] and []=, of course, with the same effect.
+
+If you want to add methods to a subschema, get the class_for_schema for that schema and open up that class. You can leave the class anonymous, as in this example:
+
+```ruby
+phone_schema = Contact.schema['properties']['phone']['items']
+JSI.class_for_schema(phone_schema).class_eval do
+  def number_with_dashes
+    number.split(//).join('-')
+  end
+end
+bill.phone.first.number_with_dashes
+# => "5-5-5"
+```
+
+If you want to name the class, this works:
+
+```ruby
+Phone = JSI.class_for_schema(Contact.schema['properties']['phone']['items'])
+class Phone
+  def number_with_dashes
+    number.split(//).join('-')
+  end
+end
+```
+
+Either syntax is slightly cumbersome and a better syntax is in the works.
 
 ## ActiveRecord serialization
 
@@ -149,7 +181,7 @@ Now `user.contacts` will return an array of Contact instances, from the json typ
 
 ## Keying Hashes (JSON Objects)
 
-Unlike Ruby, JSON only supports string keys. JSI converts symbols to strings for its internal hash keys (much like ActiveSupport::HashWithIndifferentAccess). JSI accepts symbols to refer to its string hash keys for instantiation, but does not currently transform symbols to strings everywhere else, e.g. `bill[:name]` is `nil` whereas `bill['name']` is `"bill"`.
+Unlike Ruby, JSON only supports string keys. It is recommended to use strings as hash keys for all JSI instances, but JSI does not enforce this, nor does it do any key conversion. It should be possible to use ActiveSupport::HashWithIndifferentAccess as the instance of a JSI in order to gain the benefits that offers over a plain hash. This is not tested behavior, but JSI should behave correctly with any instance that responds to #to_hash.
 
 ## Contributing
 

data/lib/jsi.rb

@@ -20,8 +20,11 @@ module JSI
   autoload :SchemaClasses, 'jsi/base'
   autoload :ObjectJSONCoder, 'jsi/schema_instance_json_coder'
   autoload :StructJSONCoder, 'jsi/struct_json_coder'
-  autoload :SchemaInstanceJSONCoder,'jsi/schema_instance_json_coder'
+  autoload :SchemaInstanceJSONCoder, 'jsi/schema_instance_json_coder'
 
+  # @return [Class subclassing JSI::Base] a JSI class which represents the
+  #   given schema. instances of the class represent JSON Schema instances
+  #   for the given schema.
   def self.class_for_schema(*a, &b)
     SchemaClasses.class_for_schema(*a, &b)
   end

data/lib/jsi/base.rb

@@ -2,16 +2,26 @@ require 'json'
 require 'jsi/typelike_modules'
 
 module JSI
-  # base class for representing an instance of an instance described by a schema
+  # the base class for representing and instantiating a JSON Schema.
+  #
+  # a class inheriting from JSI::Base represents a JSON Schema. an instance of
+  # that class represents a JSON schema instance.
+  #
+  # as such, JSI::Base itself is not intended to be instantiated - subclasses
+  # are dynamically created for schemas using {JSI.class_for_schema}, and these
+  # are what are used to instantiate and represent JSON schema instances.
   class Base
     include Memoize
     include Enumerable
 
     class << self
+      # @return [String] absolute schema_id of the schema this class represents.
+      #   see {Schema#schema_id}.
       def schema_id
         schema.schema_id
       end
 
+      # @return [String] a string representing the class, with schema_id
       def inspect
         if !respond_to?(:schema)
           super
@@ -21,6 +31,9 @@ module JSI
           %Q(#{name} (#{schema_id}))
         end
       end
+
+      # @return [String] a string representing the class - a class name if one
+      #   was explicitly defined, otherwise a reference to JSI::SchemaClasses
       def to_s
         if !respond_to?(:schema)
           super
@@ -31,6 +44,8 @@ module JSI
         end
       end
 
+      # @return [String] a name for a constant for this class, generated from the
+      #   schema_id. only used if the class is not assigned to another constant.
       def schema_classes_const_name
         name = schema.schema_id.gsub(/[^\w]/, '_')
         name = 'X' + name unless name[/\A[a-zA-Z_]/]
@@ -38,6 +53,7 @@ module JSI
         name
       end
 
+      # @return [String] a constant name of this class
       def name
         unless super
           SchemaClasses.const_set(schema_classes_const_name, self)
@@ -46,6 +62,13 @@ module JSI
       end
     end
 
+    # initializes this JSI from the given instance. the instance will be
+    # wrapped as a {JSI::JSON::Node JSI::JSON::Node} (unless what you pass is
+    # a Node already).
+    #
+    # @param instance [Object] the JSON Schema instance being represented
+    # @param origin [JSI::Base] for internal use, specifies a parent
+    #   from which this JSI originated
     def initialize(instance, origin: nil)
       unless respond_to?(:schema)
         raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #schema. please use JSI.class_for_schema")
@@ -61,6 +84,7 @@ module JSI
       end
     end
 
+    # the instance of the json-schema. this is a JSI::JSON::Node.
     attr_reader :instance
 
     # each is overridden by BaseHash or BaseArray when appropriate. the base
@@ -69,6 +93,11 @@ module JSI
       raise NoMethodError, "Enumerable methods and #each not implemented for instance that is not like a hash or array: #{instance.pretty_inspect.chomp}"
     end
 
+    # an array of JSI instances above this one in the document. empty if this
+    # JSI is at the root or was instantiated from a source that does not have
+    # a document (e.g. a plain hash or array).
+    #
+    # @return [Array<JSI::Base>]
     def parents
       parent = @origin
       (@origin.instance.path.size...self.instance.path.size).map do |i|
@@ -77,10 +106,18 @@ module JSI
         end
       end.reverse
     end
+
+    # the immediate parent of this JSI. nil if no parent(s) are known.
+    #
+    # @return [JSI::Base, nil]
     def parent
       parents.first
     end
 
+    # if this JSI is a $ref then the $ref is followed. otherwise this JSI
+    # is returned.
+    #
+    # @return [JSI::Base, self]
     def deref
       derefed = instance.deref
       if derefed.object_id == instance.object_id
@@ -90,6 +127,13 @@ module JSI
       end
     end
 
+    # yields the content of the underlying instance. the block must result in
+    # a modified copy of that (not destructively modifying the yielded content)
+    # which will be used to instantiate a new instance of this JSI class with
+    # the modified content.
+    # @yield [Object] the content of the instance. the block should result
+    #   in a (nondestructively) modified copy of this.
+    # @return [JSI::Base subclass the same as self] the modified copy of self
     def modified_copy(&block)
       modified_instance = instance.modified_copy(&block)
       self.class.new(modified_instance, origin: @origin)
@@ -99,18 +143,32 @@ module JSI
       instance.fragment
     end
 
+    # @return [Array<String>] array of schema validation error messages for this instance
     def fully_validate
       schema.fully_validate(instance)
     end
+
+    # @return [true, false] whether the instance validates against its schema
     def validate
       schema.validate(instance)
     end
+
+    # @return [true] if this method does not raise, it returns true to
+    #   indicate a valid instance.
+    # @raise [::JSON::Schema::ValidationError] raises if the instance has
+    #   validation errors
     def validate!
       schema.validate!(instance)
     end
+
+    # @return [String] a string representing this JSI, indicating its class
+    #   and inspecting its instance
     def inspect
       "\#<#{self.class.to_s} #{instance.inspect}>"
     end
+
+    # pretty-prints a representation this JSI to the given printer
+    # @return [void]
     def pretty_print(q)
       q.instance_exec(self) do |obj|
         text "\#<#{obj.class.to_s}"
@@ -125,34 +183,43 @@ module JSI
       end
     end
 
+    # @return [String] the instance's object_group_text
     def object_group_text
       instance.object_group_text
     end
 
+    # @return [Object] a jsonifiable representation of the instance
     def as_json(*opt)
       Typelike.as_json(instance, *opt)
     end
 
+    # @return [Object] an opaque fingerprint of this JSI for FingerprintHash
     def fingerprint
       {class: self.class, instance: instance}
     end
     include FingerprintHash
 
     private
+
+    # assigns @instance to the given thing, raising if the thing is not appropriate for a JSI instance
+    # @param thing [Object] a JSON schema instance for this class's schema
     def instance=(thing)
       if instance_variable_defined?(:@instance)
         raise(JSI::Bug, "overwriting instance is not supported")
       end
       if thing.is_a?(Base)
         warn "assigning instance to a Base instance is incorrect. received: #{thing.pretty_inspect.chomp}"
-        @instance = JSI.deep_stringify_symbol_keys(thing.instance)
+        @instance = thing.instance
       elsif thing.is_a?(JSI::JSON::Node)
-        @instance = JSI.deep_stringify_symbol_keys(thing)
+        @instance = thing
       else
-        @instance = JSI::JSON::Node.new_by_type(JSI.deep_stringify_symbol_keys(thing), [])
+        @instance = JSI::JSON::Node.new_doc(thing)
       end
     end
 
+    # assigns a subscript, taking care of memoization and unwrapping a JSI if given.
+    # @param subscript [Object] the bit between the [ and ]
+    # @param value [JSI::Base, Object] the value to be assigned
     def subscript_assign(subscript, value)
       clear_memo(:[], subscript)
       if value.is_a?(Base)
@@ -166,12 +233,19 @@ module JSI
   # this module is just a namespace for schema classes.
   module SchemaClasses
     extend Memoize
+
+    # JSI::SchemaClasses[schema_id] returns a class for the schema with the
+    # given id, the same class as returned from JSI.class_for_schema.
+    #
+    # @param schema_id [String] absolute schema id as returned by {JSI::Schema#schema_id}
+    # @return [Class subclassing JSI::Base] the class for that schema
     def self.[](schema_id)
       @classes_by_id[schema_id]
     end
     @classes_by_id = {}
   end
 
+  # see {JSI.class_for_schema}
   def SchemaClasses.class_for_schema(schema_object)
     if schema_object.is_a?(JSI::Schema)
       schema__ = schema_object
@@ -184,7 +258,7 @@ module JSI
         begin
           Class.new(Base).instance_exec(schema_) do |schema|
             begin
-              include(JSI.module_for_schema(schema))
+              include(JSI::SchemaClasses.module_for_schema(schema))
 
               SchemaClasses.instance_exec(self) { |klass| @classes_by_id[klass.schema_id] = klass }
 
@@ -196,7 +270,20 @@ module JSI
     end
   end
 
-  def self.module_for_schema(schema_object)
+  # a module for the given schema, with accessor methods for any object
+  # property names the schema identifies. also has class and instance
+  # methods called #schema to access the {JSI::Schema} this module
+  # represents.
+  #
+  # accessor methods are defined on these modules so that methods can be
+  # defined on {JSI.class_for_schema} classes without method redefinition
+  # warnings. additionally, these overriding instance methods can call
+  # `super` to invoke the normal accessor behavior.
+  #
+  # no property names that are the same as existing method names on the JSI
+  # class will be defined. users should use #[] and #[]= to access properties
+  # whose names conflict with existing methods.
+  def SchemaClasses.module_for_schema(schema_object)
     if schema_object.is_a?(JSI::Schema)
       schema__ = schema_object
     else
@@ -219,26 +306,24 @@ module JSI
             %Q(#<Module for Schema: #{schema_id}>)
           end
 
-          if schema.describes_hash?
-            instance_method_modules = [m, Base, BaseArray, BaseHash]
-            instance_methods = instance_method_modules.map do |mod|
-              mod.instance_methods + mod.private_instance_methods
-            end.inject(Set.new, &:|)
-            accessors_to_define = schema.described_hash_property_names.map(&:to_s) - instance_methods.map(&:to_s)
-            accessors_to_define.each do |property_name|
-              define_method(property_name) do
-                if respond_to?(:[])
-                  self[property_name]
-                else
-                  raise(NoMethodError, "instance does not respond to []; cannot call reader `#{property_name}' for: #{pretty_inspect.chomp}")
-                end
+          instance_method_modules = [m, Base, BaseArray, BaseHash]
+          instance_methods = instance_method_modules.map do |mod|
+            mod.instance_methods + mod.private_instance_methods
+          end.inject(Set.new, &:|)
+          accessors_to_define = schema.described_object_property_names.map(&:to_s) - instance_methods.map(&:to_s)
+          accessors_to_define.each do |property_name|
+            define_method(property_name) do
+              if respond_to?(:[])
+                self[property_name]
+              else
+                raise(NoMethodError, "instance does not respond to []; cannot call reader `#{property_name}' for: #{pretty_inspect.chomp}")
               end
-              define_method("#{property_name}=") do |value|
-                if respond_to?(:[]=)
-                  self[property_name] = value
-                else
-                  raise(NoMethodError, "instance does not respond to []=; cannot call writer `#{property_name}=' for: #{pretty_inspect.chomp}")
-                end
+            end
+            define_method("#{property_name}=") do |value|
+              if respond_to?(:[]=)
+                self[property_name] = value
+              else
+                raise(NoMethodError, "instance does not respond to []=; cannot call writer `#{property_name}=' for: #{pretty_inspect.chomp}")
               end
             end
           end
@@ -247,14 +332,22 @@ module JSI
     end
   end
 
+  # module extending a {JSI::Base} object when its schema instance is Hash-like (responds to #to_hash)
   module BaseHash
-    # Hash methods
+    # yields each key and value of this JSI.
+    # each yielded key is the same as a key of the instance, and each yielded
+    # value is the result of self[key] (see #[]).
+    # returns an Enumerator if no block is given.
+    # @yield [Object, Object] each key and value of this JSI hash
+    # @return [self, Enumerator]
     def each
       return to_enum(__method__) { instance.size } unless block_given?
       instance.each_key { |k| yield(k, self[k]) }
       self
     end
 
+    # @return [Hash] a hash in which each key is a key of the instance hash and
+    #   each value is the result of self[key] (see #[]).
     def to_hash
       inject({}) { |h, (k, v)| h[k] = v; h }
     end
@@ -266,6 +359,10 @@ module JSI
       define_method(method_name) { |*a, &b| instance.public_send(method_name, *a, &b) }
     end
 
+    # @return [JSI::Base, Object] the instance's subscript value at the given
+    #   key property_name_. if there is a subschema defined for that property
+    #   on this JSI's schema, returns the instance's subscript as a JSI
+    #   instiation of that subschema.
     def [](property_name_)
       memoize(:[], property_name_) do |property_name|
         begin
@@ -280,18 +377,33 @@ module JSI
         end
       end
     end
+
+    # assigns the given property name of the instance to the given value.
+    # if the value is a JSI, its instance is assigned.
+    # @param property_name [Object] this should generally be a String, but JSI
+    #   does not enforce any constraint on it.
+    # @param value [Object] the value to be assigned to the given subscript
+    #   property_name
     def []=(property_name, value)
       subscript_assign(property_name, value)
     end
   end
 
+  # module extending a {JSI::Base} object when its schema instance is Array-like (responds to #to_ary)
   module BaseArray
+    # yields each element. each yielded element is the result of self[index]
+    # for each index of the instance (see #[]).
+    # returns an Enumerator if no block is given.
+    # @yield [Object] each element of this JSI array
+    # @return [self, Enumerator]
     def each
       return to_enum(__method__) { instance.size } unless block_given?
       instance.each_index { |i| yield(self[i]) }
       self
     end
 
+    # @return [Array] an array, the same size as the instance, in which the
+    #   element at each index is the result of self[index] (see #[])
     def to_ary
       to_a
     end
@@ -304,6 +416,10 @@ module JSI
       define_method(method_name) { |*a, &b| instance.public_send(method_name, *a, &b) }
     end
 
+    # @return [Object] returns the instance's subscript value at the given index
+    #   i_. if there is a subschema defined for that index on this JSI's schema,
+    #   returns the instance's subscript as a JSI instiation of that subschema.
+    # @param i_ the array index to subscript
     def [](i_)
       memoize(:[], i_) do |i|
         begin
@@ -318,6 +434,11 @@ module JSI
         end
       end
     end
+
+    # assigns the given index of the instance to the given value.
+    # if the value is a JSI, its instance is assigned.
+    # @param i [Object] the array index to assign
+    # @param value [Object] the value to be assigned to the given subscript i
     def []=(i, value)
       subscript_assign(i, value)
     end