rets4r 0.8.2

data/lib/rets4r/client/data.rb

@@ -0,0 +1,14 @@
+module RETS4R
+	class Client
+		# Represents a row of data. Nothing more than a glorfied Hash with a custom constructor and a
+		# type attribute.
+		class Data < ::Hash
+			attr_accessor :type
+			
+			def initialize(type = false)
+				super
+				self.type = type
+			end
+		end
+	end
+end 

data/lib/rets4r/client/dataobject.rb

@@ -0,0 +1,20 @@
+module RETS4R
+	class Client
+		# Represents a RETS object (as returned by the get_object) transaction.
+		class DataObject
+			attr_accessor :type, :data
+			
+			alias :info :type
+			
+			def initialize(type, data)
+				self.type = type
+				self.data = data
+			end
+			
+			def success?
+				return true if self.data
+				return false
+			end
+		end
+	end
+end

data/lib/rets4r/client/metadata.rb

@@ -0,0 +1,15 @@
+require 'rets4r/client/data'
+
+module RETS4R
+	class Client
+		# Represents a set of metadata. It is simply an extended Array with type and attributes accessors.
+		class Metadata < Array
+			attr_accessor :type, :attributes
+			
+			def initialize(type = false)
+				self.type = type if type
+				self.attributes = {}
+			end
+		end
+	end
+end

data/lib/rets4r/client/metadataindex.rb

@@ -0,0 +1,82 @@
+module RETS4R
+	class Client
+		# Provides a means of indexing metadata to allow faster searching of it.
+		# This is in dire need of a review and cleanup, so I advise you not to use it until that has been done.
+		class MetadataIndex
+			# Constructor that takes an array of Metadata objects as its sole argument.
+			def initialize(metadata)
+				@metadata 	= metadata
+				@index	= index(@metadata)
+			end
+			
+			# WARNING! Not working properly (does NOT pass unit test)
+			# This is more of a free form search than #lookup, but it is also slower because it must iterate
+			# through the entire metadata array. This also returns multiple matches, which #lookup doesn't do.
+			def search(type, attributes = {})
+				matches = []
+				
+				@metadata.each do |meta|
+					catch :mismatch do
+						if meta.type == type
+							attributes.each do |k,v|
+								throw :mismatch unless meta.attributes[k] == v
+							end
+							
+							matches << meta
+						end
+					end
+				end
+				
+				return matches
+			end
+			
+			# This is a streamlined and probably the preferred method for looking up metadata because it
+			# uses a index to quickly access the data. The downside is that it is not very flexible. This also
+			# only returns one (the "best") match. If you need multiple matches, then you should use #search.
+			# Tests show about a 690% speed increase by using #lookup over #search, so you've been warned.
+			def lookup(type, *attributes)
+				key = type
+				key << attributes.join('')
+				
+				@index[key]
+			end
+			
+			private
+			
+			# Provided an array of metadata, it indexes it for faster lookup.
+			# Takes a +Metadata+ object as its argument.
+			def index(metadata)
+				index = {}
+				
+				metadata.each do |meta|
+					key = generate_key(meta)
+					
+					index[key] = meta
+				end
+				
+				return index
+			end
+			
+			# Used to generate the key for a specified piece of metadata. Takes a +Metadata+ object as its
+			# argument.
+			def generate_key(meta)
+				key = meta.type
+					
+				case (meta.type)
+					when 'METADATA-LOOKUP'
+						key << meta.attributes['Resource']
+					when 'METADATA-LOOKUP_TYPE'
+						key << meta.attributes['Resource'] << meta.attributes['Lookup']
+					when 'METADATA-CLASS'
+						key << meta.attributes['Resource']
+					when 'METADATA-OBJECT'
+						key << meta.attributes['Resource']
+					when 'METADATA-TABLE'
+						key << meta.attributes['Resource'] << meta.attributes['Class']
+				end
+				
+				return key
+			end
+		end
+	end
+end

data/lib/rets4r/client/parser.rb

@@ -0,0 +1,135 @@
+# This is the generic parser 
+#
+#	Supports responses, data, metadata, reply codes, and reply text.
+#
+#	Supports the following tags:
+#		RETS, METADATA-.*, MAXROWS, COLUMNS, DATA, COUNT, DELIMITER
+#
+#	Metadata is built as:
+#		(Metadata 1-> data row
+#		           -> data row),
+#		(Metadata 2 -> data row),
+#		etc.
+#
+#	Data is built as:
+#		Data 1, Data 2, Data N
+#
+#
+#	TODO
+#		Add comments/documentation
+#		Handle more tags (if any are unaccounted for)
+#   Handle standard (non-compact) output
+#		Case Insensitivity?
+# 	There is still some holdovers from the previous organization of parsers, and they should be cleaned
+# 	  up at some point.
+
+require 'cgi'
+
+module RETS4R
+	class Client
+		module Parser			
+			attr_accessor :output, :logger
+			
+			def initialize
+				@transaction = Transaction.new
+				@current	   = []
+				@output      = 2
+			end
+			
+			def get_transaction
+				@transaction
+			end
+					
+			#### Stream Listener Events
+			def tag_start(name, attrs)		
+				@current.push(name)
+	
+				case name
+					when 'RETS'
+						@transaction.reply_code = attrs['ReplyCode']
+						@transaction.reply_text = attrs['ReplyText']
+					when /METADATA.*/
+						@metadata = Metadata.new(name)
+						@metadata.attributes = attrs
+					when 'MAXROWS'
+						@transaction.maxrows = true
+					when 'COUNT'
+						@transaction.count     = attrs['Records'].to_i
+					when 'DELIMITER'
+						@transaction.delimiter = attrs['value'].to_i
+				end
+			end
+			
+			def text(text)
+				case @current[-1]
+					when 'COLUMNS'
+						@transaction.header = parse_compact_line(text, @transaction.ascii_delimiter)
+						
+					when 'DATA'
+						if @transaction.header.length > 0
+							data_type << parse_data(text, @transaction.header)
+						else
+							data_type << parse_compact_line(text, @transaction.ascii_delimiter)
+						end
+					
+					when 'RETS-RESPONSE'
+						@transaction.response = parse_key_value_body(text)
+				end
+			end
+			
+			def tag_end(name)
+				@current.pop
+				
+				@transaction.data << @metadata if name =~ /METADATA.*/
+			end
+			
+			#### Helper Methods
+			def clean_xml(xml)				
+				# This is a hack, and it assumes that we're using compact mode, but it's the easiest way to
+				# strip out those bad "<" and ">" characters that were not properly escaped...
+				xml.gsub!(/<DATA>(.*)<\/DATA>/i) do |match|
+					"<DATA>#{CGI::escapeHTML(CGI::unescapeHTML($1))}</DATA>"
+				end
+			end
+			
+			def data_type
+				if @current[-2].index('METADATA') === 0
+					return @metadata
+				else
+					return @transaction.data
+				end
+			end
+			
+			def parse_compact_line(data, delim = "\t")
+				begin
+					return data.to_s.strip.split(delim)
+				rescue
+					raise "Error while parsing compact line: #{$!} with data: #{data}"
+				end
+			end
+			
+			def parse_data(data, header)			
+				results = Data.new(@current[-2])
+				
+				parsed_data = parse_compact_line(data, @transaction.ascii_delimiter)
+				
+				header.length.times do |pos|
+					results[header[pos]] = parsed_data[pos]
+				end
+				
+				results
+			end
+			
+			def parse_key_value_body(data)
+				parsed = {}
+				
+				data.each do |line|
+					(key, value) = line.strip.split('=')
+					parsed[key] = value
+				end
+				
+				return parsed
+			end
+		end
+	end
+end

data/lib/rets4r/client/parser/rexml.rb

@@ -0,0 +1,75 @@
+require 'rets4r/client/parser'
+require 'rexml/parsers/baseparser'
+require 'rexml/parsers/streamparser'
+require 'rexml/streamlistener'
+require 'rets4r/client/transaction'
+require 'rets4r/client/data'
+require 'rets4r/client/metadata'
+
+module RETS4R
+	class Client
+		module Parser
+			class REXML
+				include Parser
+
+				SUPPORTED_PARSERS << self
+				
+				attr_accessor :logger
+				
+				def initialize
+					@transaction = Transaction.new
+					@current	   = []
+				end
+				
+				def parse(xml, output = false, do_retry = true)
+					output = self.output unless output # Allow per-parse output changes
+					
+					return xml if output == OUTPUT_RAW
+					
+					# This is an legacy option that is not currently supported by XMLParser, but it is left in
+					# here for reference or "undocumented usage."
+					if output == OUTPUT_DOM
+						return ::REXML::Document.new(xml)
+					end			
+					
+					# If we're here, then we need to output a RETS::Data object
+					listener = StreamListener.new
+					
+					begin
+						stream = ::REXML::Parsers::StreamParser.new(xml, listener)
+						stream.parse
+					rescue ::REXML::ParseException, Exception
+						# We should get fancier here and actually check the type of error, but, err, oh well.
+						if do_retry
+							logger.info("Unable to parse XML on first try due to '#{$!}'. Now retrying.") if logger
+							
+							return parse(clean_xml(xml), output, false)
+						else
+							ex = ParserException.new($!)
+							ex.file = xml
+							
+							logger.error("REXML parser was unable to parse XML: #{$!}") if logger
+							logger.error("Unparsable XML was:\n#{xml}") if logger
+							
+							raise ex
+						end
+					end
+					
+					return listener.get_transaction
+				end
+				
+				class StreamListener
+					include ::REXML::StreamListener
+					include Parser				
+
+					def initialize(logger = nil)
+						self.logger  = logger
+						@transaction = Transaction.new
+						@current	   = []
+						@output      = 2
+					end
+				end
+			end
+		end
+	end
+end	

data/lib/rets4r/client/parser/xmlparser.rb

@@ -0,0 +1,95 @@
+# Because XMLParser may not be present on this system, we attempt to require it and if it
+# succeeds, we create the XMLParser and add it to the supported parsers. The user of the client 
+# can still switch to REXML if desired.
+begin
+	require 'xml/parser'
+	require 'rets4r/client/parser'
+	require 'rets4r/client/transaction'
+	require 'rets4r/client/data'
+	require 'rets4r/client/metadata'
+	
+	module RETS4R
+		class Client
+			module Parser
+				class XMLParser < XML::Parser
+					include Parser
+					
+					SUPPORTED_PARSERS << self
+						
+					attr_accessor :logger
+					
+					def initialize
+						@transaction = Transaction.new
+						@current	   = []
+						@text        = ''
+					end
+					
+					def parse(xml, output = false, do_retry = true)			
+						begin
+							super(xml)
+						rescue XMLParserError
+								line = self.line
+							
+								# We should get fancier here and actually check the type of error, but, err, oh well.
+								if do_retry			  		
+									# We probably received this error because somebody forgot to escape XML entities...
+									# so we attempt to escape them ourselves...													
+									do_retry = false
+									
+									begin
+										cleaned_xml = self.clean_xml(xml)
+										
+										# Because a cparser can only be used once per instantiation...
+										retry_xml = self.class.new
+										retry_xml.parse(cleaned_xml, output, do_retry)
+										
+										@transaction = retry_xml.get_transaction
+										
+									rescue
+										ex = ParserException.new($!)
+										ex.file = xml
+		
+										raise ex
+									end
+							else
+								# We should never get here! But if we do...
+								raise "You really shouldn't be seeing this error message! This means that there was an unexpected error: #{$!} (#{$!.class})"
+							end
+						end
+									
+						@transaction
+					end
+					
+					def get_transaction
+						@transaction
+					end
+					
+					private
+					
+					#### Stream Listener Events
+					def startElement(name, attrs)		
+						tag_start(name, attrs)
+					end
+					
+					def character(text)
+						@text += text
+					end
+					
+					def processText()
+						text(@text)
+						
+						@text = ''
+					end
+					
+					def endElement(name)
+						processText()
+						
+						tag_end(name)
+					end
+				end
+			end
+		end
+	end 
+rescue LoadError
+	# CParser is not available because we could not load the XMLParser library	
+end

data/lib/rets4r/client/transaction.rb

@@ -0,0 +1,34 @@
+module RETS4R
+	class Client
+		class Transaction
+			attr_accessor :reply_code, :reply_text, :response, :metadata, :header, :data, :maxrows, 
+				:count, :delimiter, :secondary_response
+			
+			def initialize
+				self.maxrows = false
+				self.header = []
+				self.data = []
+				self.delimiter = ?\t
+			end
+			
+			def success?
+				return true if self.reply_code == '0'
+				return false
+			end
+			
+			def has_data?
+				return true if self.data.length > 0
+				return false
+			end
+			
+			def maxrows?
+				return true if self.maxrows
+				return false
+			end
+			
+			def ascii_delimiter
+				self.delimiter.chr
+			end
+		end
+	end
+end