momomoto 0.1.13 → 0.1.14

data/lib/momomoto/row.rb

@@ -1,62 +1,86 @@
 
 module Momomoto
-  # base class for all Rows
+
+  # Base class for all Rows.
   class Row
 
-    # undefing fields to avoid conflicts
+    # undefining fields to avoid conflicts
     undef :id,:type
 
+    # Getter for the table this Row is using.
     def self.table
       @table
     end
 
+    # Getter for the columns of this Row's table.
     def self.columns
       @columns
     end
 
+    # Getter for the order of columns. The order is built from
+    # +columns+.keys.
     def self.column_order
       @column_order
     end
 
+    # Gets the value of a given +fieldname+.
+    #
+    #   feed = Feeds.select( {:url => 'https://www.c3d2.de/news-atom.xml' )[0]
+    #   feed[:url] == 'https://www.c3d2.de/news-atom.xml'
+    #     => true
+    #
     def []( fieldname )
       get_column( fieldname )
     end
 
+    # Sets +fieldname+ to +value+.
+    #
+    #   feed = Feeds.select( {:url => 'http://www.c3d2.de/news-atom.xml' )[0]
+    #   feed[:url_host] = 'https://www.c3d2.de/'
     def []=( fieldname, value )
       set_column( fieldname, value )
     end
 
+    # Compares +@data+ value of the row with +other+.
     def ==( other )
       @data == other.instance_variable_get( :@data )
     end
 
+    # Getter for +@dirty+ which holds all changed fields of a row.
     def dirty
       @dirty
     end
 
+    # Returns true if there are fields in +@dirty+.
     def dirty?
       @dirty.length > 0
     end
 
+    # Marks a field as dirty.
     def mark_dirty( field )
       field = field.to_sym
       @dirty.push( field ) if not @dirty.member?( field )
     end
 
+    # Removes all fields from +dirty+.
     def clean_dirty
       @dirty = []
     end
 
+    # Creates a new Row instance.
     def initialize( data = [] )
       @data = data
       @new_record = false
       clean_dirty
     end
 
+    # Returns true if the row is newly created.
     def new_record?
       @new_record
     end
 
+    # Sets +@new_record+ to +true+
+    # or +false+.
     def new_record=( value )
       @new_record = !!value
     end
@@ -71,7 +95,7 @@ module Momomoto
       self.class.table.delete( self )
     end
 
-    # convert row to hash
+    # converts row to hash
     def to_hash
       hash = {}
       self.class.columns.keys.each do | key |
@@ -80,7 +104,20 @@ module Momomoto
       hash
     end
 
-    # generic setter for column values
+    # Generic setter for column values. You should use this method when
+    # you are defining your own setter. This is useful for preprocessing +value+
+    # before it is written to database:
+    #
+    #   class Person < Momomoto::Table
+    #     module Methods
+    #       def nickname=( value )
+    #         set_column( :nickname, value.downcase )
+    #       end
+    #     end
+    #   end
+    #
+    # This defines a custom setter nickname= which invokes downcase 
+    # on the given +value+.
     def set_column( column, value )
       raise "Unknown column #{column}" if not self.class.column_order.member?( column.to_sym )
       table = self.class.table

data/lib/momomoto/table.rb

@@ -1,8 +1,8 @@
 
 module Momomoto
 
-  # this class implements access to tables/views
-  # it must not be used directly but you should inherit from this class
+  # This class implements access to tables/views.
+  # It must not be used directly but you should inherit from this class.
   class Table < Base
 
     class << self
@@ -43,7 +43,7 @@ module Momomoto
         @table_name
       end
 
-      # get the full name of a table including schema if set
+      # get the full name of table including, if set, schema
       def full_name
         "#{ schema_name ? schema_name + '.' : ''}#{table_name}"
       end
@@ -62,7 +62,64 @@ module Momomoto
         @primary_keys
       end
 
-      # Searches for records and returns an array containing the records
+      # Searches for records and returns an Array containing the records.
+      # There are a bunch of different use cases as this method is the primary way
+      # to access all rows in the database.
+      #
+      # Selecting rows based on expression:
+      #   #selects the feeds that match both the given url and author fields
+      #   Posts.select(:feed_url => "https://www.c3d2.de/news-atom.xml",:author => "fnord")
+      #
+      # Using order statements:
+      #   See Order#asc, Order#desc and Order#lower
+      #
+      #   #Selects conferences depending on start_date, starting with the oldest date.
+      #   #If two conferences start at the same date(day) use the second order parameter
+      #   #start_time.
+      #   Conference.select({},{:order => Momomoto.asc([:start_date,:start_time])} )
+      #
+      # Using limit statement:
+      #   See Base#compile_limit
+      #
+      #   #selects five feeds
+      #   five_feeds = Feeds.select( {},{:limit => 5} )
+      #
+      # Using offset statement:
+      #   See Base#compile_offset
+      #
+      #   #selects five feeds ommitting the first 23 rows
+      #   five_feeds = Feeds.select( {}, {:offset => 23, :limit => 5} )
+      #
+      # Using logical operators:
+      #   See Datatype::Base#operator_sign for basic comparison operators
+      #   See Base#logical_operator for the supported logical operators
+      #
+      #   #selects the posts where the content field case-insensitevely matches
+      #   #"surveillance".
+      #   Posts.select( :content => {:ilike => 'surveillance'} )
+      #
+      #   #selects all conferences with a start_date before the current time.
+      #   Conferences.select( :start_date => {:le => Time.now} )
+      # 
+      #   feed1 = "https://www.c3d2.de/news-atom.xml"
+      #   feed2 = "http://www.c3d2.de/news-atom.xml"
+      #   #selects the feeds with a field url that matches either feed1 or feed2
+      #   Feeds.select( :OR=>{:url => [feed1,feed2]} )
+      #
+      #   
+      # Selecting only given columns:
+      #   See Base#initialize_row for the implementation
+      #
+      #   #selects title and content for every row found in table Posts.
+      #   posts = Posts.select({},{:columns => [:title,:content]} )
+      #
+      #   The returned rows are special. They do not contain getter and setter
+      #   for the rest of the columns of the row. Only the specified columns
+      #   and all the primary keys of the table have proper accessor methods.
+      #
+      #   However, you can still change the rows and write them back to database:
+      #   posts.first.title = "new title"
+      #   posts.first.write
       def select( conditions = {}, options = {} )
         initialize_table unless initialized
         row_class = build_row_class( options )
@@ -74,6 +131,8 @@ module Momomoto
         data
       end
 
+      # experimental
+      #
       # Searches for records and returns an array containing the records
       def select_outer_join( conditions = {}, options = {} )
         initialize_table unless initialized
@@ -131,10 +190,14 @@ module Momomoto
         new_row
       end
 
-      # Tries to find a specific record and creates a new one if it does not find it.
+      # Tries to select the specified record or creates a new one if it does not find it.
       # Raises an exception if multiple records are found.
       # You can pass a block which has to deliver the respective values for the
-      # primary key fields
+      # primary key fields.
+      #
+      #   # selects the feed row matching the specified URL or creates a new
+      #   # row based on the given URL.
+      #   Feeds.select_or_new( :url => "https://www.c3d2.de/news-atom.xml" )
       def select_or_new( conditions = {}, options = {} )
         begin
           if block_given?
@@ -157,19 +220,19 @@ module Momomoto
       end
 
       # Select a single row from the database
-      # raises Momomoto::Nothing_found if nothing was found, raises
-      # Momomoto::Too_many_records if more than one record was found.
+      # raises Momomoto::Nothing_found if no row matched.
+      # raises Momomoto::Too_many_records if more than one record was found.
       def select_single( conditions = {}, options = {} )
         data = select( conditions, options )
         case data.length
-          when 0 then raise Nothing_found, "nothing found in #{table_name}"
+          when 0 then raise Nothing_found, "nothing found in #{full_name}"
           when 1 then return data[0]
-          else raise Too_many_records, "too many records found in #{table_name}"
+          else raise Too_many_records, "too many records found in #{full_name}"
         end
       end
 
-      # write row back to database
-      # this function is called by Momomoto::Row#write
+      # Writes row back to database.
+      # This method is called by Momomoto::Row#write
       def write( row ) # :nodoc:
         if row.new_record?
           insert( row )
@@ -181,8 +244,8 @@ module Momomoto
         true
       end
 
-      # create an insert statement for a row
-      # do not call insert directly use row.write or Table.write( row ) instead
+      # Creates an insert statement for a row.
+      # Do not use it directly but use row.write or Table.write(row) instead.
       def insert( row )
         fields, values = [], []
         columns.each do | field_name, datatype |
@@ -205,8 +268,21 @@ module Momomoto
         database.execute( sql )
       end
 
-      # create an update statement for a row
-      # do not call update directly use row.write or Table.write( row ) instead
+      # Creates an update statement for a row.
+      # Do not call update directly but use row.write or Table.write(row) instead.
+      #
+      # Get the value of row.new_record? before writing to database to find out
+      # if you are updating a row that already exists in the database.
+      #
+      #   feed = Feeds.select_single( :url => "http://www.c3d2.de/news-atom.xml" )
+      #   feed.new_record? => false
+      #   feed[:url] = "https://www.c3d2.de/news-atom.xml"
+      #   feed.new_record? => false
+      #
+      #   feed = Feeds.select_or_new( :url => "http://astroblog.spaceboyz.net/atom.rb" )
+      #   feed.new_record? => true
+      #   feed.write => true
+      #   feed.new_record? => false
       def update( row )
         raise CriticalError, 'Updating is only allowed for tables with primary keys' if primary_keys.empty?
         setter, conditions = [], {}
@@ -222,7 +298,7 @@ module Momomoto
         database.execute( sql )
       end
 
-      # delete _row_ from the database
+      # delete _row_ from table
       def delete( row )
         raise CriticalError, 'Deleting is only allowed for tables with primary keys' if primary_keys.empty?
         raise Error, "this is a new record" if row.new_record?
@@ -243,7 +319,7 @@ module Momomoto
         classname.split('::').last.downcase.gsub(/[^a-z_0-9]/, '')
       end
 
-      # initialie a table class
+      # initializes a table class
       def initialize_table
 
         @table_name ||= construct_table_name( self.name )
@@ -266,7 +342,17 @@ module Momomoto
 
       end
 
-      # builds the row class for this table
+      # Builds the row class for this table when executing #select.
+      # In the default Row class proper setter and getter are available
+      # for all columns. However, if you only want to select a few
+      # columns as in
+      #
+      #   Feeds.select( {}, {:columns => [:url,:last_changed]} )
+      #
+      # #build_row_class does not return the default Row class for this table
+      # but invokes Base#initialize_row to create a new class without
+      # the setter and getter for the unused columns.
+      # For better performance the newly created class is cached in +@row_cache+.
       def build_row_class( options )
         if options[:columns]
           options[:columns] += primary_keys
@@ -286,7 +372,7 @@ module Momomoto
         end
       end
 
-      # compile the select clause
+      # compiles the select clause
       def compile_select( conditions, options )
         if options[:columns]
           cols = {}

data/lib/timeinterval.rb

@@ -1,31 +1,71 @@
 
 require 'date'
 
-# the class is used in Momomoto to represent the SQL interval datatype
+# The class is used in Momomoto to represent time intervals.
 class TimeInterval
 
   include Comparable
 
+  # Is raised if a String cannot be converted to some representation of
+  # TimeInterval.
+  #
+  #     TimeInterval.new( {:hour => '42', :min => '23'} )
+  #       => #<TimeInterval:0x505c565c @hour="42", @sec=0, @min="23">
+  #     TimeInterval.new('invalid')
+  #       => TimeInterval::ParseError: Could not parse interval 'invalid'
   class ParseError < StandardError; end
 
+  # Getter methods for hours, minutes and seconds
+  #
+  #   interval = TimeInterval.new( {:hour => 42, :min => 23} )
+  #     time.hour => 42
+  #     time.min => 23
+  #     time.sec => 0
   attr_reader :hour, :min, :sec
 
   class << self
 
+    # Creates and returns a new instance of TimeInterval from the given +interval+
+    #   interval = TimeInterval.new( "00:23" )
+    #     => #<TimeInterval:0x5235d458 @hour=0, @sec=0, @min=23>
     def parse( interval )
       TimeInterval.new( interval )
     end
 
   end
 
-  # compare two TimeInterval instances
-  # the comparison is done by calling to_i on other
+  # Compares two TimeInterval instances by converting into seconds and
+  # applying #<=> to them.
+  # Returns 1 (first > last), 0 (first == last) or -1 (first < last).
+  #
+  #   i1 = TimeInterval.new( {:hour => 42, :min => 23, :sec => 2} )
+  #     i1.to_i => 152582
+  #   i2 = TimeInterval.new( {:hour => 5, :min => 23, :sec => 2} )
+  #     i2.to_i => 19382
+  #
+  #   i1 <=> i2     #=> 1
+  #
   def <=>( other )
     self.to_i <=> other.to_i
   end
 
-  # formats timeinterval according to the directives in the give format
-  # string
+  # add to another TimeInterval instance
+  def +( other )
+    self.class.new( self.to_i + other.to_i )
+  end
+
+  # subtract something to a TimeInterval instance
+  def -( other )
+    self.class.new( self.to_i - other.to_i )
+  end
+
+  # Formats time interval according to the directives in the given format
+  # string.
+  #
+  #   i = TimeInterval.new(2342) #2342 seconds
+  #   i.strftime( "%H" )  => "00"
+  #   i.strftime( "%M" )  => "39"
+  #   i.strftime( "%S" )  => "02"
   def strftime( fmt = "%H:%M:%S" )
     fmt.gsub( /%(.)/ ) do | match |
       case match[1,1]
@@ -38,38 +78,72 @@ class TimeInterval
     end
   end
 
-  # returns the value of timeinterval as number of seconds
+  # Returns the value of time interval as number of seconds
   def to_i
     @hour * 3600 + @min * 60 + @sec
   end
 
   alias_method :to_int, :to_i
 
-  # Returns a string representing timeinterval. Equivalent to calling
+  # Returns the value of time interval as number of seconds
+  #   Time.now + TimeInterval.new(2342)
+  #     => Tue Dec 11 21:16:06 +0100 2007
+  def to_f
+    self.to_i.to_f
+  end
+
+  # Returns a string representing time interval. Equivalent to calling
   # Time#strftime with a format string of '%H:%M:%S'.
+  #
+  #   i.inspect  => "#<TimeInterval:0x517e36b8 @hour=0, @sec=2, @min=39>"
+  #   i.to_s     => "00:39:02"
+  #   i.strftime  => "00:39:02"
   def to_s
     strftime( '%H:%M:%S' )
   end
 
+  # Creates a new instance of TimeInterval with +d+ representing either
+  # a value of type #Hash
+  #
+  #   TimeInterval.new( {:hour => 5}),
+  #
+  # a value of type #Integer in seconds
+  #
+  #   TimeInterval.new( 23 ),
+  #
+  # or of type #String
+  #
+  #   TimeInterval.new( "00:23" ).
+  #
+  # Use getter methods #hour, #min and #sec in your code.
   def initialize( d = {} )
     case d
       when Hash then
-        @hour = d[:hour] || 0
-        @min = d[:min] || 0
-        @sec = d[:sec] || 0
+        init_from_hash( d )
       when Integer then
-        @hour = d/3600
-        @min = (d/60)%60
-        @sec = d%60
+        init_from_int( d )
       when String then
         parsed = Date._parse( d, false)
         if ( parsed.empty? && d.length > 0 ) || !(parsed.keys - [:hour,:min,:sec,:sec_fraction]).empty?
           raise ParseError, "Could not parse interval `#{d}`"
         end
-        @hour = parsed[:hour] || 0
-        @min = parsed[:min] || 0
-        @sec = parsed[:sec] || 0
+        init_from_hash( parsed )
     end
+
+  end
+
+  protected
+
+  def init_from_hash( d ) #:nodoc:
+    @hour = Integer( d[:hour] || 0 )
+    @min = Integer( d[:min] || 0 )
+    @sec = Integer( d[:sec] || 0 )
+  end
+
+  def init_from_int( d ) #:nodoc:
+    @hour = d/3600
+    @min = (d/60)%60
+    @sec = d%60
   end
 
 end