anchormodel 0.3.1 → 0.4.0

data/doc/Anchormodel.html

@@ -104,13 +104,50 @@
 <h2>Overview</h2><div class="docstring">
   <div class="discussion">
     
-<p>Inherit from this class and place your Anchormodel under <code>app/anchormodels/your_anchor_model.rb</code>. Use it like <code>YourAnchorModel</code>. Refer to the README for usage.</p>
+<p>An Anchormodel is a registry of named constants that behave like first-class objects. It is a richer alternative to Rails Enums: each entry is a real Ruby instance that can carry behavior and per-key attributes while still being persistable to a String column in the database.</p>
+
+<p>Place anchormodel subclasses under <code>app/anchormodels/your_anchor_model.rb</code> so Rails autoloading picks them up. Refer to the README for usage.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+        <p class="example_title"><div class='inline'>
+<p>Define an anchormodel</p>
+</div></p>
+      
+      <pre class="example code"><code><span class='kw'>class</span> <span class='const'>Role</span> <span class='op'>&lt;</span> <span class='const'>Anchormodel</span>
+  <span class='id identifier rubyid_include'>include</span> <span class='const'>Comparable</span>
+  <span class='id identifier rubyid_attr_reader'>attr_reader</span> <span class='symbol'>:privilege_level</span>
+
+  <span class='kw'>def</span> <span class='op'>&lt;=&gt;</span><span class='lparen'>(</span><span class='id identifier rubyid_other'>other</span><span class='rparen'>)</span> <span class='op'>=</span> <span class='id identifier rubyid_privilege_level'>privilege_level</span> <span class='op'>&lt;=&gt;</span> <span class='id identifier rubyid_other'>other</span><span class='period'>.</span><span class='id identifier rubyid_privilege_level'>privilege_level</span>
+
+  <span class='id identifier rubyid_new'>new</span> <span class='symbol'>:guest</span><span class='comma'>,</span>   <span class='label'>privilege_level:</span> <span class='int'>0</span>
+  <span class='id identifier rubyid_new'>new</span> <span class='symbol'>:manager</span><span class='comma'>,</span> <span class='label'>privilege_level:</span> <span class='int'>1</span>
+  <span class='id identifier rubyid_new'>new</span> <span class='symbol'>:admin</span><span class='comma'>,</span>   <span class='label'>privilege_level:</span> <span class='int'>2</span>
+<span class='kw'>end</span></code></pre>
+    
+      
+        <p class="example_title"><div class='inline'>
+<p>Use it from an ActiveRecord model</p>
+</div></p>
+      
+      <pre class="example code"><code><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ApplicationRecord</span>
+  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span>
+<span class='kw'>end</span>
+
+<span class='id identifier rubyid_user'>user</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_create!'>create!</span><span class='lparen'>(</span><span class='label'>role:</span> <span class='symbol'>:admin</span><span class='rparen'>)</span>
+<span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_role'>role</span>                   <span class='comment'># =&gt; #&lt;Role&lt;admin&gt;:...&gt;
+</span><span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_role'>role</span><span class='period'>.</span><span class='id identifier rubyid_privilege_level'>privilege_level</span>   <span class='comment'># =&gt; 2
+</span><span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_admin?'>admin?</span>                 <span class='comment'># =&gt; true</span></code></pre>
+    
+  </div>
+
 
 </div><h2>Defined Under Namespace</h2>
 <p class="children">
@@ -120,7 +157,7 @@
     
   
     
-      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Anchormodel/ActiveModelTypeValueMulti.html" title="Anchormodel::ActiveModelTypeValueMulti (class)">ActiveModelTypeValueMulti</a></span>, <span class='object_link'><a href="Anchormodel/ActiveModelTypeValueSingle.html" title="Anchormodel::ActiveModelTypeValueSingle (class)">ActiveModelTypeValueSingle</a></span>, <span class='object_link'><a href="Anchormodel/Attribute.html" title="Anchormodel::Attribute (class)">Attribute</a></span>
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Anchormodel/ActiveModelTypeValueMulti.html" title="Anchormodel::ActiveModelTypeValueMulti (class)">ActiveModelTypeValueMulti</a></span>, <span class='object_link'><a href="Anchormodel/ActiveModelTypeValueSingle.html" title="Anchormodel::ActiveModelTypeValueSingle (class)">ActiveModelTypeValueSingle</a></span>, <span class='object_link'><a href="Anchormodel/Attribute.html" title="Anchormodel::Attribute (class)">Attribute</a></span>, <span class='object_link'><a href="Anchormodel/InvalidKey.html" title="Anchormodel::InvalidKey (class)">InvalidKey</a></span>
     
   
 </p>
@@ -153,7 +190,9 @@
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'>
+<p>Returns the value of attribute index.</p>
+</div></span>
   
 </li>
 
@@ -180,7 +219,9 @@
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'>
+<p>Returns the value of attribute key.</p>
+</div></span>
   
 </li>
 
@@ -201,7 +242,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#all-class_method" title="all (class method)">.<strong>all</strong>  &#x21d2; Object </a>
+      <a href="#all-class_method" title="all (class method)">.<strong>all</strong>  &#x21d2; Array&lt;Anchormodel&gt; </a>
     
 
     
@@ -216,7 +257,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>Returns all possible values this Anchormodel can take.</p>
+<p>All registered entries of this subclass, in declaration order.</p>
 </div></span>
   
 </li>
@@ -225,7 +266,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#find-class_method" title="find (class method)">.<strong>find</strong>(key)  &#x21d2; Object </a>
+      <a href="#find-class_method" title="find (class method)">.<strong>find</strong>(key)  &#x21d2; Anchormodel<sup>?</sup> </a>
     
 
     
@@ -240,7 +281,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>Retrieves a particular value given the key.</p>
+<p>Retrieves the entry registered under <code>key</code>.</p>
 </div></span>
   
 </li>
@@ -249,7 +290,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#first-class_method" title="first (class method)">.<strong>first</strong>  &#x21d2; Object </a>
+      <a href="#first-class_method" title="first (class method)">.<strong>first</strong>  &#x21d2; Anchormodel<sup>?</sup> </a>
     
 
     
@@ -264,7 +305,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>Shorthand to satisfy rubocop.</p>
+<p>Shorthand for <code>all.first</code>.</p>
 </div></span>
   
 </li>
@@ -273,7 +314,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#form_collection-class_method" title="form_collection (class method)">.<strong>form_collection</strong>  &#x21d2; Object </a>
+      <a href="#form_collection-class_method" title="form_collection (class method)">.<strong>form_collection</strong>  &#x21d2; Array&lt;Array(String,String)&gt; </a>
     
 
     
@@ -288,7 +329,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>Returns an array of tuples [label, key] suitable for passing as a collection to some form input helpers.</p>
+<p>Builds a <code>[label, key_string]</code> tuple list suitable for Rails form select helpers.</p>
 </div></span>
   
 </li>
@@ -297,7 +338,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#setup!-class_method" title="setup! (class method)">.<strong>setup!</strong>  &#x21d2; Object </a>
+      <a href="#setup!-class_method" title="setup! (class method)">.<strong>setup!</strong>  &#x21d2; void </a>
     
 
     
@@ -312,7 +353,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>When a descendant of Anchormodel is first used, it must overwrite the class_attributes to prevent cross-class pollution.</p>
+<p>Initializes the per-subclass registry on first use.</p>
 </div></span>
   
 </li>
@@ -330,10 +371,12 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#==-instance_method" title="#== (instance method)">#<strong>==</strong>(other)  &#x21d2; Object </a>
+      <a href="#==-instance_method" title="#== (instance method)">#<strong>==</strong>(other)  &#x21d2; Boolean </a>
     
 
     
+      (also: #eql?)
+    
   </span>
   
   
@@ -344,7 +387,9 @@
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'>
+<p>Two anchormodels are equal iff they have the same concrete class and key.</p>
+</div></span>
   
 </li>
 
@@ -352,7 +397,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#as_json-instance_method" title="#as_json (instance method)">#<strong>as_json</strong>  &#x21d2; Object </a>
+      <a href="#as_json-instance_method" title="#as_json (instance method)">#<strong>as_json</strong>  &#x21d2; String </a>
     
 
     
@@ -366,7 +411,33 @@
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'>
+<p>JSON serialization returns the key as a String so anchormodels round-trip cleanly through JSON (e.g. for API payloads).</p>
+</div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#hash-instance_method" title="#hash (instance method)">#<strong>hash</strong>  &#x21d2; Integer </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>Hash matches <code>==</code> (class + key) so <code>Set</code> and <code>Hash</code> membership work correctly even for copies (<code>dup</code>, Marshal round-trip) of the singleton entries.</p>
+</div></span>
   
 </li>
 
@@ -391,7 +462,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>Call this initializer directly in your Anchormodel class.</p>
+<p>Registers a new entry.</p>
 </div></span>
   
 </li>
@@ -400,7 +471,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#inspect-instance_method" title="#inspect (instance method)">#<strong>inspect</strong>  &#x21d2; Object </a>
+      <a href="#inspect-instance_method" title="#inspect (instance method)">#<strong>inspect</strong>  &#x21d2; String </a>
     
 
     
@@ -414,7 +485,9 @@
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'>
+<p>Debug representation like <code>&quot;#&lt;Role&lt;admin&gt;:HASH&gt;&quot;</code>.</p>
+</div></span>
   
 </li>
 
@@ -422,7 +495,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#label-instance_method" title="#label (instance method)">#<strong>label</strong>  &#x21d2; Object </a>
+      <a href="#label-instance_method" title="#label (instance method)">#<strong>label</strong>  &#x21d2; String </a>
     
 
     
@@ -437,7 +510,7 @@
 
   
     <span class="summary_desc"><div class='inline'>
-<p>Returns a Rails label that is compatible with the <a href="https://github.com/grosser/gettext_i18n_rails/">Rails FastGettext</a> gem.</p>
+<p>Returns a translatable label for this entry, compatible with the <a href="https://github.com/grosser/gettext_i18n_rails/">Rails FastGettext</a> gem.</p>
 </div></span>
   
 </li>
@@ -446,7 +519,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#to_s-instance_method" title="#to_s (instance method)">#<strong>to_s</strong>  &#x21d2; Object </a>
+      <a href="#to_s-instance_method" title="#to_s (instance method)">#<strong>to_s</strong>  &#x21d2; String </a>
     
 
     
@@ -460,7 +533,9 @@
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'>
+<p>Same as <span class='object_link'><a href="#inspect-instance_method" title="Anchormodel#inspect (method)">#inspect</a></span>.</p>
+</div></span>
   
 </li>
 
@@ -483,13 +558,24 @@
 </h3><div class="docstring">
   <div class="discussion">
     
-<p>Call this initializer directly in your Anchormodel class. To set <code>@foo=:bar</code> for anchor <code>:ter</code>, use <code>new(:ter, foo: :bar)</code></p>
+<p>Registers a new entry. Called in the body of an Anchormodel subclass. All keyword arguments become instance attributes accessible via <code>attr_reader</code>.</p>
 
 
   </div>
 </div>
 <div class="tags">
-  <p class="tag_title">Parameters:</p>
+  
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+      <pre class="example code"><code><span class='kw'>class</span> <span class='const'>Role</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span></span>
+  <span class='id identifier rubyid_attr_reader'>attr_reader</span> <span class='symbol'>:privilege_level</span>
+  <span class='id identifier rubyid_new'>new</span> <span class='symbol'>:guest</span><span class='comma'>,</span> <span class='label'>privilege_level:</span> <span class='int'>0</span>
+<span class='kw'>end</span></code></pre>
+    
+  </div>
+<p class="tag_title">Parameters:</p>
 <ul class="param">
   
     <li>
@@ -503,7 +589,7 @@
       
         &mdash;
         <div class='inline'>
-<p>The key under which the entry should be stored.</p>
+<p>The unique key under which the entry is registered.</p>
 </div>
       
     </li>
@@ -513,19 +599,37 @@
         <span class='name'>attributes</span>
       
       
-        <span class='type'></span>
+        <span class='type'>(<tt>Hash</tt>)</span>
       
       
       
         &mdash;
         <div class='inline'>
-<p>All named arguments to Anchormodel are made available as instance attributes.</p>
+<p>Arbitrary attributes exposed as instance variables.</p>
 </div>
       
     </li>
   
 </ul>
 
+<p class="tag_title">Raises:</p>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>RuntimeError</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if <code>key</code> is already registered for this subclass.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -533,33 +637,33 @@
       <pre class="lines">
 
 
-48
-49
-50
-51
-52
-53
-54
-55
-56
-57
-58
-59
-60
-61
-62
-63
-64
-65
-66
-67
-68
-69
-70
-71</pre>
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 48</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 115</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_key'>key</span><span class='comma'>,</span> <span class='op'>**</span><span class='id identifier rubyid_attributes'>attributes</span><span class='rparen'>)</span>
   <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='period'>.</span><span class='id identifier rubyid_setup!'>setup!</span> <span class='kw'>unless</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='period'>.</span><span class='id identifier rubyid_setup_completed'>setup_completed</span>
@@ -609,6 +713,8 @@
 </h3><div class="docstring">
   <div class="discussion">
     
+<p>Returns the value of attribute index.</p>
+
 
   </div>
 </div>
@@ -621,12 +727,12 @@
       <pre class="lines">
 
 
-6
-7
-8</pre>
+37
+38
+39</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 6</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 37</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_index'>index</span>
   <span class='ivar'>@index</span>
@@ -650,6 +756,8 @@
 </h3><div class="docstring">
   <div class="discussion">
     
+<p>Returns the value of attribute key.</p>
+
 
   </div>
 </div>
@@ -662,12 +770,12 @@
       <pre class="lines">
 
 
-5
-6
-7</pre>
+33
+34
+35</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 5</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 33</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_key'>key</span>
   <span class='ivar'>@key</span>
@@ -687,7 +795,7 @@
       <div class="method_details first">
   <h3 class="signature first" id="all-class_method">
   
-    .<strong>all</strong>  &#x21d2; <tt>Object</tt> 
+    .<strong>all</strong>  &#x21d2; <tt>Array&lt;<span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span>&gt;</tt> 
   
 
   
@@ -696,13 +804,39 @@
 </h3><div class="docstring">
   <div class="discussion">
     
-<p>Returns all possible values this Anchormodel can take.</p>
+<p>Returns All registered entries of this subclass, in declaration order.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+      <pre class="example code"><code><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span> <span class='comment'># =&gt; [#&lt;Role&lt;guest&gt;&gt;, #&lt;Role&lt;manager&gt;&gt;, #&lt;Role&lt;admin&gt;&gt;]</span></code></pre>
+    
+  </div>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Array&lt;<span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span>&gt;</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>All registered entries of this subclass, in declaration order.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -710,12 +844,12 @@
       <pre class="lines">
 
 
-24
-25
-26</pre>
+63
+64
+65</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 24</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 63</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
   <span class='id identifier rubyid_entries_list'>entries_list</span>
@@ -728,7 +862,7 @@
       <div class="method_details ">
   <h3 class="signature " id="find-class_method">
   
-    .<strong>find</strong>(key)  &#x21d2; <tt>Object</tt> 
+    .<strong>find</strong>(key)  &#x21d2; <tt><span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span></tt><sup>?</sup> 
   
 
   
@@ -737,13 +871,24 @@
 </h3><div class="docstring">
   <div class="discussion">
     
-<p>Retrieves a particular value given the key. Fails if not found.</p>
+<p>Retrieves the entry registered under <code>key</code>.</p>
 
 
   </div>
 </div>
 <div class="tags">
-  <p class="tag_title">Parameters:</p>
+  
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+      <pre class="example code"><code><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:admin</span><span class='rparen'>)</span>   <span class='comment'># =&gt; #&lt;Role&lt;admin&gt;&gt;
+</span><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>admin</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>  <span class='comment'># =&gt; #&lt;Role&lt;admin&gt;&gt;   (same singleton instance)
+</span><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='kw'>nil</span><span class='rparen'>)</span>      <span class='comment'># =&gt; nil
+</span><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:nope</span><span class='rparen'>)</span>    <span class='comment'># raises Anchormodel::InvalidKey</span></code></pre>
+    
+  </div>
+<p class="tag_title">Parameters:</p>
 <ul class="param">
   
     <li>
@@ -751,7 +896,7 @@
         <span class='name'>key</span>
       
       
-        <span class='type'>(<tt>String</tt>, <tt>Symbol</tt>)</span>
+        <span class='type'>(<tt>String</tt>, <tt>Symbol</tt>, <tt>nil</tt>)</span>
       
       
       
@@ -764,6 +909,42 @@
   
 </ul>
 
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span></tt>, <tt>nil</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The matching entry, or <code>nil</code> if <code>key</code> is <code>nil</code>.</p>
+</div>
+      
+    </li>
+  
+</ul>
+<p class="tag_title">Raises:</p>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="Anchormodel/InvalidKey.html" title="Anchormodel::InvalidKey (class)">Anchormodel::InvalidKey</a></span></tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if no entry with that key exists.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -771,17 +952,17 @@
       <pre class="lines">
 
 
-40
-41
-42
-43</pre>
+99
+100
+101
+102</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 40</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 99</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='id identifier rubyid_key'>key</span><span class='rparen'>)</span>
   <span class='kw'>return</span> <span class='kw'>nil</span> <span class='kw'>if</span> <span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
-  <span class='kw'>return</span> <span class='id identifier rubyid_entries_hash'>entries_hash</span><span class='lbracket'>[</span><span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span><span class='rbracket'>]</span> <span class='op'>||</span> <span class='id identifier rubyid_fail'>fail</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Retreived undefined anchor model key </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_inspect'>inspect</span><span class='embexpr_end'>}</span><span class='tstring_content'> for </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_inspect'>inspect</span><span class='embexpr_end'>}</span><span class='tstring_content'>.</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
+  <span class='kw'>return</span> <span class='id identifier rubyid_entries_hash'>entries_hash</span><span class='lbracket'>[</span><span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span><span class='rbracket'>]</span> <span class='op'>||</span> <span class='id identifier rubyid_raise'>raise</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="Anchormodel/InvalidKey.html" title="Anchormodel::InvalidKey (class)">InvalidKey</a></span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Retrieved undefined anchor model key </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_inspect'>inspect</span><span class='embexpr_end'>}</span><span class='tstring_content'> for </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_inspect'>inspect</span><span class='embexpr_end'>}</span><span class='tstring_content'>.</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -791,7 +972,7 @@
       <div class="method_details ">
   <h3 class="signature " id="first-class_method">
   
-    .<strong>first</strong>  &#x21d2; <tt>Object</tt> 
+    .<strong>first</strong>  &#x21d2; <tt><span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span></tt><sup>?</sup> 
   
 
   
@@ -800,13 +981,31 @@
 </h3><div class="docstring">
   <div class="discussion">
     
-<p>Shorthand to satisfy rubocop</p>
+<p>Shorthand for <code>all.first</code>. Provided so callers can avoid Rubocop’s <code>Style/FirstElementInCollection</code>-style warnings on <code>Foo.all.first</code>.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="" title="Anchormodel (class)">Anchormodel</a></span></tt>, <tt>nil</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The first registered entry, or <code>nil</code> if the registry is empty.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -814,12 +1013,12 @@
       <pre class="lines">
 
 
-29
-30
-31</pre>
+70
+71
+72</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 29</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 70</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
   <span class='id identifier rubyid_all'>all</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
@@ -832,7 +1031,7 @@
       <div class="method_details ">
   <h3 class="signature " id="form_collection-class_method">
   
-    .<strong>form_collection</strong>  &#x21d2; <tt>Object</tt> 
+    .<strong>form_collection</strong>  &#x21d2; <tt>Array&lt;Array(String,String)&gt;</tt> 
   
 
   
@@ -841,13 +1040,34 @@
 </h3><div class="docstring">
   <div class="discussion">
     
-<p>Returns an array of tuples [label, key] suitable for passing as a collection to some form input helpers</p>
+<p>Builds a <code>[label, key_string]</code> tuple list suitable for Rails form select helpers.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+      <pre class="example code"><code>&lt;%= form.select :role, Role.form_collection %&gt;</code></pre>
+    
+  </div>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Array&lt;Array(String,String)&gt;</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -855,12 +1075,12 @@
       <pre class="lines">
 
 
-34
-35
-36</pre>
+78
+79
+80</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 34</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 78</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_form_collection'>form_collection</span>
   <span class='id identifier rubyid_entries_list'>entries_list</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_el'>el</span><span class='op'>|</span> <span class='lbracket'>[</span><span class='id identifier rubyid_el'>el</span><span class='period'>.</span><span class='id identifier rubyid_label'>label</span><span class='comma'>,</span> <span class='id identifier rubyid_el'>el</span><span class='period'>.</span><span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='rbracket'>]</span> <span class='rbrace'>}</span>
@@ -873,7 +1093,7 @@
       <div class="method_details ">
   <h3 class="signature " id="setup!-class_method">
   
-    .<strong>setup!</strong>  &#x21d2; <tt>Object</tt> 
+    .<strong>setup!</strong>  &#x21d2; <tt>void</tt> 
   
 
   
@@ -881,14 +1101,34 @@
   
 </h3><div class="docstring">
   <div class="discussion">
-    
-<p>When a descendant of Anchormodel is first used, it must overwrite the class_attributes to prevent cross-class pollution.</p>
+    <p class="note returns_void">This method returns an undefined value.</p>
+<p>Initializes the per-subclass registry on first use. Called automatically from the first <code>new</code> invocation. Each subclass gets its own duped copies of the registry class attributes to prevent cross-class pollution.</p>
+
+<p>You normally do not need to call this directly.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Raises:</p>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>RuntimeError</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if called twice for the same subclass.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -896,16 +1136,16 @@
       <pre class="lines">
 
 
-15
-16
-17
-18
-19
-20
-21</pre>
+52
+53
+54
+55
+56
+57
+58</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 15</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 52</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_setup!'>setup!</span>
   <span class='id identifier rubyid_fail'>fail</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>`setup!` was called twice for Anchormodel subclass </span><span class='embexpr_beg'>#{</span><span class='kw'>self</span><span class='embexpr_end'>}</span><span class='tstring_content'>.</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_setup_completed'>setup_completed</span>
@@ -928,20 +1168,54 @@
       <div class="method_details first">
   <h3 class="signature first" id="==-instance_method">
   
-    #<strong>==</strong>(other)  &#x21d2; <tt>Object</tt> 
+    #<strong>==</strong>(other)  &#x21d2; <tt>Boolean</tt> 
   
 
   
+    <span class="aliases">Also known as:
+    <span class="names"><span id='eql?-instance_method'>eql?</span></span>
+    </span>
+  
 
   
 </h3><div class="docstring">
   <div class="discussion">
     
+<p>Two anchormodels are equal iff they have the same concrete class and key. Different subclasses sharing a key are not equal.</p>
+
 
   </div>
 </div>
 <div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>other</span>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Boolean</tt>)</span>
+      
+      
+      
+    </li>
   
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -949,12 +1223,12 @@
       <pre class="lines">
 
 
-73
-74
-75</pre>
+144
+145
+146</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 73</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 144</span>
 
 <span class='kw'>def</span> <span class='op'>==</span><span class='lparen'>(</span><span class='id identifier rubyid_other'>other</span><span class='rparen'>)</span>
   <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span> <span class='op'>==</span> <span class='id identifier rubyid_other'>other</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_key'>key</span> <span class='op'>==</span> <span class='id identifier rubyid_other'>other</span><span class='period'>.</span><span class='id identifier rubyid_key'>key</span>
@@ -967,7 +1241,7 @@
       <div class="method_details ">
   <h3 class="signature " id="as_json-instance_method">
   
-    #<strong>as_json</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>as_json</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -976,11 +1250,34 @@
 </h3><div class="docstring">
   <div class="discussion">
     
+<p>JSON serialization returns the key as a String so anchormodels round-trip cleanly through JSON (e.g. for API payloads).</p>
+
 
   </div>
 </div>
 <div class="tags">
   
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+      <pre class="example code"><code><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:admin</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_as_json'>as_json</span> <span class='comment'># =&gt; &quot;admin&quot;</span></code></pre>
+    
+  </div>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -988,12 +1285,12 @@
       <pre class="lines">
 
 
-90
-91
-92</pre>
+184
+185
+186</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 90</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 184</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_as_json'>as_json</span>
   <span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span>
@@ -1001,12 +1298,66 @@
     </td>
   </tr>
 </table>
+</div>
+    
+      <div class="method_details ">
+  <h3 class="signature " id="hash-instance_method">
+  
+    #<strong>hash</strong>  &#x21d2; <tt>Integer</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Hash matches <code>==</code> (class + key) so <code>Set</code> and <code>Hash</code> membership work correctly even for copies (<code>dup</code>, Marshal round-trip) of the singleton entries.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Integer</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+152
+153
+154</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 152</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_hash'>hash</span>
+  <span class='lbracket'>[</span><span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='comma'>,</span> <span class='id identifier rubyid_key'>key</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_hash'>hash</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
 </div>
     
       <div class="method_details ">
   <h3 class="signature " id="inspect-instance_method">
   
-    #<strong>inspect</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>inspect</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -1015,11 +1366,31 @@
 </h3><div class="docstring">
   <div class="discussion">
     
+<p>Returns Debug representation like <code>&quot;#&lt;Role&lt;admin&gt;:HASH&gt;&quot;</code>.</p>
+
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>Debug representation like <code>&quot;#&lt;Role&lt;admin&gt;:HASH&gt;&quot;</code>.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -1027,12 +1398,12 @@
       <pre class="lines">
 
 
-82
-83
-84</pre>
+167
+168
+169</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 82</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 167</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_inspect'>inspect</span>
   <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>#&lt;</span><span class='embexpr_beg'>#{</span><span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='embexpr_end'>}</span><span class='tstring_content'>&lt;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_key'>key</span><span class='embexpr_end'>}</span><span class='tstring_content'>&gt;:</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_hash'>hash</span><span class='embexpr_end'>}</span><span class='tstring_content'>&gt;</span><span class='tstring_end'>&quot;</span></span>
@@ -1045,7 +1416,7 @@
       <div class="method_details ">
   <h3 class="signature " id="label-instance_method">
   
-    #<strong>label</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>label</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -1054,13 +1425,34 @@
 </h3><div class="docstring">
   <div class="discussion">
     
-<p>Returns a Rails label that is compatible with the <a href="https://github.com/grosser/gettext_i18n_rails/">Rails FastGettext</a> gem.</p>
+<p>Returns a translatable label for this entry, compatible with the <a href="https://github.com/grosser/gettext_i18n_rails/">Rails FastGettext</a> gem. The translation key is <code>&quot;&lt;SubclassName&gt;|&lt;Humanized key&gt;&quot;</code>.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+  <div class="examples">
+    <p class="tag_title">Examples:</p>
+    
+      
+      <pre class="example code"><code><span class='const'>Role</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:admin</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_label'>label</span> <span class='comment'># =&gt; &quot;Role|Admin&quot; (or its I18n translation)</span></code></pre>
+    
+  </div>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -1068,12 +1460,12 @@
       <pre class="lines">
 
 
-78
-79
-80</pre>
+162
+163
+164</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 78</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 162</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_label'>label</span>
   <span class='const'>I18n</span><span class='period'>.</span><span class='id identifier rubyid_t'>t</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_demodulize'>demodulize</span><span class='embexpr_end'>}</span><span class='tstring_content'>|</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_key'>key</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='period'>.</span><span class='id identifier rubyid_humanize'>humanize</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
@@ -1086,7 +1478,7 @@
       <div class="method_details ">
   <h3 class="signature " id="to_s-instance_method">
   
-    #<strong>to_s</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>to_s</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -1095,11 +1487,26 @@
 </h3><div class="docstring">
   <div class="discussion">
     
+<p>Same as <span class='object_link'><a href="#inspect-instance_method" title="Anchormodel#inspect (method)">#inspect</a></span>. Anchormodel intentionally overrides <code>to_s</code> so string interpolation in templates is unambiguous; render <code>#label</code> or <code>#key</code> directly if you want a user-facing form.</p>
+
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -1107,12 +1514,12 @@
       <pre class="lines">
 
 
-86
-87
-88</pre>
+175
+176
+177</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 86</span>
+      <pre class="code"><span class="info file"># File 'lib/anchormodel.rb', line 175</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_to_s'>to_s</span>
   <span class='id identifier rubyid_inspect'>inspect</span>
@@ -1127,7 +1534,7 @@
 </div>
 
       <div id="footer">
-  Generated on Wed May 13 11:46:10 2026 by
+  Generated on Wed May 13 15:48:24 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.28 (ruby-3.3.5).
 </div>