https://github.com/mcorino/firm
Format Independent Ruby Marshalling
https://github.com/mcorino/firm
cross-platform marshaling ruby serialization
Last synced: about 1 year ago
JSON representation
Format Independent Ruby Marshalling
- Host: GitHub
- URL: https://github.com/mcorino/firm
- Owner: mcorino
- License: mit
- Created: 2024-09-02T12:45:17.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2025-01-23T07:36:09.000Z (over 1 year ago)
- Last Synced: 2025-03-24T12:39:16.738Z (over 1 year ago)
- Topics: cross-platform, marshaling, ruby, serialization
- Language: Ruby
- Homepage: https://mcorino.github.io/firm/
- Size: 118 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/mcorino/firm/actions/workflows/ruby.yml)
[](LICENSE)
[](https://badge.fury.io/rb/firm)
[](https://mcorino.github.io/firm)
# FIRM - Format Independent Ruby Marshalling
## Introduction
FIRM is a pure Ruby library that works across different Ruby implementations like MRI Ruby and JRuby providing 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 a 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` (optional starting from Ruby 3.5 which removes this class from the standard library)
- `Date`
- `DateTime`
For simplicity and security reasons FIRM does **not** support direct (de-)serializing of `Class` objects but will rather
serialize (and deserialize) these as their scoped string names. Customized property setters can be used to
resolve Class objects from these names if really needed.
Serialization support for user defined classes is available through a simple DSL scheme.
FIRM provides object aliasing support for JSON and XML in a similar fashion as the standard support provided
by YAML.
In addition FIRM automatically recognizes and handles cyclic references of aliasable objects.
FIRM serialization is also thread safe and supports re-entrancy (i.e. nested serialization).
## 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=>
#,
:bottomright=>
#}
=> "\n
topleft11
bottomright3264
\n"
=> nil
=>
{:topleft=>
#,
:bottomright=>
#}
```
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.