json2ruby 0.1.0 → 0.1.1

data/.gitignore

@@ -1,4 +1,5 @@
 coverage
 testjson
 classes
+doc
 *.gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    json2ruby (0.1.0)
+    json2ruby (0.1.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,6 @@
 # json2ruby
 
-[![Build Status](https://travis-ci.org/tomdionysus/json2ruby.svg?branch=master)](https://travis-ci.org/tomdionysus/json2ruby) [![Coverage Status](https://coveralls.io/repos/tomdionysus/json2ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/tomdionysus/json2ruby?branch=master)
+[![Build Status](https://travis-ci.org/tomdionysus/json2ruby.svg?branch=master)](https://travis-ci.org/tomdionysus/json2ruby) [![Coverage Status](https://coveralls.io/repos/tomdionysus/json2ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/tomdionysus/json2ruby?branch=master) [![Gem Version](https://badge.fury.io/rb/json2ruby.svg)](http://badge.fury.io/rb/json2ruby)
 
 A ruby rool for generating POROs from JSON data. It is intended to generate ruby model classes/modules from existing JSON data, e.g. responses from an API.
 
@@ -11,7 +11,7 @@ The tool will 'fold down' objects with identical fields - i.e. if an object has
 ## Installation
 
 ```bash
-git clone git@github.com:tomdionysus/json2ruby.git
+gem install json2ruby
 ```
 
 ## Usage
@@ -69,6 +69,14 @@ end
 
 The option `-N, --forcenumeric` can be useful to fold down identical types where an attribute which is a float happens to have an integer value, to avoid generating two identical types.
 
+## Documentation
+
+Regenerate the documentation with 'rdoc':
+
+```bash
+rdoc
+```
+
 ## Contributing
 
 1. Fork it

data/lib/json2ruby/attribute.rb

@@ -1,22 +1,33 @@
 require 'digest/md5'
 
 module JSON2Ruby
+  # The Attribute class represents a field on an Entity - i.e. A field name and associated type. 
   class Attribute
-    attr_accessor :name, :original_name, :ruby_type
+    # The String name of the Attribute
+    attr_accessor :name
+    # The original String name of the Array in the JSON ([^A-Za-z0-9_] are replaced with '_')
+    attr_accessor :original_name
+    # The type of the attribute, i.e. a Entity, Collection or Primitive instance
+    attr_accessor :ruby_type
 
+    # The short name is 'Attribute'
     def self.short_name
       "Attribute"
     end
 
+    # Create a new attribute with the supplied String name and optional String type name. 
+    # If the type is not supplied or nil, if will be assigned '_unknown'
     def initialize(name, ruby_type = nil)
       @name = name
       @ruby_type = ruby_type || "_unknown"
     end
 
+    # Return the MD5 hash of the name and the type.
     def attr_hash
       Digest::MD5.hexdigest("#{@name}:#{@ruby_type}")
     end
 
+    # An Attribute is equal to another if and only if its attr_hash value is the same.
     def ==(other)
       return false if other.class != self.class
       attr_hash == other.attr_hash

data/lib/json2ruby/cli.rb

@@ -4,7 +4,9 @@ require 'optparse'
 
 module JSON2Ruby
 
+  # The CLI (Command Line Interface) functionality class for the json2ruby executable
   class CLI
+    # Run the json2ruby command, using arguments in ARGV.
     def self.run
 
       puts "json2ruby v#{VERSION}\n"
@@ -26,6 +28,7 @@ module JSON2Ruby
       write_files(rootclasses, writer, options)
     end
 
+    # Create the output directory with the options[:outputdir] if it does not exist.
     def self.ensure_output_dir(options)
       puts "Output Directory: #{options[:outputdir]}" if options[:verbose]
       unless Dir.exists?(options[:outputdir])
@@ -34,8 +37,8 @@ module JSON2Ruby
       end
     end
 
+    # Process ARGV for command line switches and return the options hash.
     def self.get_cli_options
-
       options = {}
       OptionParser.new do |opts|
         opts.banner = "Usage: #{$0} [options] <file.json> [<file.json>....]"
@@ -115,6 +118,7 @@ module JSON2Ruby
       options
     end
 
+    # Parse all JSON files in ARGV and build the Entity cache, using the supplied options Hash.
     def self.parse_files(options)
       # Reset the object cache
       Entity.reset_parse
@@ -137,6 +141,8 @@ module JSON2Ruby
       rootclasses
     end
 
+    # Write out all types in the Entity cache, except primitives and those contained in the 
+    # rootclasses array, to the provided writer with the supplied options Hash.
     def self.write_files(rootclasses, writer, options)
       files = 0
       Entity.entities.each do |k,v|
@@ -171,6 +177,7 @@ module JSON2Ruby
       puts "Done, Generated #{files} file#{files==1 ? '' : 's'}"
     end
 
+    # Display the Entity supplied in ent with the supplied hash value hsh to STDOUT  
     def self.display_entity(hsh, ent)
       puts "- #{ent.name} (#{ent.class.short_name} - #{hsh})"
       if ent.is_a?(Entity)

data/lib/json2ruby/collection.rb

@@ -1,18 +1,31 @@
 require 'digest/md5'
 
 module JSON2Ruby
+  # Collection represents a JSON Array
   class Collection
-    attr_accessor :name, :original_name, :ruby_types
+    # The String name of the Array, i.e. the field name in which it was first encountered. 
+    attr_accessor :name
+    # The original String name of the Array in the JSON ([^A-Za-z0-9_] are replaced with '_')
+    attr_accessor :original_name
+    # The array of types (Entity, Collection or Primitive instances) encountered in the JSON Array
+    attr_accessor :ruby_types
 
+    # The short name is 'Collection'
     def self.short_name
       "Collection"
     end
 
+    # Create a new Collection with the specified name and optional Array of ypes.
     def initialize(name, ruby_types = {})
       @name = name
       @ruby_types = ruby_types
     end
 
+    # Create a new, or return an existing, Collection named name that supports all types in obj_array.
+    # Optionally, options can be supplied:
+    # * :forcenumeric => true - Use RUBYNUMERIC instead of RUBYINTEGER / RUBYFLOAT.
+    #
+    # Note: Contained JSON Objects and Arrays will be recursively parsed into Entity and Collection instances.
     def self.parse_from(name, obj_array, options = {})
       ob = self.new(name)
       obj_array.each do |v|
@@ -41,6 +54,8 @@ module JSON2Ruby
       ob
     end
 
+    # Return a 128-bit hash as a hex string, representative of the set of possible types in the Collection
+    # Internally, this is calculated as the MD5 hash of the attr_hash values of all types.
     def attr_hash
       md5 = Digest::MD5.new
       @ruby_types.each do |k,typ|
@@ -49,11 +64,13 @@ module JSON2Ruby
       md5.hexdigest
     end
 
+    # Compare this Collection with another Collection. Two collections are equal if and only if they can contain exactly the same types.
     def ==(other)
       return false if other.class != self.class
       attr_hash == other.attr_hash
     end
 
+    # Generate a String comment of the form '<x>[] (<y)' where <x> and <y> are the name and original name of the Collection respectively.
     def comment
       x = "#{@name}[]"
       x += " (#{@original_name})" unless @original_name.nil?

data/lib/json2ruby/entity.rb

@@ -1,19 +1,28 @@
 require 'digest/md5'
 
 module JSON2Ruby
-
+  # Entity represents a JSON Object.
   class Entity
-    attr_accessor :name, :original_name, :attributes
+    # The String name of the Object - i.e. the field name in which it was first encountered. 
+    attr_accessor :name
+    # The original String name of the object in the JSON ([^A-Za-z0-9_] are replaced with '_')
+    attr_accessor :original_name
+    # A Hash of String names to Attribute instances for this Entity, representing its attributes.
+    attr_accessor :attributes
 
+    # The short name is 'Entity'
     def self.short_name
       "Entity"
     end
 
+    # Create a new Entity with the specified name and optional Hash of attributes (String name to Entity, Collection or Primitive instances)
     def initialize(name, attributes = {})
       @name = name
       @attributes = attributes
     end
 
+    # Return a 128-bit hash as a hex string, representative of the unique set of fields and their types, including all subobjects.
+    # Internally, this is calculated as the MD5 of all field names and their type attr_hash calls.
     def attr_hash
       md5 = Digest::MD5.new
       @attributes.each do |k,v|
@@ -22,11 +31,17 @@ module JSON2Ruby
       md5.hexdigest
     end
 
+    # Compare this Entity with another. An entity is equal to another entity if and only if it has:
+    # * The same number of fields
+    # * The fields have the same case-sensitive name
+    # * The fields have the same types, as tested with `attr_hash`
+    # i.e. in short, an entity is equal to another entity if and only if both +attr_hash+ calls return the same value.
     def ==(other)
       return false if other.class != self.class
       attr_hash == other.attr_hash
     end
 
+    # Reset the internal type cache for all Entities everywhere, and reset the global Unknown number.
     def self.reset_parse
       @@objs = {
         RUBYSTRING.attr_hash => RUBYSTRING,
@@ -38,6 +53,11 @@ module JSON2Ruby
       @@unknowncount = 0
     end
 
+    # Create a new, or return an existing, Entity named name that supports all fields in obj_hash.
+    # Optionally, options can be supplied:
+    # * :forcenumeric => true - Use RUBYNUMERIC instead of RUBYINTEGER / RUBYFLOAT.
+    #
+    # Note: Contained JSON Objects and Arrays will be recursively parsed into Entity and Collection instances.
     def self.parse_from(name, obj_hash, options = {})
       ob = self.new(name)
       obj_hash.each do |k,v|
@@ -70,16 +90,20 @@ module JSON2Ruby
       ob
     end
 
+    # Return the type cache of all Entity objects.
+    # This is a Hash of +hash_attr+ values to +Entity+ instances.
     def self.entities
       @@objs
     end
 
+    # Return a string of the form 'Unknown<x>' where <x> is a globally unique sequence.
     def self.get_next_unknown
       @@unknowncount ||= 0
       @@unknowncount += 1
       "Unknown#{@@unknowncount}"
     end
 
+    # Return a string of the form ' (<y>)' where <y> is the original_name of the Entity
     def comment
       x = @name
       x += " (#{@original_name})" unless @original_name.nil?

data/lib/json2ruby/primitive.rb

@@ -1,21 +1,30 @@
 module JSON2Ruby
-
+  # Represents a JSON Primitive. You should not instantiate this class - use the static instances:
+  # * JSON2Ruby::RUBYSTRING for JSON Strings
+  # * JSON2Ruby::RUBYINTEGER for JSON Integers
+  # * JSON2Ruby::RUBYFLOAT for JSON Floats
+  # * JSON2Ruby::RUBYBOOLEAN for JSON Booleans
+  # * JSON2Ruby::RUBYNUMERIC for JSON Numerics (Integers or floats)
   class Primitive
-    attr_accessor :name, :original_name, :attr_hash
+    # The +String+ name of the Primitive. 
+    attr_accessor :name
+    # +String+ Exists for compatibility.
+    attr_accessor :original_name
+    # The static +attr_hash+ of the Primitive.
+    attr_accessor :attr_hash
 
+    # The short name is 'Primitive'
     def self.short_name
       "Primitive"
     end
 
+    # Create a new Primitive with the specified +name+ and +attr_hash+
     def initialize(name, attr_hash)
       @name = name
       @attr_hash = attr_hash
     end
 
-    def attr_hash
-      @attr_hash
-    end
-
+    # Return the +name+ of the Primitive
     def comment
       @name
     end
@@ -30,5 +39,5 @@ module JSON2Ruby
   # Primitive Representing a Ruby Boolean
   RUBYBOOLEAN = Primitive.new("Boolean","0123456789ABCDEF0123456789ABCDE2")
   # Psuedo-Primitive Representing a Numeric
-  RUBYNUMERIC = Primitive.new("Numeric","0123456789ABCDEF0123456789ABCDE2")
+  RUBYNUMERIC = Primitive.new("Numeric","0123456789ABCDEF0123456789ABCDE3")
 end

data/lib/json2ruby/ruby_writer.rb

@@ -3,7 +3,16 @@ require 'json'
 require 'optparse'
 
 module JSON2Ruby
+  # The RubyWriter class contains methods to output ruby code from a given Entity.
   class RubyWriter
+    # Return a String containing a Ruby class/module definition for the given Entity.
+    # Optionally, supply indent to set the indent of the generated code in spaces,
+    # and supply a Hash of options as follows:
+    # * :modules - Boolean if true, generate Ruby +module+ files instead of classes.
+    # * :require - Array of String items, each of which will generate a `require '<x>'` statement for each item
+    # * :superclass_name - String, if supplied, the superclass of the class to geneerate
+    # * :extend - Array of String items, each of which will generate a `extend '<x>'` statement for each item in the class
+    # * :include - Array of String items, each of which will generate a `include '<x>'` statement for each item in the class
     def self.to_code(entity, indent = 0, options = {})
       x = ""
       if options.has_key?(:require)
@@ -27,7 +36,14 @@ module JSON2Ruby
       x
     end
 
-    def self.attributes_to_ruby(entity, indent, options = {})
+    # Return a String containing the Ruby code for each Attribute definition for in the supplied Entity.
+    # Optionally, supply indent to set the indent of the generated code in spaces,
+    # and supply a Hash of options as follows:
+    # * :attributemethod - String, the method to call to define attributes
+    # * :collectionmethod - String, the method to call to define collections
+    # * :includetypes - Boolean if true, include the string of the Attribute type as a second parameter to the definition call.
+    # * :namespace - String, the namespace of the type classes in the format 'Module::SubModule'...
+    def self.attributes_to_ruby(entity, indent = 0, options = {})
       ident = (' '*indent)
       x = ""
       entity.attributes.each do |k,v|

data/lib/json2ruby/version.rb

@@ -1,3 +1,5 @@
+# The JSON2Ruby module encapsulates all classes and constants for the json2ruby gem and executable.
 module JSON2Ruby
-  VERSION = '0.1.0'
+  # The Version of this json2ruby
+  VERSION = '0.1.1'
 end

data/spec/collection_spec.rb

@@ -62,8 +62,8 @@ describe JSON2Ruby::Collection do
 
       expect(col).to be_a(JSON2Ruby::Collection)
       expect(col.name).to eq("Test")
-      expect(col.ruby_types.length).to eq(4)
-      expect(col.attr_hash).to eq("e38d96234bfbf21545ed4ab2128b9ab4")
+      expect(col.ruby_types.length).to eq(5)
+      expect(col.attr_hash).to eq("94db8ab7a9379e835f6a69714fbec9cc")
     end
   end
 

data/spec/entity_spec.rb

@@ -59,7 +59,7 @@ describe JSON2Ruby::Entity do
       expect(ent).to be_a(JSON2Ruby::Entity)
       expect(ent.name).to eq("Test")
       expect(ent.attributes.length).to eq(6)
-      expect(ent.attr_hash).to eq("592884f7d98c4a31b7d641b10636d546")
+      expect(ent.attr_hash).to eq("5681e2da2b9aa0a343e622ef771c0abb")
     end
   end
 

data/spec/primitive_spec.rb

@@ -45,7 +45,7 @@ describe JSON2Ruby::Primitive do
       expect(JSON2Ruby::RUBYBOOLEAN.attr_hash).to eq('0123456789ABCDEF0123456789ABCDE2')
 
       expect(JSON2Ruby::RUBYNUMERIC.name).to eq('Numeric')
-      expect(JSON2Ruby::RUBYNUMERIC.attr_hash).to eq('0123456789ABCDEF0123456789ABCDE2')
+      expect(JSON2Ruby::RUBYNUMERIC.attr_hash).to eq('0123456789ABCDEF0123456789ABCDE3')
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json2ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-21 00:00:00.000000000 Z
+date: 2015-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: coveralls
@@ -223,3 +223,4 @@ test_files:
 - spec/primitive_spec.rb
 - spec/ruby_writer_spec.rb
 - spec/spec_helper.rb
+has_rdoc: