firm 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|
+
[](https://github.com/mcorino/firm/actions/workflows/ruby.yml)
|
2
|
+
|
3
|
+
[](LICENSE)
|
4
|
+
[](https://badge.fury.io/rb/firm)
|
5
|
+
[](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.
|