christiank-turntable 1.1.1 → 1.1.2

data/turntable.rb

@@ -13,7 +13,7 @@ require 'ostruct'
 
 class Turntable
 
-  VERSION = 'v1.1.1'
+  VERSION = 'v1.1.2'
 
   include Enumerable
   def each
@@ -22,6 +22,10 @@ class Turntable
 
   # Creates a new Turntable object and corresponding file. Requires a filename
   # and a list of column names, or one array which represents the column names.
+  #
+  # Column names should be symbols. There is no need to declare an :id or
+  # primary key column; this is automatically taken care of by virtue of
+  # Turntable's likeness to an array. Columns are never typed.
   def initialize filename, *columns
     raise ArgumentError, 'expecting column names' if columns.empty?
 
@@ -52,6 +56,8 @@ class Turntable
   end
 
   # Allows you to access Turntable rows and/or metadata like an array or hash.
+  # If index is an integer, you're looking for a row of data. If index is 
+  # something else (usually a symbol), you're looking for a piece metadata.
   def [](index)
     @table[index]
   end
@@ -62,7 +68,7 @@ class Turntable
   end
 
   # Inserts a new column. Fills all of the pre-existing rows with nil. Returns
-  # the new databse.
+  # the new columns list.
   def add_column column_name
     raise ArgumentError, "column #{column_name} already exists" if @table[:columns].include?(column_name)
 
@@ -81,18 +87,19 @@ class Turntable
   alias :all :all_numbered_rows
   alias :*   :all_numbered_rows
 
-  # Removes a given row. Returns the new database.
+  # Removes a given row. Returns the changed database.
   def delete id
     @table.delete id
     self.update
     @table
   end
 
-  # A much healthier inspect() makes dealing with Turntable in IRB easier.
+  # A leaner, meaner inspect allows dealing with Turntable in IRB to be much
+  # easier.
   def inspect; self.to_s; end
 
-  # Returns a boolean indicating whether the select statement would return any
-  # data.
+  # Returns a boolean indicating whether an equivalent select statement would
+  # return any data.
   def include?
     result = []
     self.each { |row| result.push row if yield row }
@@ -107,7 +114,9 @@ class Turntable
   end
 
   # Pushes self with a new row. Accepts either a list of arguments, or one
-  # array which represents the same thing.
+  # array which represents the same thing. The number of arguments must equal
+  # the number of columns in the database. This is equivalent to the SQL INSERT
+  # statement.
   def push *args
     args = args[0] if args.length == 1 and args[0].is_a?(Array)
 
@@ -133,8 +142,9 @@ class Turntable
   # Just a wrapper for Array#to_textile.
   def to_textile; self.to_a.to_textile; end
 
-  # Any changes to the external file must occur within this block. If something
-  # goes wrong (like trying to push a Proc object) then no changes are made.
+  # Updates self and the Turntable file, by marshalling self to the file. Any
+  # changes to the external file must occur within this block. If something
+  # goes wrong, like trying to push a Proc object, then no changes are made.
   def update
     @pushing ? (@before_table) : (@before_table = @table.dup)
     what_happened = yield if block_given?
@@ -157,7 +167,9 @@ class Turntable
 
 end
 
-# Rows are custom OpenStructs, made with dictionaries and not hashes.
+# Rows are custom OpenStructs, made with dictionaries instead of hashes. Rows
+# may be created only in this manner, unlike regular OpenStructs, which also
+# accept a hash of values at creation.
 class Row < OpenStruct
   def initialize; @table = Dictionary.new; end
   public :table
@@ -181,7 +193,7 @@ class Array
 
     string += '</table>'
   end
-  
+
   # Writes the output of any query to STDOUT.
   def to_stdout; puts self.to_textile; end
 
@@ -204,10 +216,11 @@ end
 
 class Object
 
-  # Turn off Object#id warnings.
+  # Turntable uses id to identify a database's rows. Undefining this method
+  # turns off Object#id deprecation warnings.
   undef id
 
-  # Just like regular puts(), except putting a Turntable calls
+  # Just like regular puts, except putting a Turntable calls
   # Turntable#to_textile.
   def puts obj
     super obj

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: christiank-turntable
 version: !ruby/object:Gem::Version 
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors: 
 - Christian Koch
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-13 00:00:00 -07:00
+date: 2009-07-16 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -25,7 +25,7 @@ files:
 - turntable.rb
 - dictionary.rb
 has_rdoc: false
-homepage: http://github.com/christiank/Turntable
+homepage: http://christiank.github.com/Turntable/
 post_install_message: 
 rdoc_options: []