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>

0 commit comments

Comments
 (0)