kirbybaserubymanual.html in KirbyBase-2.5.2 vs kirbybaserubymanual.html in KirbyBase-2.6
- old
+ new
@@ -259,20 +259,20 @@
</head>
<body>
<div id="header">
<h1>KirbyBase Manual (Ruby Version)</h1>
<span id="author">Jamey Cribbs</span><br />
-<span id="email"><tt><<a href="mailto:jcribbs@twmi.rr.com">jcribbs@twmi.rr.com</a>></tt></span><br />
-v2.5.2 December 2005
+<span id="email"><tt><<a href="mailto:jcribbs@netpromi.com">jcribbs@netpromi.com</a>></tt></span><br />
+v2.6 June 2006
</div>
<div id="preamble">
<div class="sectionbody">
<div class="imageblock">
<div class="content">
<img src="images/kirby1.jpg" alt="images/kirby1.jpg"/>
</div>
-<div class="image-title">Figure: Kirby pictured here in attack mode.</div>
+<div class="image-title">Figure: Kirby, pictured here in attack mode.</div>
</div>
</div>
</div>
<h2>Table of Contents</h2>
<div class="sectionbody">
@@ -384,10 +384,15 @@
<li>
<p>
<a href="#selects-involving-lookups-or-link-manys">Selects involving Lookups or Link_manys</a>
</p>
</li>
+<li>
+<p>
+<a href="#a-note-about-nil-values">A note about nil values</a>
+</p>
+</li>
</ol>
</li>
<li>
<p>
<a href="#kbresultset">KBResultSet</a>
@@ -706,13 +711,14 @@
text files and small SQL database management systems like SQLite and
MySQL.</p>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title">Drop me a line!</div>
-<p>If you find a use for KirbyBase, please send an email
-telling me how you use it. I find that hearing how people have
-put KirbyBase to use is one of the biggest rewards I get for working on it.</p>
+<p>If you find a use for KirbyBase, please send me an email telling how you
+use it, whether it is ok for me to mention your application on the
+"KirbyBase Applications" webpage, and possibly a link to your application's
+webpage (if you have one).</p>
</div></div>
</div>
<h2><a id="connecting-to-a-database"></a>Connecting to a database</h2>
<div class="sectionbody">
<p>To use Kirbybase, you first need to require the module:</p>
@@ -748,18 +754,18 @@
</div></div>
<p>To specify a different location other than the current directory for any
memo/blob files, you need to pass the location as an argument, like so:</p>
<div class="listingblock">
<div class="content">
-<pre><tt>db = KirbyBase.new(:local, nil, './', '.tbl', './memos')</tt></pre>
+<pre><tt>db = KirbyBase.new(:local, nil, nil, './', '.tbl', './memos')</tt></pre>
</div></div>
<p>If you don't want KirbyBase to spend time initially creating all of the
indexes for the tables in the database, you can pass true as the
delay_index_creation argument:</p>
<div class="listingblock">
<div class="content">
-<pre><tt>db = KirbyBase.new(:local, nil, './', '.tbl', './', true)</tt></pre>
+<pre><tt>db = KirbyBase.new(:local, nil, nil, './', '.tbl', './', true)</tt></pre>
</div></div>
<p>KirbyBase will skip initial index creation and will create a table's
indexes when the table is first referenced.</p>
<p>You can also specify the arguments via a code block. So, if you don't want
to have to specify a bunch of arguments just to get to the one you want,
@@ -826,12 +832,16 @@
</div></div>
<h3><a id="record-class"></a>Specifying a custom record class</h3>
<p>You can also specify that you want records of the table to be returned to
you as instances of a class. To do this, simply define a class before you
call #create_table. This class needs to have an accessor for each fieldname
-in the table. Also, this class needs to have a class method, called
-#kb_create, that returns a new class instance. Here is an example class:</p>
+in the table.</p>
+<p>If this class has a class method, called #kb_create, KirbyBase, when
+creating each record of the result set, will call that method and pass it
+the field values of the result record. #kb_create will need to handle
+creating an instance of the record class itself.</p>
+<p>Here is an example of #kb_create in action:</p>
<div class="listingblock">
<div class="content">
<pre><tt>class Foobar
attr_accessor(:recno, :name, :country, :role, :speed, :range,
:began_service, :still_flying, :alpha, :beta)
@@ -868,10 +878,12 @@
</div></div>
<p>Now, when you call #select, the result set will be made up of instances of
Foobar, instead of the default, which is instances of Struct. This also
works the other way. You can now specify instances of Foobar as input to
the #insert, #update and #set methods. More on those methods below.</p>
+<p>If the custom record class does not respond to #kb_create, KirbyBase will
+call the class's #new method instead, passing it all of the field values.</p>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="admonitionblock">
<table><tr>
<td class="icon">
@@ -1370,10 +1382,39 @@
result.items.each { |item| puts '%d %d' % [item.item_no, item.qty] }</tt></pre>
</div></div>
<p>Notice how the items attribute in the ResultSet is itself a ResultSet
containing all of the :order_items records that belong to the selected
order.</p>
+<h3><a id="a-note-about-nil-values"></a>A Note About nil Values</h3>
+<p>Beginning in version 2.6 of KirbyBase, nil values are no longer stored as
+the singleton instance of NilClass in the database. Now, they are stored
+as references to the singleton instance, kb_nil, of KBNilClass. KBNilClass
+is as similar to NilClass as possible, but since NilClass cannot
+be sub-classed, there are a few minor differences.</p>
+<p>However, this should all be transparent to you because KirbyBase converts
+kb_nil values to Ruby nil values before returning the results of a query.
+The only time you will need to be worried about kb_nil is when you need to
+explicitly test for a nil value in a query. For example:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>plane_tbl.select {|r| r.speed == kb_nil}</tt></pre>
+</div></div>
+<p>which is the same as:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>plane_tbl.select {|r| r.speed.kb_nil?}</tt></pre>
+</div></div>
+<p>Notice how it is very similar to how you would test for nil?</p>
+<p>The only other difference you will now notice, is if you open up a table in
+a text editor. Now, nil values are stored as "kb_nil", instead of being
+stored as an empty string (i.e. ""). This has the added advantage that
+KirbyBase can now distinguish between empty strings and nil values. In the
+past, if you saved an empty string as a field value, the next time you
+selected that record, KirbyBase would return that field's value as nil.</p>
+<p>The main reason for making this change was to eliminate the need to
+override NilClass#method_missing, which was cause for concern for some
+users.</p>
</div>
<h2><a id="kbresultset"></a>KBResultSet</h2>
<div class="sectionbody">
<p>As stated above, the select method returns an instance of KBResultSet, which
is an array of Struct objects (or instances of the class specified in
@@ -1675,10 +1716,18 @@
lines:</p>
<div class="listingblock">
<div class="content">
<pre><tt>result = plane_tbl.pack</tt></pre>
</div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/important.png" alt="Important" />
+</td>
+<td class="content">You can only call this method when connect_type==:local.</td>
+</tr></table>
+</div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="admonitionblock">
<table><tr>
<td class="icon">
@@ -1852,10 +1901,12 @@
</div></div>
<p>This method allows you to import a csv file into the current table.
KirbyBase will attempt to convert the values in the csv file into their
corresponding KirbyBase field types, based upon the field types you
designated when you created the table.</p>
+<p>If you have FasterCSV installed KirbyBase will use it instead of CSV from
+the standard library.</p>
<p>Returns an Integer specifying the total number of records imported.</p>
</div></div>
<div class="sidebarblock">
<a id="add-column"></a>
<div class="sidebar-content">
@@ -2163,14 +2214,14 @@
</div></div>
<p>The first line is the header rec. Each field is delimited by a "|". The
first field in the header is the record counter. It is incremented by
KirbyBase to create new record numbers when records are inserted.</p>
<p>The second field in the header is the deleted-records counter. Every time a
-line in the file is blanked-out (see "The pack method"), this number is
-incremented. You can use this field in a maintenance script so that the
-table is packed whenever the deleted-records counter reaches, say, 5,000
-records.</p>
+line in the file is blanked-out (see <a href="#pack-method">The pack method</a>), this
+number is incremented. You can use this field in a maintenance script so
+that the table is packed whenever the deleted-records counter reaches, say,
+5,000 records.</p>
<p>The third field in the header is the record_class field. If you specified a
class when you created the table, its name will show up here and records
returned from a #select will be instances of this class. The default is
"Struct".</p>
<p>The fourth field in the header is the :recno field. This field is
@@ -2264,10 +2315,10 @@
</tr></table>
</div>
</div>
<div id="footer">
<div id="footer-text">
-Last updated 30-Dec-2005 10:16:41 Eastern Daylight Time
+Last updated 26-Jun-2006 14:36:38 EDT
</div>
</div>
</body>
</html>