momomoto 0.1.13 → 0.1.14

data/Rakefile

@@ -28,11 +28,26 @@ begin
 rescue LoadError
 end
 
+desc "check documentation coverage"
+task :dcov do
+  sh "find lib -name '*.rb' | xargs dcov"
+end
+
 desc "create documentation for ri"
 task :doc do
   sh "rdoc -r lib"
 end
 
+desc "create html documentation"
+task :html do
+  sh "rdoc --template jamis --main Momomoto::Table --inline-source --force-update --webcvs 'http://trac.c3d2.de/momomoto/browser/trunk/%s' lib"
+end
+
+desc "update html documentation on momomoto.rubyforge.org"
+task :update_html do
+  sh "scp -r doc rubyforge:/var/www/gforge-projects/momomoto"
+end
+
 desc "run benchmark"
 task( :bench ) do | t |
   sh "ruby benchmark.rb"

data/lib/momomoto/base.rb

@@ -4,30 +4,70 @@ module Momomoto
 
   class << self
 
+    # Getter and setter for debugging.
+    # If +debug+ evaluates to +true+ then all SQL queries to the database
+    # are printed to STDOUT.
     attr_accessor :debug
 
+    # Returns an instance of Order::Lower where +args+ is either a single
+    # or array of +Symbol+ representing columns.
+    #
+    # Eases the use of class Order::Lower. You can use it whenever selecting
+    # rows or in #default_order.
+    #
+    #   order_lower = Momomoto.lower( :person )
+    #     => #<Momomoto::Order::Lower:0x5184131c @fields=[:person]>
+    #   Table.select( {}, {:order => order} )
+    #     => returns Table's rows ordered case-insensitively by column person
     def lower( *args )
       Momomoto::Order::Lower.new( *args )
     end
 
+    # Returns an instance of Order::Asc where +args+ is either a single
+    # or array of +Symbol+ representing columns.
+    #
+    # Eases the use of class Order::Asc. You can use it whenever selecting
+    # rows or in #default_order.
+    #
+    #   order_lower = Momomoto.asc( :person )
+    #     => #<Momomoto::Order::Asc:0x5184131c @fields=[:person]>
+    #   Table.select( {}, {:order => order} )
+    #     => returns Table's rows ordered asc by column person
     def asc( *args )
       Momomoto::Order::Asc.new( *args )
     end
 
+    # Returns an instance of Order::Asc where +args+ is either a single
+    # or array of +Symbol+ representing columns.
+    #
+    # Eases the use of class Order::Desc. You can use it whenever selecting
+    # rows or in #default_order.
+    #
+    #   order_lower = Momomoto.lower( :person )
+    #     => #<Momomoto::Order::Desc:0x5184131c @fields=[:person]>
+    #   Table.select( {}, {:order => order} )
+    #     => returns Table's rows ordered desc by column person
     def desc( *args )
       Momomoto::Order::Desc.new( *args )
     end
 
   end
 
-  ## base exception for all exceptions thrown by Momomoto
+  # Base exception for all exceptions thrown by Momomoto
   class Error < StandardError; end
 
-  # thrown when datatype conversion fails
+  # Thrown when datatype conversion fails and if a +block+ given to
+  # Table#select_or_new does not act on all primary keys.
   class ConversionError < Error; end
-  class CriticalError < Error; end
 
+  # Thrown when a critical error occurs.
+  class CriticalError < Error; end
+  
+  # Thrown when multiple values are found in Table#select_or_new or
+  # Table#select_single.
   class Too_many_records < Error; end
+
+  # Thrown when no row was found in Table#select_single.
   class Nothing_found < Error; end
 
 
@@ -36,9 +76,13 @@ module Momomoto
 
     class << self
 
+      # Getter for logical operator. This is used in #compile_where.
+      # See Table#select for usage of logical operators.
       attr_reader :logical_operator
 
-      # set the default logical operator for constraints
+      # Set the default logical operator for constraints. AND and OR are
+      # supported.
+      # See Table#select for usage of logical operators.
       def logical_operator=( value )
         @logical_operator = case value
           when /and/i then "AND"
@@ -47,12 +91,14 @@ module Momomoto
         end
       end
 
-      # set the schema name of the table this class operates on
+      # Set the schema name of the table this class operates on.
       def schema_name=( schema_name )
         @schema_name = schema_name
       end
 
-      # get the schema name of the table this class operates on
+      # Get the schema name of the table this class operates on. Invokes
+      # #schema_name= if +schema_name+ is given as parameter. Returns 
+      # +@schema_name+
       def schema_name( schema_name  = nil )
         return self.schema_name=( schema_name ) if schema_name
         if not instance_variable_defined?( :@schema_name )
@@ -63,9 +109,10 @@ module Momomoto
 
       protected
 
+      # Getter and setter used for marking tables as initialized.
       attr_accessor :initialized
 
-      # guesses the schema name of the table this class works on
+      # Guesses the schema name of the table this class works on.
       def construct_schema_name( classname )
         # Uncomment these lines to derive the schema from the enclosing namespace of the class
         #schema = classname.split('::')[-2]
@@ -73,7 +120,7 @@ module Momomoto
         'public'
       end
 
-      # get the database connection
+      # Get the database connection.
       def database # :nodoc:
         Momomoto::Database.instance
       end
@@ -85,6 +132,7 @@ module Momomoto
         where.empty? ? '' : " WHERE #{where}"
       end
 
+      # compiles subexpressions of the where-clause
       def compile_expression( conditions, operator )
         where = []
         case conditions
@@ -110,7 +158,10 @@ module Momomoto
       end
 
 
-      # compiles the sql statement defining the limit
+      # Compiles the sql statement defining the limit
+      #
+      #   #selects five feeds
+      #   five_feeds = Feeds.select( {},{:limit => 5} )
       def compile_limit( limit )
         " LIMIT #{Integer(limit)}"
        rescue => e
@@ -118,6 +169,9 @@ module Momomoto
       end
 
       # compiles the sql statement defining the offset
+      #
+      #   #selects five feeds ommitting the first 23 rows
+      #   five_feeds = Feeds.select( {}, {:offset => 23, :limit => 5} )
       def compile_offset( offset )
         " OFFSET #{Integer(offset)}"
        rescue => e
@@ -140,7 +194,18 @@ module Momomoto
         " ORDER BY #{order.join(',')}"
       end
 
-      # construct the Row class for the table
+      # Constructs the Row class for the given table or procedure +table+.
+      # If +columns+ is given as parameter to this method all setter and getter
+      # for the fields which are not included in columns will be removed.
+      #
+      # See Table#select for how this can be useful when only some columns are
+      # needed.
+      #
+      # module Methods can be used to modify setter and getter methods for columns.
+      # Methods is included to the row class after StandardMethods which holds all
+      # default accessors. That's why you can define your own accessors in Methods.
+      #
+      # See Row#set_column and Row#get_column for more information on this.
       def initialize_row( row, table, columns = table.columns )
 
         const_set( :Methods, Module.new ) if not const_defined?( :Methods )
@@ -173,8 +238,8 @@ module Momomoto
 
       end
 
-      # defines row setter and getter in the module StandardMethods which
-      # is later included in the Row class
+      # Defines row setter and getter in the module StandardMethods which
+      # is later included in the Row class.
       def define_row_accessors( method_module, table, columns )
         columns.each_with_index do | ( field_name, data_type ), index |
           method_module.instance_eval do

data/lib/momomoto/database.rb

@@ -36,6 +36,7 @@ module Momomoto
       @config = config
     end
 
+    # Eases the use of #config.
     def self.config( conf )
       instance.config( conf )
     end
@@ -45,6 +46,10 @@ module Momomoto
       @connection = nil
     end
 
+    # Connects to database
+    #   Momomoto::Database.config( :database=>:test, :username => 'test' )
+    #   Momomoto::Database.connect
+    #   # configure and connect
     def connect
       @connection.close if @connection
       @transaction_active = false
@@ -56,6 +61,11 @@ module Momomoto
       raise CriticalError, "Connection to database failed: #{e}"
     end
 
+    # Eases the use of #connect.
+    #
+    #   Momomoto::Database.config( :database=>:test, :username => 'test' )
+    #   Momomoto::Database.connect
+    #   # configure and connect
     def self.connect
       instance.connect
     end
@@ -115,7 +125,7 @@ module Momomoto
       columns
     end
 
-    # fetches the parameter of a stored procedure
+    # fetches parameters of a stored procedure
     def fetch_procedure_parameters( procedure_name, schema_name = nil ) # :nodoc:
       p = []
       conditions = { :procedure_name => procedure_name }
@@ -125,14 +135,14 @@ module Momomoto
       end
       # mark parameters of strict procedures as not null
       if Information_schema::Routines.select_single(:routine_name=>procedure_name).is_null_call == 'YES'
-        p.each do | param | 
-          param[param.keys.first].instance_variable_set(:@not_null,true) 
+        p.each do | param |
+          param[param.keys.first].instance_variable_set(:@not_null,true)
         end
       end
       p
     end
 
-    # fetches the resultset columns of a stored procedure
+    # fetches the result set columns of a stored procedure
     def fetch_procedure_columns( procedure_name, schema_name = nil ) # :nodoc:
       c = {}
       conditions = { :procedure_name => procedure_name }
@@ -177,10 +187,12 @@ module Momomoto
       @transaction_active = false
     end
 
+    # escapes the given string +input+
     def self.escape_string( input )
       PGconn.escape( input )
     end
 
+    # escapes the given binary data +input+
     def self.escape_bytea( input )
       PGconn.escape_bytea( input )
     end

data/lib/momomoto/datatype/base.rb

@@ -1,39 +1,61 @@
 
 module Momomoto
 
+  # This module encapsulates all supported data types, i.e.:
+  # Numeric, Integer, Bigint, Smallint, Real,
+  # Timestamp_with_time_zone, Timestamp_without_time_zone,
+  # Time_with_time_zone, Time_without_time_zone, Date, Interval,
+  # Character, Character_varying, Bytea, Text, Inet and Boolean.
+  #
+  # Refer to http://www.postgresql.org/docs/8.2/static/datatype.html
+  # for more information on the specific data types.
   module Datatype
-    # base class for all datatypes
+
+    # Every data type class (see #Datatype) is derived from this class.
     class Base
-      # get the default value for this column
-      # returns false if none exists
+
+      # Gets the default value for this column or returns nil if none
+      # exists.
       def default
         @default
       end
 
-      # is this column a not null column
+      # Returns true if this column can be NULL otherwise false.
       def not_null?
         @not_null
       end
 
+      # Creates a new instance of the special data type, setting +not_null+
+      # and +default+ according to the values from Information Schema.
       def initialize( row = nil )
-        @not_null = row.respond_to?(:is_nullable) && row.is_nullable == "NO"
-        @default = row.respond_to?( :column_default) && row.column_default
+        @not_null = row.respond_to?(:is_nullable) && row.is_nullable == "NO" ? true : false
+        @default = row.respond_to?(:column_default) ? row.column_default : nil
       end
 
-      # values are filtered by this function when being set
+      # Values are filtered by this function when being set. See the
+      # method in the appropriate derived data type class for allowed
+      # values.
       def filter_set( value ) # :nodoc:
         value
       end
 
+      # Compares two values and return true if equal or false otherwise.
+      # It is used to check if a row field has been changed so that only
+      # changed fields are written to database.
       def equal( a, b )
         a == b
       end
 
+      # Escapes +input+ to be saved in database.
+      # If +input+ equals nil, NULL is returned, otherwise Database#escape_string
+      # is called.
+      # This method is overwritten to get data type-specific escaping rules.
       def escape( input )
         input.nil? ? "NULL" : "'" + Database.escape_string( input.to_s ) + "'"
       end
 
-      # this functions is used for compiling the where clause
+      # This method is used when compiling the where clause. No need
+      # for direct use.
       def compile_rule( field_name, value ) # :nodoc:
         case value
           when nil then
@@ -66,6 +88,25 @@ module Momomoto
         end
       end
 
+      # These are operators supported by all data types. In your select
+      # statement use something like:
+      #
+      #   one_day_ago = Time.now - (3600*24)
+      #   Feeds.select( :date => {:ge => one_day_ago.to_s} )
+      #
+      # This will select all rows from Feeds that are newer than 24 hours.
+      # Same with Momomoto's TimeInterval:
+      #
+      #   one_day_ago = Time.now + TimeInterval.new({:hour => -24})
+      #   Feeds.select( :date => {:ge => one_day_ago.to_s} )
+      #
+      # In case of data type Text also +:like+ and +:ilike+ are supported.
+      # For +:like+ and +:ilike+ operators you may use _ as placeholder for
+      # a single character or % as placeholder for multiple characters.
+      #
+      #   # Selects all posts having "surveillance" in their content field
+      #   # while ignoring case.
+      #   Posts.select( :content => {:ilike => 'surveillance'} )
       def self.operator_sign( op )
         case op
           when :le then '<='

data/lib/momomoto/datatype/bigint.rb

@@ -1,8 +1,9 @@
 module Momomoto
   module Datatype
 
+    # Represents values of type Bigint derived from Integer
     class Bigint < Integer
-    
+
     end
 
   end

data/lib/momomoto/datatype/boolean.rb

@@ -1,7 +1,14 @@
 module Momomoto
   module Datatype
+
+    # This class represents values of boolean type.
     class Boolean < Base
 
+      # Values are filtered by this method when being set.
+      # Returns true or false.
+      # If the given +value+ cannot be converted to true or false
+      # and NULL is not allowed, than again return false. Otherwise
+      # return +nil+.
       def filter_set( value )
         case value
           when true, 1, 't', 'true', 'on' then true
@@ -10,6 +17,8 @@ module Momomoto
         end
       end
 
+      # Converts the given +input+ to true or false if possible.
+      # Otherwise returns NULL.
       def escape( input )
         case input
           when true, 1, 't', 'true', 'on' then "'t'"

data/lib/momomoto/datatype/bytea.rb

@@ -1,8 +1,12 @@
 
 module Momomoto
   module Datatype
+
+    # This class is used for Binary Data (Byte Array).
     class Bytea < Base
 
+      # Escapes +input+ using Database#escape_bytea or returns NULL if
+      # +input+ is nil.
       def escape( input )
         input.nil? ? "NULL" : "E'" + Database.escape_bytea( input ) + "'"
       end

data/lib/momomoto/datatype/character.rb

@@ -1,5 +1,7 @@
 module Momomoto
   module Datatype
+
+    # Represents character data type.
     class Character < Text
     
     end

data/lib/momomoto/datatype/character_varying.rb

@@ -1,5 +1,7 @@
 module Momomoto
   module Datatype
+
+    # Represents the Character Varying data type.
     class Character_varying < Text
     
     end

data/lib/momomoto/datatype/date.rb

@@ -3,8 +3,13 @@ require 'date'
 
 module Momomoto
   module Datatype
+
+    # Represents the data type Date.
     class Date < Base
 
+      # Values are filtered by this function when being set.
+      # Returns ruby's Date or tries to build a Date from a String.
+      # Raises ConversionError if the given +value+ cannot be parsed.
       def filter_set( value )
         case value
           when nil,'' then nil