inline_transforms 0.1.0 → 0.3.0

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.
Files changed (21) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +46 -3
  3. data/docs/InlineTransforms.html +519 -0
  4. data/docs/Object.html +148 -0
  5. data/docs/_index.html +122 -0
  6. data/docs/class_list.html +54 -0
  7. data/docs/css/common.css +1 -0
  8. data/docs/css/full_list.css +206 -0
  9. data/docs/css/style.css +1089 -0
  10. data/docs/file.README.html +257 -0
  11. data/docs/file_list.html +59 -0
  12. data/docs/frames.html +22 -0
  13. data/docs/index.html +257 -0
  14. data/docs/js/app.js +801 -0
  15. data/docs/js/full_list.js +334 -0
  16. data/docs/js/jquery.js +4 -0
  17. data/docs/method_list.html +78 -0
  18. data/docs/top-level-namespace.html +114 -0
  19. data/lib/inline_transforms/version.rb +1 -1
  20. data/lib/inline_transforms.rb +47 -8
  21. metadata +17 -1
data/docs/index.html ADDED
@@ -0,0 +1,257 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.9.45
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css">
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css">
16
+
17
+ <script type="text/javascript">
18
+ pathId = "README";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div id="main_progress" aria-hidden="true"></div>
31
+
32
+ <div class="nav_wrap">
33
+ <iframe id="nav" src="class_list.html?1"></iframe>
34
+ <div id="resizer"></div>
35
+ </div>
36
+
37
+ <div id="main" tabindex="-1">
38
+ <div id="header">
39
+ <div id="menu">
40
+
41
+ <a href="_index.html">Index</a> &raquo;
42
+ <span class="title">File: README</span>
43
+
44
+ </div>
45
+
46
+ <div id="search">
47
+
48
+ <a class="full_list_link" id="class_list_link"
49
+ href="class_list.html">
50
+
51
+ <svg width="24" height="24">
52
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
53
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
54
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
55
+ </svg>
56
+ </a>
57
+
58
+ </div>
59
+ <div class="clear"></div>
60
+ </div>
61
+
62
+ <div id="content"><div id='filecontents'><p><a href="https://rubygems.org/gems/inline_transforms"><img src="https://img.shields.io/github/v/release/nestor-custodio/inline_transforms?color=green&amp;label=gem%20version" alt="Gem Version" /></a>
63
+ <a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/github/license/nestor-custodio/inline_transforms" alt="MIT License" /></a></p>
64
+ <h1 id="Inline_Transforms">Inline Transforms</h1>
65
+ <p>Ruby is an incredibly expressive (and easy to read!) language, but lacks a way for you to transform a value <em>inline</em> without resorting to nested ternaries (🫠). This gem allows you to do exactly that in a way that still feels like <em>Ruby</em> (i.e. via <em>value manipulation</em> through method calls rather than classic flow control blocks).</p>
66
+ <p>In simplest terms:</p>
67
+ <pre class="code ruby"><code class="ruby"><span class='comment'># &quot;Only If&quot; Logic:
68
+ </span>
69
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_original_value'>original_value</span>
70
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_different_value'>different_value</span> <span class='kw'>unless</span> <span class='id identifier rubyid_original_value'>original_value</span> <span class='op'>==</span> <span class='id identifier rubyid_a_good_thing'>a_good_thing</span>
71
+
72
+ <span class='comment'># ... or ...
73
+ </span>
74
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='kw'>if</span> <span class='id identifier rubyid_original_value'>original_value</span> <span class='op'>==</span> <span class='id identifier rubyid_a_good_thing'>a_good_thing</span>
75
+ <span class='id identifier rubyid_original_value'>original_value</span>
76
+ <span class='kw'>else</span>
77
+ <span class='id identifier rubyid_different_value'>different_value</span>
78
+ <span class='kw'>end</span>
79
+
80
+ <span class='comment'># ... becomes ...
81
+ </span>
82
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_original_value'>original_value</span><span class='period'>.</span><span class='id identifier rubyid_only_if'>only_if</span> <span class='id identifier rubyid_a_good_thing'>a_good_thing</span><span class='comma'>,</span>
83
+ <span class='label'>else:</span> <span class='id identifier rubyid_different_value'>different_value</span>
84
+ </code></pre>
85
+ <pre class="code ruby"><code class="ruby"><span class='comment'># &quot;Unless&quot; Logic:
86
+ </span>
87
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_original_value'>original_value</span>
88
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_different_value'>different_value</span> <span class='kw'>if</span> <span class='id identifier rubyid_original_value'>original_value</span> <span class='op'>==</span> <span class='id identifier rubyid_a_bad_thing'>a_bad_thing</span>
89
+
90
+ <span class='comment'># ... or ...
91
+ </span>
92
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='kw'>if</span> <span class='id identifier rubyid_original_value'>original_value</span> <span class='op'>==</span> <span class='id identifier rubyid_a_bad_thing'>a_bad_thing</span>
93
+ <span class='id identifier rubyid_different_value'>different_value</span>
94
+ <span class='kw'>else</span>
95
+ <span class='id identifier rubyid_original_value'>original_value</span>
96
+ <span class='kw'>end</span>
97
+
98
+ <span class='comment'># ... becomes ...
99
+ </span>
100
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_original_value'>original_value</span><span class='period'>.</span><span class='id identifier rubyid_unless'>unless</span> <span class='id identifier rubyid_a_bad_thing'>a_bad_thing</span><span class='comma'>,</span>
101
+ <span class='label'>then:</span> <span class='id identifier rubyid_different_value'>different_value</span>
102
+ </code></pre>
103
+ <pre class="code ruby"><code class="ruby"><span class='comment'># &quot;Transform&quot; Logic:
104
+ </span>
105
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='kw'>case</span> <span class='id identifier rubyid_original_value'>original_value</span>
106
+ <span class='kw'>when</span> <span class='kw'>true</span> <span class='kw'>then</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>success</span><span class='tstring_end'>&#39;</span></span>
107
+ <span class='kw'>when</span> <span class='kw'>false</span> <span class='kw'>then</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>failure</span><span class='tstring_end'>&#39;</span></span>
108
+ <span class='kw'>when</span> <span class='const'>String</span> <span class='kw'>then</span> <span class='tstring'><span class='tstring_beg'>%(</span><span class='tstring_content'>error: &quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_original_value'>original_value</span><span class='embexpr_end'>}</span><span class='tstring_content'>&quot;</span><span class='tstring_end'>)</span></span>
109
+ <span class='kw'>end</span>
110
+
111
+ <span class='comment'># ... becomes ...
112
+ </span>
113
+ <span class='id identifier rubyid_final_value'>final_value</span> <span class='op'>=</span> <span class='id identifier rubyid_original_value'>original_value</span><span class='period'>.</span><span class='id identifier rubyid_transform'>transform</span> <span class='kw'>true</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>success</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span>
114
+ <span class='kw'>false</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>failure</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span>
115
+ <span class='const'>String</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>%(</span><span class='tstring_content'>error: &quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_original_value'>original_value</span><span class='embexpr_end'>}</span><span class='tstring_content'>&quot;</span><span class='tstring_end'>)</span></span>
116
+ </code></pre>
117
+ <p><a href="https://nestor-custodio.github.io/inline_transforms">Full documentation is available here</a>, but do read below for a crash course on availble featues!</p>
118
+ <h2 id="Installation">Installation</h2>
119
+ <ul>
120
+ <li>
121
+ <p>If your project uses <a href="https://github.com/bundler/bundler">Bundler</a>:</p>
122
+ <ul>
123
+ <li>Add one of the following to your application's Gemfile:
124
+ <pre class="code ruby"><code class="ruby"><span class='comment'># For on-demand usage:
125
+ </span>
126
+ <span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>inline_transforms</span><span class='tstring_end'>&#39;</span></span>
127
+ </code></pre>
128
+ </li>
129
+ <li>And then run a:
130
+ <pre class="code shell"><code class="shell">$ bundle install
131
+ </code></pre>
132
+ </li>
133
+ </ul>
134
+ </li>
135
+ <li>
136
+ <p>Or, you can keep things simple with a manual install:</p>
137
+ <pre class="code shell"><code class="shell">$ gem install inline_transforms
138
+ </code></pre>
139
+ </li>
140
+ </ul>
141
+ <h2 id="Usage">Usage</h2>
142
+ <h3 id="Object_only_if">Object#only_if</h3>
143
+ <p><code>only_if</code> lets you specify a &quot;good&quot; value and an <code>else</code> replacement.</p>
144
+ <ul>
145
+ <li>If your <code>else</code> replacement is a <code>Proc</code>, it is resolved (via <code>call</code>) before being returned.
146
+ <ul>
147
+ <li>If it has arity 0, it is <code>call</code>ed with no params.</li>
148
+ <li>If it has arity 1, it is <code>call</code>ed with the original value.</li>
149
+ <li>If it has arity -1 (a <code>lambda</code> with optional param), it is <code>call</code>ed with the original value.</li>
150
+ </ul>
151
+ </li>
152
+ <li>This method uses <strong>case comparison</strong> (<code>===</code>), so you can check for range inclusion or class.</li>
153
+ </ul>
154
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_only_if'>only_if</span> <span class='id identifier rubyid_good_value'>good_value</span><span class='comma'>,</span> <span class='label'>else:</span> <span class='id identifier rubyid_fallback_value'>fallback_value</span>
155
+ <span class='comment'># ... or ...
156
+ </span><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_only_if'>only_if</span> <span class='id identifier rubyid_good_value'>good_value</span><span class='comma'>,</span> <span class='label'>else:</span> <span class='tlambda'>-&gt;</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_some_method_call'>some_method_call</span> <span class='id identifier rubyid_with_params'>with_params</span> <span class='rbrace'>}</span>
157
+ </code></pre>
158
+ <h3 id="Object_unless">Object#unless</h3>
159
+ <p><code>unless</code> lets you specify a &quot;bad&quot; value and a <code>then</code> replacement.</p>
160
+ <ul>
161
+ <li>If your <code>then</code> replacement is a <code>Proc</code>, it is resolved (via <code>call</code>) before being returned.
162
+ <ul>
163
+ <li>If it has arity 0, it is <code>call</code>ed with no params.</li>
164
+ <li>If it has arity 1, it is <code>call</code>ed with the original value.</li>
165
+ <li>If it has arity -1 (a <code>lambda</code> with optional param), it is <code>call</code>ed with the original value.</li>
166
+ </ul>
167
+ </li>
168
+ <li>This method uses <strong>case comparison</strong> (<code>===</code>), so you can check for range inclusion or class.</li>
169
+ </ul>
170
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_unless'>unless</span> <span class='id identifier rubyid_bad_value'>bad_value</span><span class='comma'>,</span> <span class='label'>then:</span> <span class='id identifier rubyid_fallback_value'>fallback_value</span>
171
+ <span class='comment'># ... or ...
172
+ </span><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_unless'>unless</span> <span class='id identifier rubyid_bad_value'>bad_value</span><span class='comma'>,</span> <span class='label'>then:</span> <span class='tlambda'>-&gt;</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_some_method_call'>some_method_call</span> <span class='id identifier rubyid_with_params'>with_params</span> <span class='rbrace'>}</span>
173
+ </code></pre>
174
+ <h3 id="Object_transform">Object#transform</h3>
175
+ <p><code>transform</code> lets you specify a transformation hash and will return the value for the first matching key, or (if no matching key is found) the <code>:else</code> value.</p>
176
+ <ul>
177
+ <li>Any <code>Proc</code> values in the transform hash are resolved (via <code>call</code>) before being returned.
178
+ <ul>
179
+ <li>Values with arity 0 are <code>call</code>ed with no params.</li>
180
+ <li>Values with arity 1 are <code>call</code>ed with the original value.</li>
181
+ <li>Values with arity -1 (<code>lambda</code>s with an optional param) are <code>call</code>ed with the original value.</li>
182
+ </ul>
183
+ </li>
184
+ <li>This method uses <strong>case comparison</strong> (<code>===</code>), so range and class keys work as you expect.</li>
185
+ </ul>
186
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_transform'>transform</span> <span class='id identifier rubyid_key_1'>key_1</span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_value_1'>value_1</span><span class='comma'>,</span>
187
+ <span class='id identifier rubyid_key_2'>key_2</span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_value_2'>value_2</span><span class='comma'>,</span>
188
+ <span class='comment'># ...
189
+ </span> <span class='label'>else:</span> <span class='id identifier rubyid_else_value'>else_value</span>
190
+ </code></pre>
191
+ <h2 id="Potential_Gotchas">Potential Gotchas</h2>
192
+ <ul>
193
+ <li>
194
+ <p>Because <code>else:</code> has special meaning, <code>transform</code> cannot check for the original value being the literal <code>Symbol</code> <code>:else</code>.</p>
195
+ </li>
196
+ <li>
197
+ <p><code>Proc</code> instances are only resolved if they <em>need to be returned and are not the original value</em>:</p>
198
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='tlambda'>-&gt;</span> <span class='tlambeg'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>value proc</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
199
+ <span class='id identifier rubyid_replacement_proc'>replacement_proc</span> <span class='op'>=</span> <span class='tlambda'>-&gt;</span> <span class='tlambeg'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>replacement proc</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
200
+
201
+ <span class='comment'># Returns the original `value`, still a *Proc*.
202
+ </span><span class='comment'>#
203
+ </span><span class='comment'># The original `value` is never resolved.
204
+ </span><span class='comment'># The `replacement_proc` is not resolved.
205
+ </span><span class='comment'>#
206
+ </span><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_unless'>unless</span> <span class='int'>99</span><span class='comma'>,</span> <span class='label'>then:</span> <span class='id identifier rubyid_replacement_proc'>replacement_proc</span>
207
+
208
+ <span class='comment'># Returns the *String* &#39;replacement proc&#39;.
209
+ </span><span class='comment'>#
210
+ </span><span class='comment'># The original `value` is never resolved.
211
+ </span><span class='comment'># The `replacement_proc` DOES get resolved.
212
+ </span><span class='comment'>#
213
+ </span><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_unless'>unless</span> <span class='id identifier rubyid_value'>value</span><span class='comma'>,</span> <span class='label'>then:</span> <span class='id identifier rubyid_replacement_proc'>replacement_proc</span>
214
+
215
+ <span class='comment'># Returns 99.
216
+ </span><span class='comment'>#
217
+ </span><span class='comment'># The original `value` is never resolved.
218
+ </span><span class='comment'># The `replacement_proc` is not resolved.
219
+ </span><span class='comment'>#
220
+ </span><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_transform'>transform</span> <span class='id identifier rubyid_value'>value</span> <span class='op'>=&gt;</span> <span class='int'>99</span><span class='comma'>,</span> <span class='label'>else:</span> <span class='id identifier rubyid_replacement_proc'>replacement_proc</span>
221
+
222
+ <span class='comment'># Returns the *String* &#39;replacement proc&#39;.
223
+ </span><span class='comment'>#
224
+ </span><span class='comment'># The original `value` is never resolved.
225
+ </span><span class='comment'># The `replacement_proc` DOES get resolved.
226
+ </span><span class='comment'>#
227
+ </span><span class='id identifier rubyid_final'>final</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_transform'>transform</span> <span class='int'>99</span> <span class='op'>=&gt;</span> <span class='int'>99</span><span class='comma'>,</span> <span class='label'>else:</span> <span class='id identifier rubyid_replacement_proc'>replacement_proc</span>
228
+ </code></pre>
229
+ </li>
230
+ <li>
231
+ <p>Because <em>return</em> <code>Proc</code>s are resolved before being passed back, you have to &quot;proc-wrap&quot; any <code>Proc</code> you want returned as-is (😵‍💫):</p>
232
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>some value</span><span class='tstring_end'>&#39;</span></span>
233
+ <span class='id identifier rubyid_replacement_proc'>replacement_proc</span> <span class='op'>=</span> <span class='tlambda'>-&gt;</span> <span class='tlambeg'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>replacement proc</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
234
+
235
+ <span class='comment'># Returns the `replacement_proc`, still a *Proc*.
236
+ </span><span class='comment'>#
237
+ </span><span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_unless'>unless</span> <span class='int'>99</span><span class='comma'>,</span> <span class='label'>then:</span> <span class='tlambda'>-&gt;</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_replacement_proc'>replacement_proc</span> <span class='rbrace'>}</span>
238
+ </code></pre>
239
+ <p>It should be <em>exceedingly rare</em> for someone to want to do this, but it <em>is</em> supported and this is how you would make that happen.</p>
240
+ </li>
241
+ </ul>
242
+ <h2 id="Contribution___Development">Contribution / Development</h2>
243
+ <p>Bug reports and pull requests are welcome at: <a href="https://github.com/nestor-custodio/inline_transforms"><a href="https://github.com/nestor-custodio/inline_transforms">https://github.com/nestor-custodio/inline_transforms</a></a></p>
244
+ <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>rake spec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
245
+ <p>Linting is courtesy of <a href="https://docs.rubocop.org/">Rubocop</a> (<code>rake rubocop</code>) and documentation is built using <a href="https://yardoc.org/">YARD</a>. Please ensure you have a clean bill of health from Rubocop and that any new features and/or changes to behaviour are reflected in the adjacent documentation before submitting a pull request.</p>
246
+ <h2 id="License">License</h2>
247
+ <p>The <code>inline_transforms</code> gem is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p></div></div>
248
+
249
+ <div id="footer">
250
+ Generated on Wed Aug 26 23:26:19 2026 by
251
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
252
+ 0.9.45 (ruby-3.4.8).
253
+ </div>
254
+
255
+ </div>
256
+ </body>
257
+ </html>