firm 0.9.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 823d2ee34c56ec4457626d9dd06586825f33a01ad3dd34dfd135f9cdefafdd66
+  data.tar.gz: f0c33ff04609cfa111f98886ca3d92cab1478d81b5bde280c2000bdcaca614c5
+SHA512:
+  metadata.gz: 9a7c5b5446f5bc1aae9e6f2fcaa3baa0d3589b235144367443292e2785570ce5765f3612fc10c9fc010e7ce4f0e820239167a5e6f4ef5ad77fe2ecdbc0820349
+  data.tar.gz: 129cb0defe0a5628f9c7731e23ba73b90747f973cfc2931021612f4d271efbd39b80bbb60c8ca751f64fa549110fd79362ca751dfa78d11e68e9c127856da5de

data/.yardopts

@@ -0,0 +1,12 @@
+--load rakelib/yard/yard-relative_markdown_links.rb
+--load rakelib/yard/yard-custom-templates.rb
+--charset UTF-8
+--markup markdown
+--readme README.md
+--title "FIRM API Documentation"
+--output-dir rdoc
+--protected
+lib/firm/**/*.rb
+-
+LICENSE
+USAGE.md

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 mcorino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+[![Tests](https://github.com/mcorino/firm/actions/workflows/ruby.yml/badge.svg)](https://github.com/mcorino/firm/actions/workflows/ruby.yml)
+
+[![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/firm.svg)](https://badge.fury.io/rb/firm)
+[![Documentation](https://img.shields.io/badge/docs-pages-blue.svg)](https://mcorino.github.io/firm)
+
+# FIRM - Format Independent Ruby Marshalling
+
+## Introduction
+
+FIRM is a pure Ruby library providing output format independent object (de-)serialization support.
+
+FIRM is explicitly **NOT** intended as a non-discriminative marshaling library (dumping any object's attributes)
+but rather as structured and safe serialization library requiring users to think about what state they want
+persisted (and possibly in what form) and what not.
+Straightforward attribute serialization is simple with minimal intrusion on user code.
+In addition various customization options are available to tweak (de-)serialization for a perfect fit if needed. 
+
+Out of the box (de-)serializing Ruby objects to(from) JSON and YAML is supported without any additional
+dependencies.
+When the `nokogiri` gem is installed (and loaded before FIRM) XML (de-)serializing will also be available.
+
+FIRM supports (de-)serializing many core Ruby objects out of the box including:
+
+- `NilClass`
+- `TrueClass` & `FalseClass`
+- `Integer`
+- `Float`
+- `Rational`
+- `Complex`
+- `BigDecimal` (if loaded; not default anymore starting from Ruby 3.4)
+- `String`
+- `Symbol`
+- `Array`
+- `Hash`
+- `Range`
+- `Regexp`
+- `Time`
+- `Struct`
+- `Set`
+- `OpenStruct`
+- `Date`
+- `DateTime`
+
+FIRM also supports a simple scheme to provide (de-)serialization support for user defined classes. 
+
+FIRM provides object aliasing support for JSON and XML in a similar fashion as the standard support provided
+by YAML. All user defined serializable class as well as **named** `Struct`-derived classes support aliasing.
+
+FIRM also automatically recognizes and handles cyclic references of aliasable objects.
+
+## Installing FIRM
+
+FIRM is distributed as a Ruby gem on [RubyGems](https://rubygems.org). This gem can also be downloaded from the release
+assets on [Github](https://github.com/mcorino/firm/releases).
+
+Installing the gem requires no additional installation steps and/or additional software to be installed except for a
+supported version of the Ruby interpreter. So the following command is all it takes to install:
+
+```shell
+gem install firm
+```
+
+Installing the `nokogiri` gem is optional to enable the XML serialization format.   
+
+## Usage examples
+
+### Serialize an array of objects to JSON string
+
+```
+ruby
+require 'firm'
+
+a = [1, '2', :three, 4.321]
+json = a.serialize
+FIRM.deserialize(json)
+```
+
+IRB output:
+
+```shell
+=> true
+=> 
+[1,
+ "2",
+ :three,
+ 4.321]
+=> "[1,\"2\",{\"json_class\":\"Symbol\",\"s\":\"three\"},4.321]"
+=> 
+[1,
+ "2",
+ :three,
+ 4.321]
+```
+
+Alternatively the object can be serialized to the YAML or XML (if the `nokogiri` gem is installed) format like this.
+
+```ruby
+require 'firm'
+
+a = [1, '2', :three, 4.321]
+json = a.serialize(format: :yaml)
+FIRM.deserialize(json, format: :yaml)
+```
+
+IRB output:
+
+```shell
+=> true
+=> 
+[1,
+ "2",
+ :three,
+ 4.321]
+=> "---\n- 1\n- '2'\n- :three\n- 4.321\n"
+=> 
+[1,
+ "2",
+ :three,
+ 4.321]
+```
+
+### Serialize a user defined object
+
+```ruby
+require 'nokogiri' # enable XML output format
+require 'firm'
+
+class Point
+
+  # define the class as serializable 
+  include FIRM::Serializable
+
+  # declare the serializable properties of instances of this class
+  properties :x, :y
+
+  # allow instantiation using the default ctor (no args)
+  # (custom creation schemes can be defined)
+  def initialize(*args)
+    if args.empty?
+      @x = @y = 0
+    else
+      @x, @y = *args
+    end
+  end
+
+  # define the default getter/setter support FIRM will use when (de-)serializing properties
+  # (customization options are available)
+  attr_accessor :x, :y
+
+end
+
+rect = {topleft: Point.new(1,1), bottomright: Point.new(32, 64)}
+xml = rect.serialize(format: :xml)
+# all serializable classes provide the #deserialize class method
+Hash.deserialize(xml, format: :xml)
+```
+
+IRB output:
+
+```shell
+=> true
+=> true
+=> 
+[:x,
+ :x=,
+ :y,
+ :y=]
+=> 
+{:topleft=>
+  #<Point:0x00007f6da9902518
+   @x=
+    1,
+   @y=
+    1>,
+ :bottomright=>
+  #<Point:0x00007f6da9902450
+   @x=
+    32,
+   @y=
+    64>}
+=> "<?xml version=\"1.0\"?>\n<Hash><P><Symbol>topleft</Symbol><Object class=\"Point\"><x><Integer>1</Integer></x><y><Integer>1</Integer></y></Object></P><P><Symbol>bottomright</Symbol><Object class=\"Point\"><x><Integer>32</Integer></x><y><Integer>64</Integer></y></Object></P></Hash>\n"
+=> nil
+=> 
+{:topleft=>
+  #<Point:0x00007f6da98f2208
+   @x=
+    1,
+   @y=
+    1>,
+ :bottomright=>
+  #<Point:0x00007f6da98f0d90
+   @x=
+    32,
+   @y=
+    64>}
+```
+
+See [USAGE](USAGE.md) for more information.
+
+## FIRM licence
+
+FIRM is free and open-source. It is distributed under the liberal
+MIT licence which is compatible with both free and commercial development.
+See [LICENSE](LICENSE) for more details.
+
+### Required Credits and Attribution
+
+FIRM requires no attribution, beyond retaining existing copyright notices.