fxf 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70f8912e081de135c77935749f2b329a76f3db905f0c19fdac9aee2b3c1aef30
+  data.tar.gz: e92108b05650908867a92ee460e604bf4664ce3fc3f5e3e4132b70da6b112dce
+SHA512:
+  metadata.gz: 0401c245c79b49771cabb9bf9d4e21b64fd375972aac13236dd9f0540bcecbe5a2a393588a6cd29336d3835a98afec46f6dc53da3f731a68952b532e00ddf0be
+  data.tar.gz: becc4252056063906a4e06815cb9c2c36f82b9f4fbfb23e623ad45e74d09ead403770e10344478aff39af007cb007d151eeb1df9fda32f7a7be8708ee878b9d7

data/README.md

@@ -0,0 +1,190 @@
+# FXF
+
+FXF is a JSON structure for serializing interconnected data. It also allows for
+serialization of objects of arbitrary classes.
+
+Native JSON only allows for hierarchical data. For example, the following
+structure serializes to JSON quite nicely.
+
+```text
+hsh = {}
+hsh['mary'] = {'name'=>'Mary'}
+hsh['fred'] = {'name'=>'Fred'}
+```
+
+That produces JSON like this:
+
+```text
+{
+    "mary": {
+        "name": "Mary"
+    },
+    "fred": {
+        "name": "Fred"
+    }
+}
+```
+
+However, if you add interconnections to the data you start getting repeated data
+in the JSON. For example, consider this structure in which the hash for Mary
+includes a reference to the hash for Fred.
+
+```text
+hsh = {}
+hsh['mary'] = {'name'=>'Mary'}
+hsh['fred'] = {'name'=>'Fred'}
+hsh['mary']['friend'] = hsh['fred']
+```
+
+In that case you get this structure with redundant information:
+
+```text
+{
+    "mary": {
+        "name": "Mary",
+        "friend": {
+            "name": "Fred"
+        }
+    },
+    "fred": {
+        "name": "Fred"
+    }
+}
+```
+
+The situation gets worse if data references itself. For example, if the JSON
+module tries to implement this structure, an error results.
+
+```text
+hsh = {}
+hsh['mary'] = {'name'=>'Mary'}
+hsh['fred'] = {'name'=>'Fred'}
+hsh['mary']['self'] = hsh['mary']
+```
+
+That gives us this nesting error:
+
+```text
+Traceback (most recent call last):
+2: from ./json.rb:39:in `<main>'
+1: from /usr/lib/ruby/2.5.0/json/common.rb:286:in `pretty_generate'
+/usr/lib/ruby/2.5.0/json/common.rb:286:in `generate': nesting of 100 is too deep (JSON::NestingError)
+```
+
+FXF preserves the original structure of the object without any difficulties with
+redundant or self-nested objects. To generate an FXF string, simply call
+FXF.generate. In these examples we add `'pretty'=>true` for readability.
+
+```text
+fxf = FXF.generate(hsh, 'pretty'=>true)
+```
+
+So the structure from the previous example would be serialized with this
+(admittedly not very human readable) JSON structure:
+
+```text
+{
+    "root": "47283390982220",
+    "objects": {
+        "47283390982220": {
+            "mary": "47283390982160",
+            "fred": "47283390982120"
+        },
+        "47283390982160": {
+            "name": "47283390982180",
+            "self": "47283390982160"
+        },
+        "47283390982180": "Mary",
+        "47283390982120": {
+            "name": "47283390982140"
+        },
+        "47283390982140": "Fred"
+    }
+}
+```
+
+To parse that string back into a structure, use `FXF.parse`.
+
+```text
+parsed = FXF.parse(fxf)
+```
+
+The resulting parsed data has the same structure as the original.
+
+```text
+puts parsed['mary'] == parsed['mary']['self'] # true
+```
+
+## Custom classes
+
+FXF can serialize data so that the class of the object is preserved. Classes
+must be defined in such a way that their objects can be exported to FXF format,
+then imported again from that format. Doing so requires implementing the
+instance method `to_fxf` and the class method `from_fxf`. Consider this class.
+
+```ruby
+class MyClass
+    attr_reader :pk
+    
+    def initialize(pk)
+        @pk = pk
+    end
+    
+    def to_fxf
+        return {'pk'=>@pk}
+    end
+    
+    def self.from_fxf(details)
+        return self.new(details['pk'])
+    end
+end
+```
+
+The `to_fxf` method returns a hash with information necessary to recreate the
+object. In this case just the `pk` property is required.
+
+When the object is deserialized, that information is passed to the class'
+`from_fxf` method. Note that that is a method of the class itself, so it needs
+to be defined with `self.from_fxf`. The method is given a hash of the same
+information that was exported from `to_fxf`. In this case, `from_fxf` uses that
+hash to create a new `MyClass` object using the primary key.
+
+## Standard classes
+
+FXF can export two standard classes without the need for any additional
+modifications to them: DateTime and URI::HTTPS. More common classes will be
+added as FXF is developed.
+
+In this example, we create a `DateTime` object and a `URI::HTTPS` object.
+
+```ruby
+hsh = {}
+hsh['timestamp'] = DateTime.parse('Jan 5, 2017, 7:18 am')
+hsh['uri'] = URI('https://www.example.com')
+fxf = FXF.generate(hsh, 'pretty'=>true)
+```
+
+Identical objects are created when the FXF string is parsed.
+
+```ruby
+parsed = FXF.parse(fxf)
+puts parsed['timestamp'].class # DateTime
+puts parsed['uri'].class       # URI::HTTPS
+```
+
+## Install
+
+```
+gem install fxf
+```
+
+## Author
+
+Mike O'Sullivan
+mike@idocs.com
+
+## History
+
+| version | date         | notes                         |
+|---------|--------------|-------------------------------|
+| 1.0     | Jan 27, 2020 | Initial upload.               |

data/lib/fxf.rb

@@ -0,0 +1,467 @@
+require 'json'
+
+
+#===============================================================================
+# FXF
+#
+module FXF
+	# version 1.0
+	VERSION = '1.0'
+	
+	#---------------------------------------------------------------------------
+	# generate
+	#
+	
+	# Generates a FXF JSON string.
+	
+	def self.generate(struct, opts={})
+		# $tm.hrm
+		rv = {}
+		self.generate_object(rv, struct)
+		rv = {'root'=>rv.keys[0], 'objects'=>rv}
+		
+		# return JSON
+		if opts['pretty']
+			return JSON.pretty_generate(rv)
+		else
+			return JSON.generate(rv)
+		end
+	end
+	#
+	# generate
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# parse
+	#
+	
+	# Parses an FXF string and returns the structure it defines.
+	
+	def self.parse(fxf)
+		parser = FXF::Parser.new(fxf)
+		return parser.parse()
+	end
+	#
+	# parse
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	
+	#---------------------------------------------------------------------------
+	# generate_object
+	#
+	
+	# Scalar object types. These are all the data types in JSON except for
+	# hashes and arrays.
+	SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass]
+	
+	def self.generate_object(rv, obj)
+		# $tm.hrm
+		key = obj.object_id.to_s
+		
+		# add to rv
+		if not rv.has_key?(key)
+			# scalar
+			if SCALARS.include?(obj.class)
+				rv[key] = obj
+				
+			# hash
+			elsif obj.is_a?(Hash)
+				hsh = rv[key] = {}
+				
+				obj.each do |k, v|
+					hsh[k] = self.generate_object(rv, v)
+				end
+				
+			# array
+			elsif obj.is_a?(Array)
+				arr = rv[key] = []
+				
+				obj.each do |v|
+					arr.push self.generate_object(rv, v)
+				end
+				
+			# to_fxf
+			elsif obj.respond_to?('to_fxf')
+				dfn = {}
+				dfn['class'] = obj.class.to_s
+				dfn['details'] = obj.to_fxf()
+				object_dfn rv, key, 'custom', dfn
+				
+			# standard class
+			elsif translator = FXF::Standard::TO_FXF[obj.class.to_s]
+				dfn = translator.call(obj)
+				object_dfn rv, key, 'standard', dfn
+			
+			# else unknown class
+			else
+				# build details
+				details = {}
+				
+				# string
+				if obj.respond_to?('to_s')
+					details['str'] = obj.to_s
+				end
+				
+				# buid definition
+				dfn = {}
+				dfn['scope'] = 'unrecognized'
+				dfn['class'] = obj.class.to_s
+				dfn['details'] = details
+				
+				# store
+				rv[key] = [dfn]
+			end
+		end
+		
+		# return
+		return key
+	end
+	#
+	# generate_object
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# object_dfn
+	#
+	def self.object_dfn(rv, key, scope, dfn)
+		# $tm.hrm
+		export = {}
+		rv[key] = [export]
+		export['scope'] = scope
+		export['class'] = dfn['class']
+		export['details'] = {}
+		
+		# add object references
+		if dfn['details']
+			if dfn['details'].is_a?(Hash)
+				dfn['details'].each do |k, v|
+					export['details'][k] = self.generate_object(rv, v)
+				end
+			else
+				raise 'custom-object-details-must-be-hash'
+			end
+		end
+	end
+	#
+	# object_dfn
+	#---------------------------------------------------------------------------
+end
+#
+# FXF
+#===============================================================================
+
+
+#===============================================================================
+# FXF::Standard
+#
+
+# This module defines procs for serializing and deserializing DateTime and
+# URI::HTTPS objects.
+
+module FXF::Standard
+	TO_FXF = {}
+	FROM_FXF = {}
+	
+	#---------------------------------------------------------------------------
+	# DateTime
+	#
+	TO_FXF['DateTime'] = proc do |obj|
+		dfn = {}
+		dfn['class'] = 'datetime'
+		dfn['details'] = {'str'=>obj.to_s}
+		dfn
+	end
+	
+	FROM_FXF['datetime'] = proc do |dfn|
+		# $tm.hrm
+		DateTime.parse(dfn.details['str'])
+	end
+	#
+	# DateTime
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# URI
+	#
+	TO_FXF['URI::HTTPS'] = proc do |obj|
+		dfn = {}
+		dfn['class'] = 'uri'
+		dfn['details'] = {'str'=>obj.to_s}
+		dfn
+	end
+
+	FROM_FXF['uri'] = proc do |dfn|
+		URI(dfn.details['str'])
+	end
+	#
+	# URI
+	#---------------------------------------------------------------------------
+end
+#
+# FXF::Standard
+#===============================================================================
+
+
+#===============================================================================
+# FXF::Parser
+#
+
+# `FXF::Parser` isn't intended to be used directly. FXF.parse creates a
+# `FXF::Parser` and calls its `parse` method.
+
+class FXF::Parser
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(raw)
+		@raw = raw
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# parse
+	#
+	def parse()
+		@full = JSON.parse(@raw)
+		@org = @full['objects']
+		@found = {}
+		@collections = []
+		rv = self.build_object(@full['root'])
+		
+		# look for object place holders
+		placeholder_mod()
+		
+		# return
+		return rv
+	end
+	#
+	# parse
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# placeholder_mod
+	#
+	def placeholder_mod
+		# $tm.hrm
+		placeholders = []
+		phs_to_obj = {}
+		
+		# build unique list of placeholders
+		@collections.each do |collection|
+			if collection.is_a?(Array)
+				collection.each do |el|
+					placeholder_add placeholders, el
+				end
+			elsif collection.is_a?(Hash)
+				collection.values.each do |el|
+					placeholder_add placeholders, el
+				end
+			end
+		end
+		
+		# build a hash of placeholders to objects
+		placeholders.each do |ph|
+			# standard
+			if ph.scope == 'standard'
+				if translator = FXF::Standard::FROM_FXF[ph.clss]
+					phs_to_obj[ph] = translator.call(ph)
+				else
+					raise 'do-not-have-standard-translator: ' + ph.clss
+				end
+			
+			# custom
+			elsif ph.scope == 'custom'
+				if Module.const_defined?(ph.clss)
+					clss = Module.const_get(ph.clss)
+					
+					if clss.respond_to?('from_fxf')
+						phs_to_obj[ph] = clss.from_fxf(ph.details)
+					else
+						raise 'class-does-not-have-from-fxf: ' + ph.clss
+					end
+				else
+					raise 'unknown-custom-class: ' + ph.clss
+				end
+			
+			# else don't know how to build this object
+			else
+				phs_to_obj[ph] = ph
+			end
+		end
+		
+		# substitute placeholders to objects
+		@collections.each do |collection|
+			if collection.is_a?(Array)
+				collection.map! do |el|
+					rv = nil
+					
+					if phs_to_obj.has_key?(el)
+						rv = phs_to_obj[el]
+					else
+						rv = el
+					end
+					
+					rv
+				end
+			
+			elsif collection.is_a?(Hash)
+				collection.each do |k, v|
+					if phs_to_obj.has_key?(v)
+						collection[k] = phs_to_obj[v]
+					end
+				end
+			end
+		end
+	end
+	#
+	# placeholder_mod
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# placeholder_add
+	#
+	def placeholder_add(placeholders, el)
+		# $tm.hrm
+		
+		# if placeholder, and not in placeholders array, add to array
+		if el.is_a?(FXF::Parser::ObjectHolder) and (not placeholders.include?(el))
+			placeholders.push el
+		end
+	end
+	#
+	# placeholder_add
+	#---------------------------------------------------------------------------
+
+
+	#---------------------------------------------------------------------------
+	# build_object
+	#
+	def build_object(key)
+		# $tm.hrm
+		rv = nil
+		
+		# if already found
+		if @found.has_key?(key)
+			return @found[key]
+		end
+		
+		# get object definition
+		dfn = @org.delete(key)
+		
+		# scalar
+		if FXF::SCALARS.include?(dfn.class)
+			@found[key] = dfn
+			return dfn
+			
+		# array
+		elsif dfn.is_a?(Array)
+			# if object description
+			if dfn[0].is_a?(Hash)
+				details = {}
+				build_hash(dfn[0]['details'], details)
+				dfn = FXF::Parser::ObjectHolder.new dfn[0]['scope'], dfn[0]['class'], details
+				@found[key] = dfn
+				return dfn
+			else
+				@found[key] = []
+				@collections.push @found[key]
+				return build_array(dfn, @found[key])
+			end
+			
+		# hash
+		elsif dfn.is_a?(Hash)
+			@found[key] = {}
+			@collections.push @found[key]
+			return build_hash(dfn, @found[key])
+			
+		# else unknown
+		else
+			puts 'unknown: ' + dfn.class.to_s
+			exit
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# build_object
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_hash
+	#
+	def build_hash(dfn, hsh)
+		# loop through elements
+		dfn.each do |key, ref|
+			hsh[key] = build_object(ref)
+		end
+		
+		# return
+		return hsh
+	end
+	#
+	# build_hash
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# build_array
+	#
+	def build_array(dfn, arr)
+		# loop through elements
+		dfn.each do |ref|
+			arr.push build_object(ref)
+		end
+		
+		# return
+		return arr
+	end
+	#
+	# build_array
+	#---------------------------------------------------------------------------
+end
+#
+# FXF::Parser
+#===============================================================================
+
+
+#===============================================================================
+# FXF::Parser::ObjectHolder
+#
+
+# Objects of this class are placeholders for objects that have been serialized.
+# This class is used by FXF::Parser and is not meant to be used directly.
+
+class FXF::Parser::ObjectHolder
+	attr_reader :scope
+	attr_reader :clss
+	attr_reader :details
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(scope, clss, details)
+		@scope = scope
+		@clss = clss
+		@details = details
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+end
+#
+# FXF::Parser::ObjectHolder
+#===============================================================================

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: fxf
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Mike O'Sullivan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-27 00:00:00.000000000 Z
+dependencies: []
+description: A JSON implementation for non-hierarchical data and for arbitrary objects
+email: mike@idocs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/fxf.rb
+homepage: https://rubygems.org/gems/fxf
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Serializer for tangled data and objects
+test_files: []