Skip to content

Commit f855c9c

Browse files
pbolingpboling
committed
📝 Document serialization extensions:
- dump_value_extensions - load_value_extensions - dump_hash_extensions - load_hash_extensions
1 parent edbd75c commit f855c9c

32 files changed

+281
-43
lines changed

‎.rubocop_gradual.lock

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
[375, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910],
6666
[391, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233]
6767
],
68-
"spec/oauth2/response_spec.rb:2248532534": [
68+
"spec/oauth2/response_spec.rb:4032173622": [
6969
[3, 1, 31, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/response*_spec.rb`.", 3190869319]
7070
],
7171
"spec/oauth2/strategy/assertion_spec.rb:3524328522": [

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning v2](https://semver.org/spec/v2.
2121
- [gh652][gh652] - Support IETF rfc7515 JSON Web Signature - JWS by @mridang
2222
- Support JWT `kid` for key discovery and management
2323
- More Documentation by @pboling
24+
- Documented Serialization Extensions
2425
- Added Gatzo.com FLOSS logo by @Aboling0, CC BY-SA 4.0
2526
- Documentation site @ https://oauth2.galtzo.com now complete
2627
### Changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ NOTE: To build without signing the gem you must set `SKIP_GEM_SIGNING` to some v
114114
11. Run `bin/gem_checksums` (more context [1][🔒️rubygems-checksums-pr], [2][🔒️rubygems-guides-pr])
115115
to create SHA-256 and SHA-512 checksums. This functionality is provided by the `stone_checksums`
116116
[gem][💎stone_checksums].
117-
- Checksums will be committed automatically by the script, but not pushed
117+
- Checksums will be committed automatically by the script but not pushed
118118
12. Run `bundle exec rake release` which will create a git tag for the version,
119119
push git commits and tags, and push the `.gem` file to [rubygems.org][💎rubygems]
120120

‎README.md

Lines changed: 80 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ One of these might be what you are looking for:
163163
### Version 2.0.x
164164

165165
<details>
166-
<summary>2.0.x CHANGELOGs and READMEs</summary>
166+
<summary>2.0.x CHANGELOG and README</summary>
167167

168168
| Version | Release Date | CHANGELOG | README |
169169
|---------|--------------|---------------------------------------|---------------------------------|
@@ -196,7 +196,8 @@ One of these might be what you are looking for:
196196
[2.0.1-changelog]: https://gitlab.com/oauth-xx/oauth2/-/blob/main/CHANGELOG.md?ref_type=heads#201---2022-06-22
197197
[2.0.0-changelog]: https://gitlab.com/oauth-xx/oauth2/-/blob/main/CHANGELOG.md?ref_type=heads#200---2022-06-21
198198

199-
[2.0.10-readme]: https://gitlab.com/oauth-xx/oauth2/-/blob/v2.0.11/README.md
199+
[2.0.12-readme]: https://gitlab.com/oauth-xx/oauth2/-/blob/v2.0.12/README.md
200+
[2.0.11-readme]: https://gitlab.com/oauth-xx/oauth2/-/blob/v2.0.11/README.md
200201
[2.0.10-readme]: https://gitlab.com/oauth-xx/oauth2/-/blob/v2.0.10/README.md
201202
[2.0.9-readme]: https://gitlab.com/oauth-xx/oauth2/-/blob/v2.0.9/README.md
202203
[2.0.8-readme]: https://gitlab.com/oauth-xx/oauth2/-/blob/v2.0.8/README.md
@@ -492,16 +493,91 @@ response.parsed.class.name # => SnakyHash::StringKeyed (from snaky_hash g
492493

493494
As of v2.0.11, if you need to serialize the parsed result, you can!
494495

495-
There are two ways to do this, and the second option recommended.
496+
There are two ways to do this, globally, or discretely. The discrete way is recommended.
496497

497498
1. Globally configure `SnakyHash::StringKeyed` to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails):
498499

499-
```ruby
500+
```ruby
500501
SnakyHash::StringKeyed.class_eval do
501502
extend SnakyHash::Serializer
503+
end
504+
```
505+
506+
2. Discretely configure a custom Snaky Hash class to use the serializer:
507+
508+
```ruby
509+
class MySnakyHash < SnakyHash::StringKeyed
510+
# Give this hash class `dump` and `load` abilities!
511+
extend SnakyHash::Serializer
512+
end
513+
514+
# And tell your client to use the custom class in each call:
515+
client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2")
516+
token = client.get_token({snaky_hash_klass: MySnakyHash})
517+
```
518+
519+
##### Serialization Extensions
520+
521+
There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6.
522+
They are likely not needed if you are on a newer Ruby.
523+
See `response_spec.rb` if you need to study the hacks for older Rubies.
524+
525+
```ruby
526+
class MySnakyHash < SnakyHash::StringKeyed
527+
# Give this hash class `dump` and `load` abilities!
528+
extend SnakyHash::Serializer
529+
530+
#### Serialization Extentions
531+
#
532+
# Act on the non-hash values (including the values of hashes) as they are dumped to JSON
533+
# In other words, this retains nested hashes, and only the deepest leaf nodes become bananas.
534+
# WARNING: This is a silly example!
535+
dump_value_extensions.add(:to_fruit) do |value|
536+
"banana" # => Make values "banana" on dump
537+
end
538+
539+
# Act on the non-hash values (including the values of hashes) as they are loaded from the JSON dump
540+
# In other words, this retains nested hashes, and only the deepest leaf nodes become ***.
541+
# WARNING: This is a silly example!
542+
load_value_extensions.add(:to_stars) do |value|
543+
"***" # Turn dumped bananas into *** when they are loaded
544+
end
545+
546+
# Act on the entire hash as it is prepared for dumping to JSON
547+
# WARNING: This is a silly example!
548+
dump_hash_extensions.add(:to_cheese) do |value|
549+
if value.is_a?(Hash)
550+
value.transform_keys do |key|
551+
split = key.split("_")
552+
first_word = split[0]
553+
key.sub(first_word, "cheese")
554+
end
555+
else
556+
value
557+
end
558+
end
559+
560+
# Act on the entire hash as it is loaded from the JSON dump
561+
# WARNING: This is a silly example!
562+
load_hash_extensions.add(:to_pizza) do |value|
563+
if value.is_a?(Hash)
564+
res = klass.new
565+
value.keys.each_with_object(res) do |key, result|
566+
split = key.split("_")
567+
last_word = split[-1]
568+
new_key = key.sub(last_word, "pizza")
569+
result[new_key] = value[key]
570+
end
571+
res
572+
else
573+
value
574+
end
575+
end
502576
end
503577
```
504578

579+
See `response_spec.rb`, or the [oauth-xx/snaky_hash](https://gitlab.com/oauth-xx/snaky_hash) gem for more ideas.
580+
505581
#### What if I hate snakes and/or indifference?
506582

507583
```ruby

‎docs/OAuth2.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -326,7 +326,7 @@ <h3 class="signature first" id="configure-class_method">
326326
</div>
327327

328328
<div id="footer">
329-
Generated on Sun Jun 1 04:25:45 2025 by
329+
Generated on Sun Jun 1 05:10:25 2025 by
330330
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
331331
0.9.37 (ruby-3.4.3).
332332
</div>

‎docs/OAuth2/AccessToken.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3069,7 +3069,7 @@ <h3 class="signature " id="to_hash-instance_method">
30693069
</div>
30703070

30713071
<div id="footer">
3072-
Generated on Sun Jun 1 04:25:46 2025 by
3072+
Generated on Sun Jun 1 05:10:25 2025 by
30733073
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
30743074
0.9.37 (ruby-3.4.3).
30753075
</div>

‎docs/OAuth2/Authenticator.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -631,7 +631,7 @@ <h3 class="signature first" id="apply-instance_method">
631631
</div>
632632

633633
<div id="footer">
634-
Generated on Sun Jun 1 04:25:46 2025 by
634+
Generated on Sun Jun 1 05:10:25 2025 by
635635
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
636636
0.9.37 (ruby-3.4.3).
637637
</div>

‎docs/OAuth2/Client.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2651,7 +2651,7 @@ <h3 class="signature " id="token_url-instance_method">
26512651
</div>
26522652

26532653
<div id="footer">
2654-
Generated on Sun Jun 1 04:25:46 2025 by
2654+
Generated on Sun Jun 1 05:10:25 2025 by
26552655
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
26562656
0.9.37 (ruby-3.4.3).
26572657
</div>

‎docs/OAuth2/Error.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@ <h3 class="signature " id="response-instance_method">
518518
</div>
519519

520520
<div id="footer">
521-
Generated on Sun Jun 1 04:25:45 2025 by
521+
Generated on Sun Jun 1 05:10:25 2025 by
522522
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
523523
0.9.37 (ruby-3.4.3).
524524
</div>

‎docs/OAuth2/FilteredAttributes.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,7 @@ <h3 class="signature first" id="inspect-instance_method">
268268
</div>
269269

270270
<div id="footer">
271-
Generated on Sun Jun 1 04:25:45 2025 by
271+
Generated on Sun Jun 1 05:10:25 2025 by
272272
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
273273
0.9.37 (ruby-3.4.3).
274274
</div>

‎docs/OAuth2/FilteredAttributes/ClassMethods.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ <h3 class="signature " id="filtered_attributes-instance_method">
218218
</div>
219219

220220
<div id="footer">
221-
Generated on Sun Jun 1 04:25:45 2025 by
221+
Generated on Sun Jun 1 05:10:25 2025 by
222222
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
223223
0.9.37 (ruby-3.4.3).
224224
</div>

‎docs/OAuth2/Response.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1619,7 +1619,7 @@ <h3 class="signature " id="status-instance_method">
16191619
</div>
16201620

16211621
<div id="footer">
1622-
Generated on Sun Jun 1 04:25:46 2025 by
1622+
Generated on Sun Jun 1 05:10:25 2025 by
16231623
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
16241624
0.9.37 (ruby-3.4.3).
16251625
</div>

‎docs/OAuth2/Strategy.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ <h2>Defined Under Namespace</h2>
107107
</div>
108108

109109
<div id="footer">
110-
Generated on Sun Jun 1 04:25:45 2025 by
110+
Generated on Sun Jun 1 05:10:25 2025 by
111111
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
112112
0.9.37 (ruby-3.4.3).
113113
</div>

‎docs/OAuth2/Strategy/Assertion.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -481,7 +481,7 @@ <h3 class="signature " id="get_token-instance_method">
481481
</div>
482482

483483
<div id="footer">
484-
Generated on Sun Jun 1 04:25:46 2025 by
484+
Generated on Sun Jun 1 05:10:25 2025 by
485485
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
486486
0.9.37 (ruby-3.4.3).
487487
</div>

‎docs/OAuth2/Strategy/AuthCode.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -469,7 +469,7 @@ <h3 class="signature " id="get_token-instance_method">
469469
</div>
470470

471471
<div id="footer">
472-
Generated on Sun Jun 1 04:25:46 2025 by
472+
Generated on Sun Jun 1 05:10:25 2025 by
473473
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
474474
0.9.37 (ruby-3.4.3).
475475
</div>

‎docs/OAuth2/Strategy/Base.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ <h3 class="signature first" id="initialize-instance_method">
195195
</div>
196196

197197
<div id="footer">
198-
Generated on Sun Jun 1 04:25:46 2025 by
198+
Generated on Sun Jun 1 05:10:25 2025 by
199199
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
200200
0.9.37 (ruby-3.4.3).
201201
</div>

‎docs/OAuth2/Strategy/ClientCredentials.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ <h3 class="signature " id="get_token-instance_method">
343343
</div>
344344

345345
<div id="footer">
346-
Generated on Sun Jun 1 04:25:46 2025 by
346+
Generated on Sun Jun 1 05:10:25 2025 by
347347
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
348348
0.9.37 (ruby-3.4.3).
349349
</div>

‎docs/OAuth2/Strategy/Implicit.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -410,7 +410,7 @@ <h3 class="signature " id="get_token-instance_method">
410410
</div>
411411

412412
<div id="footer">
413-
Generated on Sun Jun 1 04:25:46 2025 by
413+
Generated on Sun Jun 1 05:10:25 2025 by
414414
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
415415
0.9.37 (ruby-3.4.3).
416416
</div>

‎docs/OAuth2/Strategy/Password.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ <h3 class="signature " id="get_token-instance_method">
364364
</div>
365365

366366
<div id="footer">
367-
Generated on Sun Jun 1 04:25:46 2025 by
367+
Generated on Sun Jun 1 05:10:25 2025 by
368368
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
369369
0.9.37 (ruby-3.4.3).
370370
</div>

‎docs/OAuth2/Version.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ <h2>
111111
</div>
112112

113113
<div id="footer">
114-
Generated on Sun Jun 1 04:25:45 2025 by
114+
Generated on Sun Jun 1 05:10:25 2025 by
115115
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
116116
0.9.37 (ruby-3.4.3).
117117
</div>

‎docs/_index.html

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,9 @@ <h2>File Listing</h2>
7878
<li class="r2"><a href="file.LICENSE.html" title="LICENSE">LICENSE</a></li>
7979

8080

81+
<li class="r1"><a href="file.CITATION.html" title="CITATION">CITATION</a></li>
82+
83+
8184
</ul>
8285

8386
<div class="clear"></div>
@@ -300,7 +303,7 @@ <h2>Namespace Listing A-Z</h2>
300303
</div>
301304

302305
<div id="footer">
303-
Generated on Sun Jun 1 04:25:45 2025 by
306+
Generated on Sun Jun 1 05:10:24 2025 by
304307
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
305308
0.9.37 (ruby-3.4.3).
306309
</div>

‎docs/file.CHANGELOG.html

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ <h3 id="added-1">Added</h3>
8989
</li>
9090
<li>More Documentation by @pboling
9191
<ul>
92+
<li>Documented Serialization Extensions</li>
9293
<li>Added Gatzo.com FLOSS logo by @Aboling0, CC BY-SA 4.0</li>
9394
</ul>
9495
</li>
@@ -835,7 +836,7 @@ <h2 id="001---2010-04-22-tag">
835836
</div></div>
836837

837838
<div id="footer">
838-
Generated on Sun Jun 1 04:25:45 2025 by
839+
Generated on Sun Jun 1 05:10:25 2025 by
839840
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
840841
0.9.37 (ruby-3.4.3).
841842
</div>

‎docs/file.CITATION.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@
8585
</div></div>
8686

8787
<div id="footer">
88-
Generated on Sun Jun 1 04:18:48 2025 by
88+
Generated on Sun Jun 1 05:10:25 2025 by
8989
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
9090
0.9.37 (ruby-3.4.3).
9191
</div>

‎docs/file.CODE_OF_CONDUCT.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ <h2 id="attribution">Attribution</h2>
192192
</div></div>
193193

194194
<div id="footer">
195-
Generated on Sun Jun 1 04:25:45 2025 by
195+
Generated on Sun Jun 1 05:10:25 2025 by
196196
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
197197
0.9.37 (ruby-3.4.3).
198198
</div>

‎docs/file.CONTRIBUTING.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ <h3 id="to-release-a-new-version">To release a new version:</h3>
184184
to create SHA-256 and SHA-512 checksums. This functionality is provided by the <code>stone_checksums</code><br>
185185
<a href="https://github.com/pboling/stone_checksums">gem</a>.
186186
<ul>
187-
<li>Checksums will be committed automatically by the script, but not pushed</li>
187+
<li>Checksums will be committed automatically by the script but not pushed</li>
188188
</ul>
189189
</li>
190190
<li>Run <code>bundle exec rake release</code> which will create a git tag for the version,<br>
@@ -195,7 +195,7 @@ <h3 id="to-release-a-new-version">To release a new version:</h3>
195195
</div></div>
196196

197197
<div id="footer">
198-
Generated on Sun Jun 1 04:25:45 2025 by
198+
Generated on Sun Jun 1 05:10:25 2025 by
199199
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
200200
0.9.37 (ruby-3.4.3).
201201
</div>

‎docs/file.LICENSE.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
<div id="content"><div id='filecontents'>MIT License<br><br>Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc.<br>Copyright (c) 2017 - 2025 Peter H. Boling, of RailsBling.com, and OAuth2 contributors<br><br>Permission is hereby granted, free of charge, to any person obtaining a copy<br>of this software and associated documentation files (the "Software"), to deal<br>in the Software without restriction, including without limitation the rights<br>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell<br>copies of the Software, and to permit persons to whom the Software is<br>furnished to do so, subject to the following conditions:<br><br>The above copyright notice and this permission notice shall be included in all<br>copies or substantial portions of the Software.<br><br>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR<br>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,<br>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE<br>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER<br>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE<br>SOFTWARE.</div></div>
6161

6262
<div id="footer">
63-
Generated on Sun Jun 1 04:25:45 2025 by
63+
Generated on Sun Jun 1 05:10:25 2025 by
6464
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
6565
0.9.37 (ruby-3.4.3).
6666
</div>

0 commit comments

Comments
 (0)