db-struct 0.1.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 (35) hide show
  1. checksums.yaml +7 -0
  2. data/README.md +125 -0
  3. data/Rakefile +35 -0
  4. data/db-struct.gemspec +37 -0
  5. data/doc/DBStruct/BogoHash.html +1384 -0
  6. data/doc/DBStruct/ErrorHelpers.html +288 -0
  7. data/doc/DBStruct/Failure.html +139 -0
  8. data/doc/DBStruct/FieldError.html +143 -0
  9. data/doc/DBStruct/MissingRowError.html +143 -0
  10. data/doc/DBStruct/TypeError.html +143 -0
  11. data/doc/DBStruct.html +1652 -0
  12. data/doc/_index.html +189 -0
  13. data/doc/class_list.html +54 -0
  14. data/doc/css/common.css +1 -0
  15. data/doc/css/full_list.css +58 -0
  16. data/doc/css/style.css +503 -0
  17. data/doc/file.README.html +187 -0
  18. data/doc/file_list.html +59 -0
  19. data/doc/frames.html +22 -0
  20. data/doc/index.html +187 -0
  21. data/doc/js/app.js +344 -0
  22. data/doc/js/full_list.js +242 -0
  23. data/doc/js/jquery.js +4 -0
  24. data/doc/method_list.html +342 -0
  25. data/doc/top-level-namespace.html +110 -0
  26. data/gem.deps.rb +7 -0
  27. data/lib/dbstruct.rb +29 -0
  28. data/lib/internal/bogohash.rb +226 -0
  29. data/lib/internal/dbstruct_base.rb +144 -0
  30. data/lib/internal/dbstruct_class.rb +301 -0
  31. data/lib/internal/error.rb +44 -0
  32. data/lib/internal/util.rb +11 -0
  33. data/spec/dbstruct_spec.rb +452 -0
  34. data/spec/spec_helper.rb +48 -0
  35. metadata +138 -0
data/doc/file.README.html ADDED
@@ -0,0 +1,187 @@
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.37
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 class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'>
61
+ <h1 id="label-Persistant+Sets+of+Structured+Data">Persistant Sets of Structured Data</h1>
62
+
63
+ <p><code>db-struct</code> is a Ruby gem that provides class <code>DBStruct</code>, a class that is similar to Ruby’s built-in <code>Struct</code> class but stores its data in a SQLite database. In addition, each subclass also provides access to the database via an interface that closely mimics a Ruby Hash, including support for enumeration.</p>
64
+
65
+ <p>It is currently at the “experimental toy” stage of development.</p>
66
+
67
+ <h2 id="label-Installation">Installation</h2>
68
+
69
+ <p>Simply install it via <code>gem</code>:</p>
70
+
71
+ <pre class="code ruby"><code class="ruby">gem install --prerelease db-struct
72
+ </code></pre>
73
+
74
+ <p>Note that you will also need to install SQLite3 separately. On stock Ruby, that’s:</p>
75
+
76
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_sqlite3'>sqlite3</span>
77
+ </code></pre>
78
+
79
+ <p>while with JRuby, it’s:</p>
80
+
81
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_jdbc'>jdbc</span><span class='op'>-</span><span class='id identifier rubyid_sqlite3'>sqlite3</span>
82
+ </code></pre>
83
+
84
+ <p>It uses <a href="https://sequel.jeremyevans.net/">Sequel</a> to do the heavy lifting. This is installed as a dependency, but you’ll need to know how to open a database with it.</p>
85
+
86
+ <h2 id="label-Overview">Overview</h2>
87
+
88
+ <p>Let’s start with a simple example, a table of books. The first thing we need to do is create a database connection:</p>
89
+
90
+ <pre class="code ruby"><code class="ruby"><span class='const'>DB</span> <span class='op'>=</span> <span class='const'>Sequel</span><span class='period'>.</span><span class='id identifier rubyid_sqlite'>sqlite</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>books.sqlite3</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
91
+ </code></pre>
92
+
93
+ <p>We can then define the structure and the underlying table:</p>
94
+
95
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DBStruct.html" title="DBStruct (class)">DBStruct</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with'><span class='object_link'><a href="DBStruct.html#with-class_method" title="DBStruct.with (method)">with</a></span></span><span class='lparen'>(</span><span class='const'>DB</span><span class='comma'>,</span> <span class='symbol'>:books</span><span class='rparen'>)</span> <span class='kw'>do</span>
96
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='const'>String</span>
97
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:author</span><span class='comma'>,</span> <span class='const'>String</span>
98
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:date</span><span class='comma'>,</span> <span class='const'>Time</span>
99
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:edition</span><span class='comma'>,</span> <span class='const'>Integer</span>
100
+ <span class='kw'>end</span>
101
+ </code></pre>
102
+
103
+ <p><code>Book</code> is now a subclass of <code>DBStruct</code>; creating it will also create a table named <code>:books</code> if it doesn’t exist.</p>
104
+
105
+ <p>We can create an instance of <code>Book</code> like this:</p>
106
+
107
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b1'>b1</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='label'>title:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Diseases of the Dragon</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
108
+ <span class='label'>author:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
109
+ <span class='label'>date:</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='int'>1989</span><span class='comma'>,</span> <span class='int'>11</span><span class='comma'>,</span> <span class='int'>1</span><span class='rparen'>)</span><span class='comma'>,</span>
110
+ <span class='label'>edition:</span> <span class='int'>1</span><span class='rparen'>)</span>
111
+ </code></pre>
112
+
113
+ <p>The contents are immediately written to the database, but this object behaves more or less like a Ruby <code>Struct</code>:</p>
114
+
115
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span>
116
+ <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin-Vimes</span><span class='tstring_end'>&quot;</span></span>
117
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span>
118
+ </code></pre>
119
+
120
+ <p>Note that these are not part of a transaction. If you need that (and you probably will), you can the <code>transaction</code> method:</p>
121
+
122
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_transaction'>transaction</span> <span class='lbrace'>{</span>
123
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span>
124
+ <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin-Vimes</span><span class='tstring_end'>&quot;</span></span>
125
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span>
126
+ <span class='rbrace'>}</span>
127
+ </code></pre>
128
+
129
+ <p>This starts a transaction, evaluates the block and commits. If there is an exception inside the block, the transaction is rolled back instead. Transactions can be safely nested. (<code>DBStruct#transaction</code> is simply a thin wrapper around <code>Sequel::Database#transaction</code>.)</p>
130
+
131
+ <p>The class method <code>items</code> returns a <code>DBStruct::BogoHash</code>, which behaves like a Hash mapping numeric row IDs to corresponding <code>Book</code> objects:</p>
132
+
133
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_puts'>puts</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='lbracket'>[</span><span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_rowid'>rowid</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span>
134
+ </code></pre>
135
+
136
+ <p>The usual enumeration operations are also available:</p>
137
+
138
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='period'>.</span><span class='id identifier rubyid_values'>values</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span><span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_book'>book</span><span class='op'>|</span>
139
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_book'>book</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span><span class='embexpr_end'>}</span><span class='tstring_content'> by </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_book'>book</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
140
+ <span class='rbrace'>}</span>
141
+
142
+ <span class='id identifier rubyid_first_editions'>first_editions</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span>
143
+ <span class='period'>.</span><span class='id identifier rubyid_select'>select</span><span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_id'>id</span><span class='comma'>,</span> <span class='id identifier rubyid_book'>book</span><span class='op'>|</span> <span class='id identifier rubyid_book'>book</span><span class='period'>.</span><span class='id identifier rubyid_edition'>edition</span> <span class='op'>==</span> <span class='int'>1</span><span class='rbrace'>}</span>
144
+ <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_id'>id</span><span class='comma'>,</span> <span class='id identifier rubyid__'>_</span><span class='op'>|</span> <span class='id identifier rubyid_id'>id</span><span class='rbrace'>}</span>
145
+ </code></pre>
146
+
147
+ <p>You can also add a special field type called a <code>group</code>. This can be used to subdivide the table:</p>
148
+
149
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DBStruct.html" title="DBStruct (class)">DBStruct</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with'><span class='object_link'><a href="DBStruct.html#with-class_method" title="DBStruct.with (method)">with</a></span></span><span class='lparen'>(</span><span class='const'>DB</span><span class='comma'>,</span> <span class='symbol'>:books</span><span class='rparen'>)</span> <span class='kw'>do</span>
150
+ <span class='id identifier rubyid_group'>group</span> <span class='symbol'>:category</span><span class='comma'>,</span> <span class='const'>String</span>
151
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='const'>String</span>
152
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:author</span><span class='comma'>,</span> <span class='const'>String</span>
153
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:date</span><span class='comma'>,</span> <span class='const'>Time</span>
154
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:edition</span><span class='comma'>,</span> <span class='const'>Integer</span>
155
+ <span class='kw'>end</span>
156
+
157
+ <span class='id identifier rubyid_b1'>b1</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='label'>category:</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>non-fiction</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
158
+ <span class='label'>title:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Diseases of the Dragon</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
159
+ <span class='label'>author:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
160
+ <span class='label'>date:</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='int'>1989</span><span class='comma'>,</span> <span class='int'>11</span><span class='comma'>,</span> <span class='int'>1</span><span class='rparen'>)</span><span class='comma'>,</span>
161
+ <span class='label'>edition:</span> <span class='int'>1</span><span class='rparen'>)</span>
162
+ </code></pre>
163
+
164
+ <p>A <code>group</code> is just an ordinary field except that <code>Books.items</code> will filter by them:</p>
165
+
166
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_non_fiction'>non_fiction</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>non-fiction</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
167
+ </code></pre>
168
+
169
+ <p>Multiple groups are allowed and <code>nil</code> can be used as a wildcard when selection them.</p>
170
+
171
+ <p>Alternately, you can filter using a <code>Sequel</code> <code>where</code> clause:</p>
172
+
173
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_dragon_books'>dragon_books</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='const'>Sequel</span><span class='period'>.</span><span class='id identifier rubyid_like'>like</span><span class='lparen'>(</span><span class='symbol'>:title</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>%Dragon%</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span><span class='rparen'>)</span>
174
+ </code></pre>
175
+
176
+ <p>but if you need that often, you may well be better off dealing with <code>Sequel</code> directly.</p>
177
+ </div></div>
178
+
179
+ <div id="footer">
180
+ Generated on Wed Sep 11 13:00:26 2024 by
181
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
182
+ 0.9.37 (ruby-3.1.4).
183
+ </div>
184
+
185
+ </div>
186
+ </body>
187
+ </html>
data/doc/file_list.html ADDED
@@ -0,0 +1,59 @@
1
+ <!DOCTYPE html>
2
+ <html >
3
+ <head>
4
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
5
+ <meta charset="utf-8" />
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" />
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" />
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <title>File List</title>
19
+ <base id="base_target" target="_parent" />
20
+ </head>
21
+ <body>
22
+ <div id="content">
23
+ <div class="fixed_header">
24
+ <h1 id="full_list_header">File List</h1>
25
+ <div id="full_list_nav">
26
+
27
+ <span><a target="_self" href="class_list.html">
28
+ Classes
29
+ </a></span>
30
+
31
+ <span><a target="_self" href="method_list.html">
32
+ Methods
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="file_list.html">
36
+ Files
37
+ </a></span>
38
+
39
+ </div>
40
+
41
+ <div id="search">
42
+ <label for="search-class">Search:</label>
43
+ <input id="search-class" type="text" />
44
+ </div>
45
+ </div>
46
+
47
+ <ul id="full_list" class="file">
48
+
49
+
50
+ <li id="object_README" class="odd">
51
+ <div class="item"><span class="object_link"><a href="index.html" title="README">README</a></span></div>
52
+ </li>
53
+
54
+
55
+
56
+ </ul>
57
+ </div>
58
+ </body>
59
+ </html>
data/doc/frames.html ADDED
@@ -0,0 +1,22 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Documentation by YARD 0.9.37</title>
6
+ </head>
7
+ <script type="text/javascript">
8
+ var mainUrl = 'index.html';
9
+ try {
10
+ var match = decodeURIComponent(window.location.hash).match(/^#!(.+)/);
11
+ var name = match ? match[1] : mainUrl;
12
+ var url = new URL(name, location.href);
13
+ window.top.location.replace(url.origin === location.origin ? name : mainUrl);
14
+ } catch (e) {
15
+ window.top.location.replace(mainUrl);
16
+ }
17
+ </script>
18
+ <noscript>
19
+ <h1>Oops!</h1>
20
+ <h2>YARD requires JavaScript!</h2>
21
+ </noscript>
22
+ </html>
data/doc/index.html ADDED
@@ -0,0 +1,187 @@
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.37
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 class="nav_wrap">
31
+ <iframe id="nav" src="class_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'>
61
+ <h1 id="label-Persistant+Sets+of+Structured+Data">Persistant Sets of Structured Data</h1>
62
+
63
+ <p><code>db-struct</code> is a Ruby gem that provides class <code>DBStruct</code>, a class that is similar to Ruby’s built-in <code>Struct</code> class but stores its data in a SQLite database. In addition, each subclass also provides access to the database via an interface that closely mimics a Ruby Hash, including support for enumeration.</p>
64
+
65
+ <p>It is currently at the “experimental toy” stage of development.</p>
66
+
67
+ <h2 id="label-Installation">Installation</h2>
68
+
69
+ <p>Simply install it via <code>gem</code>:</p>
70
+
71
+ <pre class="code ruby"><code class="ruby">gem install --prerelease db-struct
72
+ </code></pre>
73
+
74
+ <p>Note that you will also need to install SQLite3 separately. On stock Ruby, that’s:</p>
75
+
76
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_sqlite3'>sqlite3</span>
77
+ </code></pre>
78
+
79
+ <p>while with JRuby, it’s:</p>
80
+
81
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_jdbc'>jdbc</span><span class='op'>-</span><span class='id identifier rubyid_sqlite3'>sqlite3</span>
82
+ </code></pre>
83
+
84
+ <p>It uses <a href="https://sequel.jeremyevans.net/">Sequel</a> to do the heavy lifting. This is installed as a dependency, but you’ll need to know how to open a database with it.</p>
85
+
86
+ <h2 id="label-Overview">Overview</h2>
87
+
88
+ <p>Let’s start with a simple example, a table of books. The first thing we need to do is create a database connection:</p>
89
+
90
+ <pre class="code ruby"><code class="ruby"><span class='const'>DB</span> <span class='op'>=</span> <span class='const'>Sequel</span><span class='period'>.</span><span class='id identifier rubyid_sqlite'>sqlite</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>books.sqlite3</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
91
+ </code></pre>
92
+
93
+ <p>We can then define the structure and the underlying table:</p>
94
+
95
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DBStruct.html" title="DBStruct (class)">DBStruct</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with'><span class='object_link'><a href="DBStruct.html#with-class_method" title="DBStruct.with (method)">with</a></span></span><span class='lparen'>(</span><span class='const'>DB</span><span class='comma'>,</span> <span class='symbol'>:books</span><span class='rparen'>)</span> <span class='kw'>do</span>
96
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='const'>String</span>
97
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:author</span><span class='comma'>,</span> <span class='const'>String</span>
98
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:date</span><span class='comma'>,</span> <span class='const'>Time</span>
99
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:edition</span><span class='comma'>,</span> <span class='const'>Integer</span>
100
+ <span class='kw'>end</span>
101
+ </code></pre>
102
+
103
+ <p><code>Book</code> is now a subclass of <code>DBStruct</code>; creating it will also create a table named <code>:books</code> if it doesn’t exist.</p>
104
+
105
+ <p>We can create an instance of <code>Book</code> like this:</p>
106
+
107
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b1'>b1</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='label'>title:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Diseases of the Dragon</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
108
+ <span class='label'>author:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
109
+ <span class='label'>date:</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='int'>1989</span><span class='comma'>,</span> <span class='int'>11</span><span class='comma'>,</span> <span class='int'>1</span><span class='rparen'>)</span><span class='comma'>,</span>
110
+ <span class='label'>edition:</span> <span class='int'>1</span><span class='rparen'>)</span>
111
+ </code></pre>
112
+
113
+ <p>The contents are immediately written to the database, but this object behaves more or less like a Ruby <code>Struct</code>:</p>
114
+
115
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span>
116
+ <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin-Vimes</span><span class='tstring_end'>&quot;</span></span>
117
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span>
118
+ </code></pre>
119
+
120
+ <p>Note that these are not part of a transaction. If you need that (and you probably will), you can the <code>transaction</code> method:</p>
121
+
122
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_transaction'>transaction</span> <span class='lbrace'>{</span>
123
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span>
124
+ <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin-Vimes</span><span class='tstring_end'>&quot;</span></span>
125
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span>
126
+ <span class='rbrace'>}</span>
127
+ </code></pre>
128
+
129
+ <p>This starts a transaction, evaluates the block and commits. If there is an exception inside the block, the transaction is rolled back instead. Transactions can be safely nested. (<code>DBStruct#transaction</code> is simply a thin wrapper around <code>Sequel::Database#transaction</code>.)</p>
130
+
131
+ <p>The class method <code>items</code> returns a <code>DBStruct::BogoHash</code>, which behaves like a Hash mapping numeric row IDs to corresponding <code>Book</code> objects:</p>
132
+
133
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_puts'>puts</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='lbracket'>[</span><span class='id identifier rubyid_b1'>b1</span><span class='period'>.</span><span class='id identifier rubyid_rowid'>rowid</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span>
134
+ </code></pre>
135
+
136
+ <p>The usual enumeration operations are also available:</p>
137
+
138
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='period'>.</span><span class='id identifier rubyid_values'>values</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span><span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_book'>book</span><span class='op'>|</span>
139
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_book'>book</span><span class='period'>.</span><span class='id identifier rubyid_title'>title</span><span class='embexpr_end'>}</span><span class='tstring_content'> by </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_book'>book</span><span class='period'>.</span><span class='id identifier rubyid_author'>author</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
140
+ <span class='rbrace'>}</span>
141
+
142
+ <span class='id identifier rubyid_first_editions'>first_editions</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span>
143
+ <span class='period'>.</span><span class='id identifier rubyid_select'>select</span><span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_id'>id</span><span class='comma'>,</span> <span class='id identifier rubyid_book'>book</span><span class='op'>|</span> <span class='id identifier rubyid_book'>book</span><span class='period'>.</span><span class='id identifier rubyid_edition'>edition</span> <span class='op'>==</span> <span class='int'>1</span><span class='rbrace'>}</span>
144
+ <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_id'>id</span><span class='comma'>,</span> <span class='id identifier rubyid__'>_</span><span class='op'>|</span> <span class='id identifier rubyid_id'>id</span><span class='rbrace'>}</span>
145
+ </code></pre>
146
+
147
+ <p>You can also add a special field type called a <code>group</code>. This can be used to subdivide the table:</p>
148
+
149
+ <pre class="code ruby"><code class="ruby"><span class='const'>Book</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="DBStruct.html" title="DBStruct (class)">DBStruct</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with'><span class='object_link'><a href="DBStruct.html#with-class_method" title="DBStruct.with (method)">with</a></span></span><span class='lparen'>(</span><span class='const'>DB</span><span class='comma'>,</span> <span class='symbol'>:books</span><span class='rparen'>)</span> <span class='kw'>do</span>
150
+ <span class='id identifier rubyid_group'>group</span> <span class='symbol'>:category</span><span class='comma'>,</span> <span class='const'>String</span>
151
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='const'>String</span>
152
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:author</span><span class='comma'>,</span> <span class='const'>String</span>
153
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:date</span><span class='comma'>,</span> <span class='const'>Time</span>
154
+ <span class='id identifier rubyid_field'>field</span> <span class='symbol'>:edition</span><span class='comma'>,</span> <span class='const'>Integer</span>
155
+ <span class='kw'>end</span>
156
+
157
+ <span class='id identifier rubyid_b1'>b1</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='label'>category:</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>non-fiction</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
158
+ <span class='label'>title:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Diseases of the Dragon</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
159
+ <span class='label'>author:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Lady Sybil Ramkin</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
160
+ <span class='label'>date:</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='int'>1989</span><span class='comma'>,</span> <span class='int'>11</span><span class='comma'>,</span> <span class='int'>1</span><span class='rparen'>)</span><span class='comma'>,</span>
161
+ <span class='label'>edition:</span> <span class='int'>1</span><span class='rparen'>)</span>
162
+ </code></pre>
163
+
164
+ <p>A <code>group</code> is just an ordinary field except that <code>Books.items</code> will filter by them:</p>
165
+
166
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_non_fiction'>non_fiction</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>non-fiction</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
167
+ </code></pre>
168
+
169
+ <p>Multiple groups are allowed and <code>nil</code> can be used as a wildcard when selection them.</p>
170
+
171
+ <p>Alternately, you can filter using a <code>Sequel</code> <code>where</code> clause:</p>
172
+
173
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_dragon_books'>dragon_books</span> <span class='op'>=</span> <span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='const'>Sequel</span><span class='period'>.</span><span class='id identifier rubyid_like'>like</span><span class='lparen'>(</span><span class='symbol'>:title</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>%Dragon%</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span><span class='rparen'>)</span>
174
+ </code></pre>
175
+
176
+ <p>but if you need that often, you may well be better off dealing with <code>Sequel</code> directly.</p>
177
+ </div></div>
178
+
179
+ <div id="footer">
180
+ Generated on Wed Sep 11 13:00:26 2024 by
181
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
182
+ 0.9.37 (ruby-3.1.4).
183
+ </div>
184
+
185
+ </div>
186
+ </body>
187
+ </html>