lardawge-rfm 1.4.0 → 1.4.1

data/lib/rfm/error.rb

@@ -1,256 +1,186 @@
-require "set"
-
-# These classes wrap the filemaker error codes. FileMakerError is the base class of this hierarchy.
-# 
-# One could get a FileMakerError by doing:
-#   err = Rfm::Error::FileMakerError.getError(102)
-# 
-# The above code would return a FieldMissingError instance. Your could use this instance to raise that appropriate
-# exception:
-# 
-#   raise err 
-# 
-# You could access the specific error code by accessing:
-#   
-#   err.code
-#   
-# Author::    Mufaddal Khumri
-# Copyright:: Copyright (c) 2007 Six Fried Rice, LLC and Mufaddal Khumri
-# License::   See MIT-LICENSE for details
 module Rfm
+  
+  # Error is the base for the error hierarchy representing errors returned by Filemaker.
+  # 
+  # One could raise a FileMakerError by doing:
+  #   raise Rfm::Error.getError(102)
+  #
+  # It also takes an optional argument to give a more discriptive error message:
+  #   err = Rfm::Error.getError(102, 'add description with more detail here')
+  # 
+  # The above code would return a FieldMissing instance. Your could use this instance to raise that appropriate
+  # exception:
+  # 
+  #   raise err 
+  # 
+  # You could access the specific error code by accessing:
+  #   
+  #   err.code
   module Error
     
-    class RfmError < StandardError
-    end
-    
-    class CommunicationError < RfmError
-    end
-    
-    class ParameterError < RfmError
-    end
-    
-    class AuthenticationError < RfmError
-    end
-    
-    # Base class for all FileMaker errors
-    class FileMakerError < RfmError
-      attr_accessor :code
+    class RfmError < StandardError #:nodoc:
+      attr_reader :code
       
-      # Default filemaker error message map
-      @default_messages = {}
-      class << self; attr_reader :default_messages; end
-      
-      
-      # This method instantiates and returns the appropriate FileMakerError object depending on the error code passed to it. It
-      # also accepts an optional message.
-      def self.getError(code, message = nil)
-        if @default_messages == nil or @default_messages.size == 0
-          (0..99).each{|i| @default_messages[i] = 'SystemError occurred.'}
-          (100..199).each{|i| @default_messages[i] = 'MissingError occurred.'}
-          @default_messages[102] = 'FieldMissingError occurred.'
-          @default_messages[104] = 'ScriptMissingError occurred.'
-          @default_messages[105] = 'LayoutMissingError occurred.'
-          @default_messages[106] = 'TableMissingError occurred.'
-          (200..299).each{|i| @default_messages[i] = 'SecurityError occurred.'}
-          @default_messages[200] = 'RecordAccessDeniedError occurred.'
-          @default_messages[201] = 'FieldCannotBeModifiedError occurred.'
-          @default_messages[202] = 'FieldAccessIsDeniedError occurred.'
-          (300..399).each{|i| @default_messages[i] = 'ConcurrencyError occurred.'}
-          @default_messages[301] = 'RecordInUseError occurred.'
-          @default_messages[302] = 'TableInUseError occurred.'
-          @default_messages[306] = 'RecordModIdDoesNotMatchError occurred.'
-          (400..499).each{|i| @default_messages[i] = 'GeneralError occurred.'}
-          @default_messages[401] = 'NoRecordsFoundError occurred.'
-          (500..599).each{|i| @default_messages[i] = 'ValidationError occurred.'}
-          @default_messages[500] = 'DateValidationError occurred.'
-          @default_messages[501] = 'TimeValidationError occurred.'
-          @default_messages[502] = 'NumberValidationError occurred.'
-          @default_messages[503] = 'RangeValidationError occurred.'
-          @default_messages[504] = 'UniqueValidationError occurred.'
-          @default_messages[505] = 'ExistingValidationError occurred.'
-          @default_messages[506] = 'ValueListValidationError occurred.'
-          @default_messages[507] = 'ValidationCalculationError occurred.'
-          @default_messages[508] = 'InvalidFindModeValueError occurred.'
-          @default_messages[511] = 'MaximumCharactersValidationError occurred.'
-          (800..899).each{|i| @default_messages[i] = 'FileError occurred.'}
-          @default_messages[802] = 'UnableToOpenFileError occurred.'
-        end 
-        
-        message = @default_messages[code] if message == nil || message.strip == ''
-        message += " (FileMaker Error ##{code})"
-        
-        if 0 <= code and code <= 99
-          err = SystemError.new(message)
-        elsif 100 <= code and code <= 199
-          if code == 101
-            err = RecordMissingError.new(message)
-          elsif code == 102
-            err = FieldMissingError.new(message)
-          elsif code == 104
-            err = ScriptMissingError.new(message)
-          elsif code == 105
-            err = LayoutMissingError.new(message)
-          elsif code == 106
-            err = TableMissingError.new(message)
-          else
-            err = MissingError.new(message)
-          end
-        elsif 200 <= code and code <= 299
-          if code == 200
-            err = RecordAccessDeniedError.new(message)
-          elsif code == 201
-            err = FieldCannotBeModifiedError.new(message)
-          elsif code == 202
-            err = FieldAccessIsDeniedError.new(message)
-          else
-            err = SecurityError.new(message)
-          end
-        elsif 300 <= code and code <= 399
-          if code == 301
-            err = RecordInUseError.new(message)
-          elsif code == 302
-            err = TableInUseError.new(message)
-          elsif code == 306
-            err = RecordModIdDoesNotMatchError.new(message)
-          else
-            err = ConcurrencyError.new(message)
-          end
-        elsif 400 <= code and code <= 499
-          if code == 401
-            err = NoRecordsFoundError.new(message)
-          else
-            err = GeneralError.new(message)
-          end
-        elsif 500 <= code and code <= 599
-          if code == 500
-            err = DateValidationError.new(message)
-          elsif code == 501
-            err = TimeValidationError.new(message)
-          elsif code == 502
-            err = NumberValidationError.new(message)
-          elsif code == 503
-            err = RangeValidationError.new(message)
-          elsif code == 504
-            err = UniqueValidationError.new(message)
-          elsif code == 505
-            err = ExistingValidationError.new(message)
-          elsif code == 506
-            err = ValueListValidationError.new(message)
-          elsif code == 507
-            err = ValidationCalculationError.new(message)
-          elsif code == 508
-            err = InvalidFindModeValueError.new(message)
-          elsif code == 511
-            err = MaximumCharactersValidationError.new(message)
-          else
-            err = ValidationError.new(message)
-          end
-        elsif 800 <= code and code <= 899
-          if code == 802
-            err = UnableToOpenFileError.new(message)
-          else
-            err = FileError.new(message)
-          end
-        else 
-          # called for code == -1 or any other code not handled above.
-          err = UnknownError.new(message)
-        end
-        err.code = code
-        return err
-      end    
+      def initialize(code, message=nil)
+        @code = code
+        super(message)
+      end
     end
-    
-    class UnknownError < FileMakerError  
+
+    class UnknownError < RfmError 
     end
     
-    class SystemError < FileMakerError  
+    class SystemError  < RfmError
     end
     
-    class MissingError < FileMakerError  
+    class MissingError < RfmError
     end
-    
-    class RecordMissingError < MissingError  
+
+    class RecordMissingError < MissingError #:nodoc:
     end
-  
-    class FieldMissingError < MissingError  
+
+    class FieldMissingError  < MissingError #:nodoc:
     end
-  
-    class ScriptMissingError < MissingError  
+
+    class ScriptMissingError < MissingError #:nodoc: 
     end
-  
-    class LayoutMissingError < MissingError  
+
+    class LayoutMissingError < MissingError #:nodoc: 
     end
-  
-    class TableMissingError < MissingError  
+
+    class TableMissingError  < MissingError #:nodoc:
     end
-  
-    class SecurityError < FileMakerError  
+
+    class SecurityError < RfmError #:nodoc:
     end
-    
-    class RecordAccessDeniedError < SecurityError  
+
+    class RecordAccessDeniedError < SecurityError #:nodoc:
     end
-  
-    class FieldCannotBeModifiedError < SecurityError  
+
+    class FieldCannotBeModifiedError < SecurityError #:nodoc:
     end
-  
-    class FieldAccessIsDeniedError < SecurityError  
+
+    class FieldAccessIsDeniedError < SecurityError #:nodoc:
     end
-    
-    class ConcurrencyError < FileMakerError  
+
+    class ConcurrencyError < RfmError #:nodoc:
     end
-    
-    class RecordInUseError < ConcurrencyError  
+
+    class RecordInUseError < ConcurrencyError #:nodoc:
     end
-  
-    class TableInUseError < ConcurrencyError  
+
+    class TableInUseError < ConcurrencyError #:nodoc:
     end
-  
-    class RecordModIdDoesNotMatchError < ConcurrencyError  
+
+    class RecordModIdDoesNotMatchError < ConcurrencyError #:nodoc:
     end
-  
-    class GeneralError < FileMakerError  
+
+    class GeneralError < RfmError #:nodoc:
     end
-  
-    class NoRecordsFoundError < GeneralError  
+
+    class NoRecordsFoundError < GeneralError #:nodoc:
     end
-     
-    class ValidationError < FileMakerError  
+
+    class ValidationError < RfmError #:nodoc:
     end 
-  
-    class DateValidationError < ValidationError  
+
+    class DateValidationError < ValidationError #:nodoc:
     end
-  
-    class TimeValidationError < ValidationError  
+
+    class TimeValidationError < ValidationError #:nodoc:
     end
-    
-    class NumberValidationError < ValidationError  
+
+    class NumberValidationError < ValidationError #:nodoc: 
     end
-    
-    class RangeValidationError < ValidationError  
+
+    class RangeValidationError < ValidationError #:nodoc:
     end
-  
-    class UniqueValidationError < ValidationError  
+
+    class UniqueValidationError < ValidationError #:nodoc:
     end
-    
-    class ExistingValidationError < ValidationError  
+
+    class ExistingValidationError < ValidationError #:nodoc:
     end
-  
-    class ValueListValidationError < ValidationError  
+
+    class ValueListValidationError < ValidationError #:nodoc:
     end
-  
-    class ValidationCalculationError < ValidationError  
+
+    class ValidationCalculationError < ValidationError #:nodoc:
     end
-  
-    class InvalidFindModeValueError < ValidationError  
+
+    class InvalidFindModeValueError < ValidationError #:nodoc:
     end
-  
-    class MaximumCharactersValidationError < ValidationError  
+
+    class MaximumCharactersValidationError < ValidationError #:nodoc:
     end
-  
-    class FileError < FileMakerError  
+
+    class FileError < RfmError #:nodoc:
     end 
-  
-    class UnableToOpenFileError < FileError  
+
+    class UnableToOpenFileError < FileError #:nodoc:
+    end
+    
+    extend self
+    # This method returns the appropriate FileMaker object depending on the error code passed to it. It
+    # also accepts an optional message.
+    def getError(code, message=nil)
+      klass   = find_by_code(code)
+      message = build_message(klass, code, message)
+      error   = klass.new(code, message)
+      error
+    end
+    
+    def build_message(klass, code, message=nil) #:nodoc:
+      msg =  ": #{message}"
+      msg << " " unless message.nil?
+      msg << "(FileMaker Error ##{code})"
+      
+      "#{klass.to_s.gsub(/Rfm::Error::/, '')} occurred#{msg}"
+    end
+    
+    def find_by_code(code) #:nodoc:
+      case code
+      when 0..99 then SystemError
+      when 100..199
+        if code == 101; RecordMissingError
+        elsif code == 102; FieldMissingError
+        elsif code == 104; ScriptMissingError
+        elsif code == 105; LayoutMissingError
+        elsif code == 106; TableMissingError
+        else; MissingError; end
+      when 203..299
+        if code == 200; RecordAccessDeniedError
+        elsif code == 201; FieldCannotBeModifiedError
+        elsif code == 202; FieldAccessIsDeniedError
+        else; SecurityError; end
+      when 300..399
+        if code == 301; RecordInUseError
+        elsif code == 302; TableInUseError
+        elsif code == 306; RecordModIdDoesNotMatchError
+        else; ConcurrencyError; end
+      when 400..499
+       if code == 401; NoRecordsFoundError
+       else; GeneralError; end
+      when 500..599
+        if code == 500; DateValidationError
+        elsif code == 501; TimeValidationError
+        elsif code == 502; NumberValidationError
+        elsif code == 503; RangeValidationError
+        elsif code == 504; UniqueValidationError
+        elsif code == 505; ExistingValidationError
+        elsif code == 506; ValueListValidationError
+        elsif code == 507; ValidationCalculationError
+        elsif code == 508; InvalidFindModeValueError
+        elsif code == 511; MaximumCharactersValidationError
+        else; ValidationError
+        end
+      when 800..899
+        if code == 802; UnableToOpenFileError
+        else; FileError; end
+      else
+        UnknownError
+      end
     end
   end
+  
 end

data/lib/rfm/{commands/layout.rb → layout.rb}

@@ -136,24 +136,10 @@ module Rfm
     def initialize(name, db)
       @name = name
       @db = db
-      
-      @loaded = false
-      @field_controls = Rfm::Utility::CaseInsensitiveHash.new
-      @value_lists = Rfm::Utility::CaseInsensitiveHash.new
     end
     
     attr_reader :name, :db
     
-    def field_controls
-      load unless @loaded
-      @field_controls
-    end
-    
-    def value_lists
-      load unless @loaded
-      @value_lists
-    end
-    
     # Returns a ResultSet object containing _every record_ in the table associated with this layout.
     def all(options = {})
       get_records('-findall', {}, options)
@@ -223,49 +209,10 @@ module Rfm
     
     private
     
-    def load
-      @loaded = true
-      fmpxmllayout = @db.server.load_layout(self).body
-      doc = REXML::Document.new(fmpxmllayout)
-      root = doc.root
-      
-      # check for errors
-      error = root.elements['ERRORCODE'].text.to_i
-      raise Rfm::Error::FileMakerError.getError(error) if error != 0
-      
-      # process valuelists
-      if root.elements['VALUELISTS'].size > 0
-        root.elements['VALUELISTS'].each_element('VALUELIST') { |valuelist|
-          name = valuelist.attributes['NAME']
-          @value_lists[name] = valuelist.elements.collect {|e| e.text}
-        }
-        @value_lists.freeze
-      end
-      
-      # process field controls
-      root.elements['LAYOUT'].each_element('FIELD') { |field| 
-        name = field.attributes['NAME']
-        style = field.elements['STYLE'].attributes['TYPE']
-        value_list_name = field.elements['STYLE'].attributes['VALUELIST']
-        value_list = @value_lists[value_list_name] if value_list_name != ''
-        field_control = FieldControl.new(name, style, value_list_name, value_list)
-        existing = @field_controls[name]
-        if existing
-          if existing.kind_of?(Array)
-            existing << field_control
-          else
-            @field_controls[name] = Array[existing, field_control]
-          end
-        else
-          @field_controls[name] = field_control
-        end
-      }
-      @field_controls.freeze      
-    end
-    
     def get_records(action, extra_params = {}, options = {})
-      Rfm::Result::ResultSet.new(@db.server, @db.server.do_action(@db.account_name, 
-      @db.password, action, params().merge(extra_params), options).body, self)
+      include_portals = options[:include_portals] ? options.delete(:include_portals) : nil
+      xml_response = @db.server.connect(@db.account_name, @db.password, action, params.merge(extra_params), options).body
+      Rfm::Resultset.new(@db.server, xml_response, self, include_portals)
     end
     
     def params

data/lib/rfm/metadata/field.rb

@@ -0,0 +1,93 @@
+module Rfm
+  module Metadata
+    # The Field object represents a single FileMaker field. It *does not hold the data* in the field. Instead,
+    # it serves as a source of metadata about the field. For example, if you're script is trying to be highly
+    # dynamic about its field access, it may need to determine the data type of a field at run time. Here's
+    # how:
+    #
+    #   field_name = "Some Field Name"
+    #   case myRecord.fields[field_name].result
+    #   when "text"
+    #     # it is a text field, so handle appropriately
+    #   when "number"
+    #     # it is a number field, so handle appropriately
+    #   end
+    #
+    # =Attributes
+    #
+    # The Field object has the following attributes:
+    #
+    # * *name* is the name of the field
+    #
+    # * *result* is the data type of the field; possible values include:
+    #   * text
+    #   * number
+    #   * date
+    #   * time
+    #   * timestamp
+    #   * container
+    #
+    # * *type* any of these:
+    #   * normal (a normal data field)
+    #   * calculation
+    #   * summary
+    #
+    # * *max_repeats* is the number of repetitions (1 for a normal field, more for a repeating field)
+    #
+    # * *global* is +true+ is this is a global field, *false* otherwise
+    #
+    # Note: Field types match FileMaker's own values, but the terminology differs. The +result+ attribute
+    # tells you the data type of the field, regardless of whether it is a calculation, summary, or normal
+    # field. So a calculation field whose result type is _timestamp_ would have these attributes:
+    #
+    # * result: timestamp
+    # * type: calculation
+    #
+    # * *control& is a FieldControl object representing the sytle and value list information associated
+    #   with this field on the layout.
+    # 
+    # Note: Since a field can sometimes appear on a layout more than once, +control+ may be an Array.
+    # If you don't know ahead of time, you'll need to deal with this. One easy way is:
+    #
+    #   controls = [myField.control].flatten
+    #   controls.each {|control|
+    #     # do something with the control here
+    #   }
+    #
+    # The code above makes sure the control is always an array. Typically, though, you'll know up front
+    # if the control is an array or not, and you can code accordingly.
+    
+    class Field
+      
+      attr_reader :name, :result, :type, :max_repeats, :global
+      
+      # Initializes a field object. You'll never need to do this. Instead, get your Field objects from
+      # ResultSet::fields
+      def initialize(field)
+        @name        = field['name']
+        @result      = field['result']
+        @type        = field['type']
+        @max_repeats = field['max-repeats']
+        @global      = field['global']
+      end
+    
+      # Coerces the text value from an +fmresultset+ document into proper Ruby types based on the 
+      # type of the field. You'll never need to do this: Rfm does it automatically for you when you
+      # access field data through the Record object.
+      def coerce(value, resultset)
+        return nil if value.empty?
+        case self.result
+        when "text"      then value
+        when "number"    then BigDecimal.new(value)
+        when "date"      then Date.strptime(value, resultset.date_format)
+        when "time"      then DateTime.strptime("1/1/-4712 #{value}", "%m/%d/%Y #{resultset.time_format}")
+        when "timestamp" then DateTime.strptime(value, resultset.timestamp_format)
+        when "container" then URI.parse("#{resultset.server.scheme}://#{resultset.server.host_name}:#{resultset.server.port}#{value}")
+        else nil
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/rfm/metadata/script.rb

@@ -0,0 +1,20 @@
+module Rfm
+  module Metadata
+    # The Script object represents a FileMaker script. At this point, the Script object exists only so
+    # you can enumrate all scripts in a Database (which is a rare need):
+    # 
+    #   myDatabase.script.each {|script|
+    #     puts script.name
+    #   }
+    #
+    # If you want to _run_ a script, see the Layout object instead.
+    class Script
+      def initialize(name, db)
+        @name = name
+        @db = db
+      end
+      
+      attr_reader :name
+    end
+  end
+end