firm 0.9.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.yardopts +12 -0
- data/LICENSE +21 -0
- data/README.md +209 -0
- data/lib/firm/serializable.rb +733 -0
- data/lib/firm/serialize/core.rb +43 -0
- data/lib/firm/serialize/id.rb +104 -0
- data/lib/firm/serializer/json.rb +394 -0
- data/lib/firm/serializer/xml.rb +544 -0
- data/lib/firm/serializer/yaml.rb +118 -0
- data/lib/firm/version.rb +9 -0
- data/lib/firm.rb +5 -0
- data/rakelib/yard/templates/default/fulldoc/html/css/firm.css +97 -0
- data/rakelib/yard/templates/default/fulldoc/html/setup.rb +25 -0
- data/rakelib/yard/templates/default/layout/html/setup.rb +5 -0
- data/rakelib/yard/yard/relative_markdown_links/version.rb +8 -0
- data/rakelib/yard/yard/relative_markdown_links.rb +39 -0
- data/rakelib/yard/yard-custom-templates.rb +2 -0
- data/rakelib/yard/yard-relative_markdown_links.rb +4 -0
- data/tests/serializer_tests.rb +945 -0
- data/tests/test_serialize.rb +8 -0
- data/tests/test_serialize_xml.rb +22 -0
- data/tests/test_serialize_yaml.rb +18 -0
- metadata +110 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 823d2ee34c56ec4457626d9dd06586825f33a01ad3dd34dfd135f9cdefafdd66
|
4
|
+
data.tar.gz: f0c33ff04609cfa111f98886ca3d92cab1478d81b5bde280c2000bdcaca614c5
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 9a7c5b5446f5bc1aae9e6f2fcaa3baa0d3589b235144367443292e2785570ce5765f3612fc10c9fc010e7ce4f0e820239167a5e6f4ef5ad77fe2ecdbc0820349
|
7
|
+
data.tar.gz: 129cb0defe0a5628f9c7731e23ba73b90747f973cfc2931021612f4d271efbd39b80bbb60c8ca751f64fa549110fd79362ca751dfa78d11e68e9c127856da5de
|
data/.yardopts
ADDED
@@ -0,0 +1,12 @@
|
|
1
|
+
--load rakelib/yard/yard-relative_markdown_links.rb
|
2
|
+
--load rakelib/yard/yard-custom-templates.rb
|
3
|
+
--charset UTF-8
|
4
|
+
--markup markdown
|
5
|
+
--readme README.md
|
6
|
+
--title "FIRM API Documentation"
|
7
|
+
--output-dir rdoc
|
8
|
+
--protected
|
9
|
+
lib/firm/**/*.rb
|
10
|
+
-
|
11
|
+
LICENSE
|
12
|
+
USAGE.md
|
data/LICENSE
ADDED
@@ -0,0 +1,21 @@
|
|
1
|
+
MIT License
|
2
|
+
|
3
|
+
Copyright (c) 2024 mcorino
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
13
|
+
copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,209 @@
|
|
1
|
+
[![Tests](https://github.com/mcorino/firm/actions/workflows/ruby.yml/badge.svg)](https://github.com/mcorino/firm/actions/workflows/ruby.yml)
|
2
|
+
|
3
|
+
[![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](LICENSE)
|
4
|
+
[![Gem Version](https://badge.fury.io/rb/firm.svg)](https://badge.fury.io/rb/firm)
|
5
|
+
[![Documentation](https://img.shields.io/badge/docs-pages-blue.svg)](https://mcorino.github.io/firm)
|
6
|
+
|
7
|
+
# FIRM - Format Independent Ruby Marshalling
|
8
|
+
|
9
|
+
## Introduction
|
10
|
+
|
11
|
+
FIRM is a pure Ruby library providing output format independent object (de-)serialization support.
|
12
|
+
|
13
|
+
FIRM is explicitly **NOT** intended as a non-discriminative marshaling library (dumping any object's attributes)
|
14
|
+
but rather as structured and safe serialization library requiring users to think about what state they want
|
15
|
+
persisted (and possibly in what form) and what not.
|
16
|
+
Straightforward attribute serialization is simple with minimal intrusion on user code.
|
17
|
+
In addition various customization options are available to tweak (de-)serialization for a perfect fit if needed.
|
18
|
+
|
19
|
+
Out of the box (de-)serializing Ruby objects to(from) JSON and YAML is supported without any additional
|
20
|
+
dependencies.
|
21
|
+
When the `nokogiri` gem is installed (and loaded before FIRM) XML (de-)serializing will also be available.
|
22
|
+
|
23
|
+
FIRM supports (de-)serializing many core Ruby objects out of the box including:
|
24
|
+
|
25
|
+
- `NilClass`
|
26
|
+
- `TrueClass` & `FalseClass`
|
27
|
+
- `Integer`
|
28
|
+
- `Float`
|
29
|
+
- `Rational`
|
30
|
+
- `Complex`
|
31
|
+
- `BigDecimal` (if loaded; not default anymore starting from Ruby 3.4)
|
32
|
+
- `String`
|
33
|
+
- `Symbol`
|
34
|
+
- `Array`
|
35
|
+
- `Hash`
|
36
|
+
- `Range`
|
37
|
+
- `Regexp`
|
38
|
+
- `Time`
|
39
|
+
- `Struct`
|
40
|
+
- `Set`
|
41
|
+
- `OpenStruct`
|
42
|
+
- `Date`
|
43
|
+
- `DateTime`
|
44
|
+
|
45
|
+
FIRM also supports a simple scheme to provide (de-)serialization support for user defined classes.
|
46
|
+
|
47
|
+
FIRM provides object aliasing support for JSON and XML in a similar fashion as the standard support provided
|
48
|
+
by YAML. All user defined serializable class as well as **named** `Struct`-derived classes support aliasing.
|
49
|
+
|
50
|
+
FIRM also automatically recognizes and handles cyclic references of aliasable objects.
|
51
|
+
|
52
|
+
## Installing FIRM
|
53
|
+
|
54
|
+
FIRM is distributed as a Ruby gem on [RubyGems](https://rubygems.org). This gem can also be downloaded from the release
|
55
|
+
assets on [Github](https://github.com/mcorino/firm/releases).
|
56
|
+
|
57
|
+
Installing the gem requires no additional installation steps and/or additional software to be installed except for a
|
58
|
+
supported version of the Ruby interpreter. So the following command is all it takes to install:
|
59
|
+
|
60
|
+
```shell
|
61
|
+
gem install firm
|
62
|
+
```
|
63
|
+
|
64
|
+
Installing the `nokogiri` gem is optional to enable the XML serialization format.
|
65
|
+
|
66
|
+
## Usage examples
|
67
|
+
|
68
|
+
### Serialize an array of objects to JSON string
|
69
|
+
|
70
|
+
```
|
71
|
+
ruby
|
72
|
+
require 'firm'
|
73
|
+
|
74
|
+
a = [1, '2', :three, 4.321]
|
75
|
+
json = a.serialize
|
76
|
+
FIRM.deserialize(json)
|
77
|
+
```
|
78
|
+
|
79
|
+
IRB output:
|
80
|
+
|
81
|
+
```shell
|
82
|
+
=> true
|
83
|
+
=>
|
84
|
+
[1,
|
85
|
+
"2",
|
86
|
+
:three,
|
87
|
+
4.321]
|
88
|
+
=> "[1,\"2\",{\"json_class\":\"Symbol\",\"s\":\"three\"},4.321]"
|
89
|
+
=>
|
90
|
+
[1,
|
91
|
+
"2",
|
92
|
+
:three,
|
93
|
+
4.321]
|
94
|
+
```
|
95
|
+
|
96
|
+
Alternatively the object can be serialized to the YAML or XML (if the `nokogiri` gem is installed) format like this.
|
97
|
+
|
98
|
+
```ruby
|
99
|
+
require 'firm'
|
100
|
+
|
101
|
+
a = [1, '2', :three, 4.321]
|
102
|
+
json = a.serialize(format: :yaml)
|
103
|
+
FIRM.deserialize(json, format: :yaml)
|
104
|
+
```
|
105
|
+
|
106
|
+
IRB output:
|
107
|
+
|
108
|
+
```shell
|
109
|
+
=> true
|
110
|
+
=>
|
111
|
+
[1,
|
112
|
+
"2",
|
113
|
+
:three,
|
114
|
+
4.321]
|
115
|
+
=> "---\n- 1\n- '2'\n- :three\n- 4.321\n"
|
116
|
+
=>
|
117
|
+
[1,
|
118
|
+
"2",
|
119
|
+
:three,
|
120
|
+
4.321]
|
121
|
+
```
|
122
|
+
|
123
|
+
### Serialize a user defined object
|
124
|
+
|
125
|
+
```ruby
|
126
|
+
require 'nokogiri' # enable XML output format
|
127
|
+
require 'firm'
|
128
|
+
|
129
|
+
class Point
|
130
|
+
|
131
|
+
# define the class as serializable
|
132
|
+
include FIRM::Serializable
|
133
|
+
|
134
|
+
# declare the serializable properties of instances of this class
|
135
|
+
properties :x, :y
|
136
|
+
|
137
|
+
# allow instantiation using the default ctor (no args)
|
138
|
+
# (custom creation schemes can be defined)
|
139
|
+
def initialize(*args)
|
140
|
+
if args.empty?
|
141
|
+
@x = @y = 0
|
142
|
+
else
|
143
|
+
@x, @y = *args
|
144
|
+
end
|
145
|
+
end
|
146
|
+
|
147
|
+
# define the default getter/setter support FIRM will use when (de-)serializing properties
|
148
|
+
# (customization options are available)
|
149
|
+
attr_accessor :x, :y
|
150
|
+
|
151
|
+
end
|
152
|
+
|
153
|
+
rect = {topleft: Point.new(1,1), bottomright: Point.new(32, 64)}
|
154
|
+
xml = rect.serialize(format: :xml)
|
155
|
+
# all serializable classes provide the #deserialize class method
|
156
|
+
Hash.deserialize(xml, format: :xml)
|
157
|
+
```
|
158
|
+
|
159
|
+
IRB output:
|
160
|
+
|
161
|
+
```shell
|
162
|
+
=> true
|
163
|
+
=> true
|
164
|
+
=>
|
165
|
+
[:x,
|
166
|
+
:x=,
|
167
|
+
:y,
|
168
|
+
:y=]
|
169
|
+
=>
|
170
|
+
{:topleft=>
|
171
|
+
#<Point:0x00007f6da9902518
|
172
|
+
@x=
|
173
|
+
1,
|
174
|
+
@y=
|
175
|
+
1>,
|
176
|
+
:bottomright=>
|
177
|
+
#<Point:0x00007f6da9902450
|
178
|
+
@x=
|
179
|
+
32,
|
180
|
+
@y=
|
181
|
+
64>}
|
182
|
+
=> "<?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"
|
183
|
+
=> nil
|
184
|
+
=>
|
185
|
+
{:topleft=>
|
186
|
+
#<Point:0x00007f6da98f2208
|
187
|
+
@x=
|
188
|
+
1,
|
189
|
+
@y=
|
190
|
+
1>,
|
191
|
+
:bottomright=>
|
192
|
+
#<Point:0x00007f6da98f0d90
|
193
|
+
@x=
|
194
|
+
32,
|
195
|
+
@y=
|
196
|
+
64>}
|
197
|
+
```
|
198
|
+
|
199
|
+
See [USAGE](USAGE.md) for more information.
|
200
|
+
|
201
|
+
## FIRM licence
|
202
|
+
|
203
|
+
FIRM is free and open-source. It is distributed under the liberal
|
204
|
+
MIT licence which is compatible with both free and commercial development.
|
205
|
+
See [LICENSE](LICENSE) for more details.
|
206
|
+
|
207
|
+
### Required Credits and Attribution
|
208
|
+
|
209
|
+
FIRM requires no attribution, beyond retaining existing copyright notices.
|