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 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.