intermine 0.98.03 → 0.98.04

data/lib/intermine/query.rb

@@ -357,7 +357,12 @@ module InterMine::PathQuery
         end
 
         # Get your own result reader for handling the results at a low level.
+        # If no columns have been selected for output before requesting results, 
+        # all attribute columns will be selected.
         def results_reader(start=0, size=nil)
+            if @views.empty?
+                select("*")
+            end
             return Results::ResultsReader.new(@url, self, start, size)
         end
 

data/lib/intermine/results.rb

@@ -3,10 +3,52 @@ require "json"
 require 'stringio'
 require 'net/http'
 
+# == Code for handling results
+#
+# The classes in this module are used to process
+# the results of queries. They include mechanisms 
+# for reading from the connection in a record 
+# orientated format, and for interpreting the values 
+# received.
+#
 module InterMine::Results
 
+    # == Synopsis
+    #
+    #   query.each_row do |row|
+    #     puts row[0], row[1], row[2]
+    #     puts row["symbol"], row["proteins.name"]
+    #   end
+    #
+    # == Description
+    #
+    # A dual-faced object, these representations of rows 
+    # of results are intended to provide a single object that 
+    # allows Array-like and Hash-like access to an individual
+    # row of data. The primary means of access for this is
+    # the use of item access with ResultsRow#[], which accepts
+    # Array like index arguments, as well as Hash like key arguments.
+    #
+    # As well as value retrieval via indices and keys, iteration is also supported
+    # with ResultsRow#each and the aliases each_pair and each_value. If
+    # one parameter is requested the iteration will be by value, if 
+    # two are requested it will be by pair. 
+    #
+    # There is no attempt to fully emulate the complete Hash and Array 
+    # interfaces - that would make little sense as it does not make any 
+    # sense to insert values into a row, or to re-sort it in place. If you 
+    # want to do such things, call ResultsRow#to_a or ResultsRow#to_h to
+    # get real Hash or Array values you are free to manipulate.
+    #
+    #:include:contact_header.rdoc
+    #
     class ResultsRow
 
+        # Construct a new result row. 
+        #
+        # You will not need to do this - ResultsRow objects are created for
+        # you when the results are parsed.
+        #
         def initialize(results, columns)
             @results = results.is_a?(Array) ? results : JSON.parse(results)
             unless @results.is_a?(Array)
@@ -19,27 +61,104 @@ module InterMine::Results
             @columns = columns
         end
 
-        def [](key)
-            if key.is_a?(Integer)
-                idx = key
-            else
-                idx = index_for(key)
+        # == Retrieve values from the row
+        #
+        #   row[0]              # first element
+        #   row[-1]             # last element
+        #   row[2, 3]           # Slice of three cells, starting at cell no. 3 (index 2)
+        #   row[1..3]           # Slice of three cells, starting at cell no. 2 (index 1)
+        #   row["length"]       # Get a cell's value by column name
+        #   row["Gene.length"]  # Use of the root class is optional
+        #   row[:length]        # For bare attributes, a symbol may be used.
+        #
+        # This method emulated both the array and hash style of access, based
+        # on argument type. Passing in integer indexes or ranges retrieves
+        # values in a manner that treats the row as a list of values. Passing in 
+        # string or symbols retrieves values in a manner that treates the 
+        # row as a Hash. It is possible to access the values in the row by using 
+        # either the short or long forms of the column name.
+        #
+        # Unlike the corresponding method in either Hash or Array, this method
+        # throws errors when trying to access single elements (not when requesting
+        # array slices) and the result cannot be found.
+        #
+        def [](arg, length=nil)
+            unless length.nil?
+                raise ArgumentError, "when providing a length, the first argument must be an Integer" unless arg.is_a? Integer
+                return @results[arg, length].map {|x| x["value"]}
             end
-            if idx.nil?
-                raise IndexError, "Bad key: #{key}"
+
+            case arg
+            when Range
+                return @results[arg].map {|x| x["value"]}
+            when Integer
+                idx = arg
+            else
+                idx = index_for(arg)
             end
-            begin
-                result = @results[idx]["value"]
-            rescue NoMethodError
-                raise IndexError, "Bad key: #{key}"
+
+            raise ArgumentError, "Bad argument: #{arg}" if idx.nil?
+
+            cell = @results[idx]
+
+            raise IndexError, "Argument out of range" if cell.nil?
+
+            return cell["value"]
+        end
+
+        # Returns the first value in this row
+        def first
+            return @results[0]["value"]
+        end
+
+        # Returns the last value in this row
+        def last
+            return @results.last["value"]
+        end
+
+        # Iterate over the values in this row in the
+        # order specified by the query's view.
+        # 
+        #   row.each do |value|
+        #     puts value
+        #   end
+        #
+        #   row.each do |column, value|
+        #     puts "#{column} is #{value}"
+        #   end
+        #
+        # If one parameter is specified, then the iteration 
+        # simply includes values, if more than one is specified,
+        # then it will be by column/value pairs.
+        #
+        def each(&block) 
+            if block
+                if block.arity == 1
+                    @results.each {|x| block.call(x["value"])}
+                else block.arity == 2
+                    (0 ... @results.size).to_a.each {|i| block.call(@columns[i], @results[i]["value"])}
+                end
             end
-            return result
+            return self
         end
 
+        alias each_value each
+        alias each_pair each
+
+        # Return the number of cells in this row.
+        def size
+            return @results.size
+        end
+
+        alias length size
+
+        # Return an Array version of the row.
         def to_a
             return @results.map {|x| x["value"]}
         end
 
+        # Return a Hash version of the row. All keys in this
+        # hash will be full length column headers.
         def to_h
             hash = {}
             @results.each_index do |x|
@@ -49,6 +168,7 @@ module InterMine::Results
             return hash
         end
 
+        # Return a readable representation of the information in this row
         def to_s 
             bufs = []
             @results.each_index do |idx|
@@ -61,12 +181,16 @@ module InterMine::Results
             return @columns.first.rootClass.name + ": " + bufs.join(",\t")
         end
 
-        def to_csv
-            return @results.map {|x| x["value"].to_s}.join("\t")
+        # Return the information in this row as a line suitable for prining in a 
+        # CSV or TSV file. The optional separator argument will be used to delimit
+        # columns
+        def to_csv(sep="\t")
+            return @results.map {|x| x["value"].inspect}.join(sep)
         end
 
         private
 
+        # Return the index for a string or symbol key.
         def index_for(key)
             if @indexes.nil?
                 @indexes = {}
@@ -81,13 +205,30 @@ module InterMine::Results
                     end
                 end
             end
-            return @indexes[key]
+            return @indexes[key.to_s]
         end
     end
 
 
+    # The class responsible for retrieving results and processing them
+    #
+    #   query.each_row do |row|
+    #     puts row[2..3]
+    #   end
+    #
+    # Queries delegate their handling of results to these objects, which
+    # are responsible for creating the ResultsRow objects or model objects 
+    # that the results represent.
+    #
+    #:include:contact_header.rdoc
+    #
     class ResultsReader
 
+        # Construct a new ResultsReader.
+        #
+        # You will not need to do this yourself. It is handled by 
+        # queries themselves.
+        #
         def initialize(uri, query, start, size)
             @uri = URI(uri)
             @query = query
@@ -95,12 +236,7 @@ module InterMine::Results
             @size = size
         end
 
-        def params(format)
-            p = @query.params.merge("start" => @start, "format" => format)
-            p["size"] = @size unless @size.nil?
-            return p
-        end
-
+        # Run a request to get the size of the result set.
         def get_size
             query = params("jsoncount")
             res = Net::HTTP.post_form(@uri, query)
@@ -113,31 +249,10 @@ module InterMine::Results
             end
         end
 
-        def each_line(data)
-            req = Net::HTTP::Post.new(@uri.path)
-            req.set_form_data(data)
-            Net::HTTP.new(@uri.host, @uri.port).start {|http|
-                http.request(req) {|resp|
-                    holdover = ""
-                    resp.read_body {|chunk|
-                        sock = StringIO.new(holdover + chunk)
-                        sock.each_line {|line|
-                            if sock.eof?
-                                holdover = line
-                            else
-                                yield line
-                            end
-                        }
-                        sock.close
-                    }
-                    yield holdover
-                }
-            }
-        end
-
+        # Iterate over the result set one ResultsRow at a time
         def each_row
             container = ''
-            self.each_line(params("jsonrows")) do |line|
+            each_line(params("jsonrows")) do |line|
                 if line.start_with?("[")
                     begin
                         row = ResultsRow.new(line.chomp("," + $/), @query.views)
@@ -152,10 +267,25 @@ module InterMine::Results
             check_result_set(container)
         end
 
+        # Iterate over the resultset, one object at a time, where the
+        # object is the instantiation of the type of object specified as the 
+        # query's root type. The actual type returned depends on the query
+        # itself, and any subclass information returned by the webservice.
+        #
+        #   query = service.query("Gene").select("*")
+        #   query.each_result do |gene|
+        #     puts gene.symbol, gene.length
+        #   end
+        #
+        #   query = service.query("Organism").select("*")
+        #   query.each_result do |organism|
+        #     puts organism.shortName, organism.taxonId
+        #   end
+        #
         def each_result
             model = @query.model
             container = ''
-            self.each_line(params("jsonobjects")) do |line|            
+            each_line(params("jsonobjects")) do |line|            
                 line.chomp!("," + $/)
                 if line.start_with?("{") and line.end_with?("}")
                     begin
@@ -176,6 +306,41 @@ module InterMine::Results
 
         private
 
+        # Retrieve the results from the webservice, one line at a time. 
+        # This method has responsibility for ensuring that the lines are 
+        # complete, and not split over two or more chunks.
+        def each_line(data)
+            req = Net::HTTP::Post.new(@uri.path)
+            req.set_form_data(data)
+            Net::HTTP.new(@uri.host, @uri.port).start {|http|
+                http.request(req) {|resp|
+                    holdover = ""
+                    resp.read_body {|chunk|
+                        sock = StringIO.new(holdover + chunk)
+                        sock.each_line {|line|
+                            if sock.eof?
+                                holdover = line
+                            else
+                                yield line
+                            end
+                        }
+                        sock.close
+                    }
+                    yield holdover
+                }
+            }
+        end
+
+
+        # Get the parameters for this request, given the specified format.
+        def params(format)
+            p = @query.params.merge("start" => @start, "format" => format)
+            p["size"] = @size unless @size.nil?
+            return p
+        end
+
+        # Check that the request was successful according the metadata
+        # passed with the result.
         def check_result_set(container)
             begin
                 result_set = JSON.parse(container)
@@ -189,6 +354,7 @@ module InterMine::Results
         end
     end
 
+    # Errors if there are problems retrieving results from the webservice.
     class ServiceError < RuntimeError
     end
 

data/lib/intermine/service.rb

@@ -84,6 +84,9 @@ module InterMine
     # is fully introspectible and queriable. This allows for sophisticated meta-programming
     # and dynamic query generation. 
     #
+    #
+    #:include:contact_header.rdoc
+    #
     class Service
 
         extend Forwardable

data/lib/intermine/version.rb

@@ -1,3 +1,3 @@
 module Intermine
-  VERSION = "0.98.03"
+  VERSION = "0.98.04"
 end

data/test/data/resultrow.json

@@ -1 +1,5 @@
-[{"id":320000014,"value":"DepartmentA1","class":"Department","url":"/report.do?id=320000014"},{"id":320000015,"value":"EmployeeA1","class":"Manager","url":"/report.do?id=320000015"}]
+[
+    {"id":320000014,"value":"DepartmentA1","class":"Department","url":"/report.do?id=320000014"},
+    {"id":320000015,"value":"EmployeeA1","class":"Manager","url":"/report.do?id=320000015"},
+    {"id":320000015,"value":33,"class":"Manager","url":"/report.do?id=320000015"}
+]

data/test/test_result_row.rb

@@ -14,8 +14,8 @@ class TestResults < Test::Unit::TestCase
             File.dirname(__FILE__) + "/data/resultrow.json", "r")
         @data = file.read
         @json = JSON.parse(@data)
-        @view = ["Company.departments.name","Company.departments.manager.name"]
-        @bad_view = ["Company.departments.name","Company.departments.manager.name", "Comany.name"]
+        @view = ["Company.departments.name","Company.departments.manager.name", "Company.departments.manager.age"]
+        @bad_view = ["Company.departments.name","Company.departments.manager.name"]
     end
 
     def test_initialize
@@ -54,7 +54,11 @@ class TestResults < Test::Unit::TestCase
         assert_equal(rr[0], "DepartmentA1")
         assert_equal(rr[1], "EmployeeA1")
 
-        rr = ResultsRow.new(@json, @view)
+        assert_equal(rr[1..2], ["EmployeeA1", 33])
+        assert_equal(rr[0, 2], ["DepartmentA1", "EmployeeA1"])
+
+        assert_equal(rr.first, "DepartmentA1")
+        assert_equal(rr.last, 33)
 
         assert_raise IndexError do
             rr[3]
@@ -62,6 +66,25 @@ class TestResults < Test::Unit::TestCase
 
     end
 
+    def test_each
+
+        rr = ResultsRow.new(@data, @view)
+        expected =  %w{DepartmentA1 EmployeeA1} << 33
+
+        c = 0
+        rr.each do |val|
+            assert_equal(expected[c], val)
+            c += 1
+        end
+
+        c = 0
+        rr.each do |key, val|
+            assert_equal(@view[c], key)
+            assert_equal(expected[c], val)
+            c += 1
+        end
+    end
+
     def test_hash_access
 
         rr = ResultsRow.new(@data, @view)
@@ -76,7 +99,7 @@ class TestResults < Test::Unit::TestCase
 
         rr = ResultsRow.new(@json, @view)
 
-        assert_raise IndexError do
+        assert_raise ArgumentError do
             rr["foo"]
         end
 
@@ -84,7 +107,7 @@ class TestResults < Test::Unit::TestCase
 
     def test_to_a
 
-        expected =  %w{DepartmentA1 EmployeeA1}
+        expected =  %w{DepartmentA1 EmployeeA1} << 33
 
         rr = ResultsRow.new(@data, @view)
 
@@ -101,7 +124,8 @@ class TestResults < Test::Unit::TestCase
 
         expected = {
             "Company.departments.name" => "DepartmentA1",
-            "Company.departments.manager.name" => "EmployeeA1"
+            "Company.departments.manager.name" => "EmployeeA1",
+            "Company.departments.manager.age" => 33
         }
         assert_equal(expected, rr.to_h)
 

data/test/unit_tests.rb

@@ -4,3 +4,4 @@ require 'test/unit'
 require 'test_model'
 require 'test_query'
 require 'test_sugar'
+require 'test_result_row'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: intermine
 version: !ruby/object:Gem::Version 
-  hash: 401
+  hash: 415
   prerelease: false
   segments: 
   - 0
   - 98
-  - 3
-  version: 0.98.03
+  - 4
+  version: 0.98.04
 platform: ruby
 authors: 
 - Alex Kalderimis
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-01 00:00:00 +01:00
+date: 2011-08-02 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency