lib/biomart/dataset.rb in biomart-0.2.1 vs lib/biomart/dataset.rb in biomart-0.2.2

@@ -35,53 +35,64 @@
       @exportables  = {}
     end
     
     # Returns a hash (keyed by the biomart 'internal_name' for the filter) 
     # of all of the Biomart::Filter objects belonging to this dataset.
+    # 
+    # @return [Hash] A hash of Biomart::Filter objects keyed by 'internal_name'
     def filters
       if @filters.empty?
         fetch_configuration()
       end
       return @filters
     end
     
     # Returns an array of the filter names (biomart 'internal_name') 
     # for this dataset.
+    # 
+    # @return [Array] An array of filters (their 'internal_name's)
     def list_filters
       if @filters.empty?
         fetch_configuration()
       end
       return @filters.keys
     end
     
     # Returns a hash (keyed by the biomart 'internal_name' for the attribute) 
     # of all of the Biomart::Attribute objects belonging to this dataset.
+    # 
+    # @return [Hash] A hash of Biomart::Attribute objects keyed by 'internal_name'
     def attributes
       if @attributes.empty?
         fetch_configuration()
       end
       return @attributes
     end
     
     # Returns an array of the attribute names (biomart 'internal_name') 
     # for this dataset.
+    # 
+    # @return [Array] An array of attributes (their 'internal_name's)
     def list_attributes
       if @attributes.empty?
         fetch_configuration()
       end
       return @attributes.keys
     end
     
     # Function to perform a Biomart count.  Returns an integer value for 
     # the result of the count query.
-    #
-    # optional arguments:
     # 
+    # arguments:
+    # 
     #   {
-    #     :timeout => integer,     # set a timeout length for the request (secs)
-    #     :filters => {}           # hash of key-value pairs (filter => search term)
+    #     :timeout => integer,     # set a timeout length for the request (secs) - optional
+    #     :filters => {}           # hash of key-value pairs (filter => search term) - optional
     #   }
+    # 
+    # @param [Hash] args The arguments hash
+    # @raise Biomart::ArgumentError Raised when un-supported arguments are passed
     def count( args={} )
       if args[:federate]
         raise Biomart::ArgumentError, "You cannot federate a count query."
       end
       
@@ -134,10 +145,14 @@
     #     :data    => []    # array of arrays containing search results
     #   }
     #
     # But with the :process_results option will return an array of hashes, 
     # where each hash represents a row of results (keyed by the attribute name).
+    # 
+    # @param [Hash] args The arguments hash
+    # @return [Hash/Array] Will return a hash by default (of unprocessed data), or will return an array of hashes
+    # @raise Biomart::ArgumentError Raised if incorrect arguments are passed
     def search( args={} )
       if args[:required_attributes] and !args[:required_attributes].is_a?(Array)
         raise Biomart::ArgumentError, "The :required_attributes option must be passed as an array."
       end
       
@@ -152,11 +167,14 @@
       result = filter_data_rows( args, result ) if args[:required_attributes]
       result = conv_results_to_a_of_h( result ) if args[:process_results]
       return result
     end
     
-    # Utility function to build the Biomart query XML
+    # Utility function to build the Biomart query XML - used by #count and #search.
+    #
+    # @see #count
+    # @see #search
     def generate_xml( args={} )
       biomart_xml = ""
       xml = Builder::XmlMarkup.new( :target => biomart_xml, :indent => 2 )
       
       xml.instruct!
@@ -182,11 +200,12 @@
       
       return biomart_xml
     end
     
     # Simple heartbeat function to test that a Biomart server is online.
-    # Returns true/false.
+    #
+    # @return [Boolean] true/false
     def alive?
       server = Biomart::Server.new( @url )
       return server.alive?
     end
     
@@ -196,20 +215,20 @@
       # xml for a dataset
       def fetch_configuration
         url = @url + "?type=configuration&dataset=#{@name}"
         document = REXML::Document.new( request( :url => url ) )
 
-        # Top-Level filters...
-        REXML::XPath.each( document, '//FilterDescription' ) do |f|
-          unless f.attributes["displayType"].eql? "container"
-            @filters[ f.attributes["internalName"] ] = Filter.new( f.attributes )
-          end
-        end
-        
-        # Filters nested inside containers...
-        REXML::XPath.each( document, '//FilterDescription/Option' ) do |f|
-          if f.attributes["displayType"] != nil
-            @filters[ f.attributes["internalName"] ] = Filter.new( f.attributes )
+        # Filters...
+        ['//FilterDescription','//FilterDescription/Option'].each do |filter_xpath|
+          REXML::XPath.each( document, filter_xpath ) do |f|
+            if f.attributes["displayType"] != nil
+              next if f.attributes["displayType"] == "container"
+              @filters[ f.attributes["internalName"] ] = Filter.new( f.attributes )
+            else f.attributes["pointerFilter"] != nil
+              pointer_filter = Filter.new( f.attributes )
+              @filters[ pointer_filter.name ]           = pointer_filter
+              @filters[ pointer_filter.pointer_filter ] = pointer_filter
+            end
           end
         end
         
         # Attributes are much simpler...
         REXML::XPath.each( document, '//AttributeDescription' ) do |a|
\ No newline at end of file