intermine 0.98.01

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in intermine.gemspec
+gemspec

data/LICENCE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.rdoc

@@ -0,0 +1,79 @@
+= Webservice Client Library for InterMine Data-Warehouses
+
+This library provides an interface to the InterMine webservices
+API. It makes construction and execution of queries more 
+straightforward, safe and convenient, and allows for results
+to be used directly in Ruby code. As well as traditional row based
+access, the library provides an object-orientated record result
+format (similar to ActiveRecords), and allows for fast, memory 
+efficient iteration of result sets.
+
+== Example
+
+Get all protein domains associated with a set of genes and print their names:
+
+    require "intermine/service"
+
+    Service.new("www.flymine.org/query").
+        new_query("Pathway")
+        select(:name).
+        where("genes.symbol" => ["zen", "hox", "h", "bib"]).
+        each_row { |row| puts row[:name]}
+
+== Who is this for?
+
+InterMine data warehouses are typically constructed to hold
+Biological data, and as this library facilitates programmatic
+access to these data, this install is primarily aimed at 
+bioinformaticians. In particular, users of the following services
+may find it especially useful:
+ * FlyMine (http://www.flymine.org/query)
+ * YeastMine (http://yeastmine.yeastgenome.org/yeastmine)
+ * RatMine (http://ratmine.mcw.edu/ratmine)
+ * modMine (http://intermine.modencode.org/release-23)
+ * metabolicMine (http://www.metabolicmine.org/beta)
+
+== How to use this library:
+
+We have tried to construct an interface to this library that
+does not require you to learn an entirely new set of concepts. 
+As such, as well as the underlying methods that are common
+to all libraries, there is an additional set of aliases and sugar
+methods that emulate the DSL style of SQL:
+
+=== SQL style
+
+  service = Service.new("www.flymine.org/query")
+  service.model.
+     table("Gene").
+     select("*", "pathways.*").
+     where(:symbol => "zen").
+     order_by(:symbol).
+     outerjoin(:pathways).
+     each_row do |r|
+       puts r
+     end
+
+=== Common InterMine interface
+
+  service = Service.new("www.flymine.org/query")
+  query = service.new_query("Gene")
+  query.add_views("*", "pathways.*")
+  query.add_constraint("symbol", "=", "zen")
+  query.add_sort_order(:symbol)
+  query.add_join(:pathways)
+  query.each_row do |r|
+    puts r
+  end
+
+For more details, see the accompanying documentation and the unit tests
+for interface examples. Further documentation is available at www.intermine.org.
+
+== Support
+
+Support is available on our development mailing list: dev@intermine.org
+
+== License
+
+This code is Open Source under the LGPL. Source code for all InterMine code
+can be checked out from svn://subversion.flymine.org/flymine

data/Rakefile

@@ -0,0 +1,67 @@
+require 'rubygems'
+require 'rubygems/specification' unless defined?(Gem::Specification)
+require 'rake/testtask'
+require 'rake/gempackagetask'
+
+gem 'rdoc', '=2.1.0'
+require 'rdoc/rdoc'
+require 'rake/rdoctask'
+
+gem 'darkfish-rdoc'
+require 'darkfish-rdoc'
+
+def gemspec
+    @gemspec ||= begin
+        Gem::Specification.load(File.expand_path('intermine.gemspec'))
+    end
+end
+
+task :default => :test
+
+desc 'Start a console session'
+task :console do
+    system 'irb -I lib -r intermine/service'
+end
+
+desc 'Displays the current version'
+task :version do 
+    puts "Current version: #{gemspec.version}"
+end
+
+desc 'Installs the gem locally'
+task :install => :package do
+    sh "gem install pkg/#{gemspec.name}-#{gemspec.version}"
+end
+
+desc 'Release the gem'
+task :release => :package do
+      sh "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+Rake::GemPackageTask.new(gemspec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
+
+end
+
+Rake::TestTask.new do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/unit_tests.rb']
+    t.verbose = true
+end
+
+Rake::TestTask.new(:live_tests) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/live_test.rb']
+    t.verbose = true
+end
+
+Rake::RDocTask.new do |t|
+    t.title = 'InterMine Webservice Client Documentation'
+    t.rdoc_files.include 'README.rdoc'
+    t.rdoc_files.include 'lib/**/*rb'
+    t.main = 'README.rdoc'
+    t.options += ['-SHN', '-f', 'darkfish']
+end
+
+

data/lib/intermine/lists.rb

@@ -0,0 +1,716 @@
+require 'rubygems'
+require 'net/http'
+require 'uri'
+require "stringio"
+require "cgi"
+require 'json'
+require "intermine/service"
+
+include InterMine
+
+# == List Management Tools
+#
+# Classes that deal with the creation and management
+# of a user's saved lists in an individual webservice.
+#
+module InterMine::Lists
+
+    #
+    # == Synopsis
+    #
+    #  list = service.create_list(%{h eve H bib zen}, "Gene")
+    #  list.name = "My new list of genes" # Updates name on server
+    #  puts list.size                     # 5
+    #  list.each do |gene|                # Inspect the contents
+    #    puts gene.name
+    #  end
+    #
+    #  list << "Hox"                      # Append an element
+    #  puts list.size
+    #
+    # == Description 
+    #
+    # A representation of a saved list in the account of an
+    # individual user of an InterMine service. Lists represent
+    # homogenous collections of objects, which are themselves
+    # linked to records in the data-warehouse. A list behaves
+    # much as a normal Array would: it has a size, and can be 
+    # processed with each and map, and allows for positional
+    # access with list[idx]. In addition, as this list is 
+    # backed by its representation in the webapp, it has a name, 
+    # and description, as well as a type. Any changes to the list,
+    # either in its contents or by renaming, are reflected in the 
+    # stored object.
+    #
+    #:include:contact_header.rdoc
+    #
+    class List
+
+        # The name of the list. This can be changed at any time.
+        attr_reader :name
+
+        # The title of the list. This is fixed.
+        attr_reader :title
+        
+        # An informative description.
+        attr_reader :description
+        
+        # The kind of object this list holds
+        attr_reader :type
+        
+        # The number of elements in the list
+        attr_reader :size
+        
+        # The date that this list was originally created
+        attr_reader :dateCreated
+        
+        # The categories associated with this list
+        attr_reader :tags
+        
+        # Any ids used to construct this list that did not match any objects in the database
+        attr_reader :unmatched_identifiers
+
+        # Construct a new list with details from the webservice.
+        #
+        # This method is called internally. You will not need to construct
+        # new list objects directly.
+        #
+        # Arguments:
+        # [+details+] The information about this list received from the webservice.
+        # [+manager+] The object responsible for keeping track of all the known lists
+        #
+        #   list = List.new({"name" => "Foo"}, manager)
+        #
+        def initialize(details, manager=nil)
+            @manager = manager
+            details.each {|k,v| instance_variable_set('@' + k, v)}
+            @unmatched_identifiers = []
+            @tags ||= []
+        end
+
+        # True if the list has no elements.
+        def empty?
+            @size == 0
+        end
+
+        # True if the list can be changed by the current user.
+        #
+        #  if list.is_authorized?
+        #    list.remove("h")
+        #  end
+        #
+        def is_authorized?
+            return @authorized.nil? ? true : @authorized
+        end
+
+        # Returns the first element in the list. The order elements
+        # are returned in depends on the fields that its class has.
+        # It is not related to the order of the identifiers given at creation.
+        #
+        #   puts list.first.symbol
+        #
+        def first
+            if @size > 0
+                return self[0]
+            else
+                return nil
+            end
+        end
+
+        # Retrieve an element at a given position. Negative indices 
+        # count from the end of the list. 
+        #
+        #   puts list[2].length
+        #   puts list[-1].length
+        #
+        def [](index)
+            if index < 0
+                index = @size + index
+            end
+            unless index < @size && index >= 0
+                return nil
+            end
+            return query.first(index)
+        end
+
+        # Retrieve the object at the given index, or raise an IndexError, unless
+        # a default is supplied, in which case that is returned instead.
+        #
+        #   gene = list.fetch(6)  # Blows up if the list has only 6 elements or less
+        #
+        def fetch(index, default=nil)
+            if index < 0
+                index = @size + index
+            end
+            unless index < @size && index >= 0
+                if default
+                    return default
+                else
+                    raise IndexError, "#{index} is not a suitable index for this list"
+                end
+            end
+            return query.first(index)
+        end
+
+        # Apply the given block to each element in the list. Return the list.
+        #  
+        #   list.each do |gene|
+        #     puts gene.symbol
+        #   end
+        #  
+        def each
+            query.each_result {|r| yield r}
+            return self
+        end
+
+        # Return a list composed of the results of the elements of 
+        # this list process by the given block
+        #
+        #   symbols = list.map {|gene| gene.symbol}
+        #
+        def map 
+            ret = []
+            query.each_result {|r|
+                ret.push(yield r)
+            }
+            return ret
+        end
+
+        # Used to create a new list from the contents of this one. This can be used
+        # to define a sub-list
+        #
+        #   sub_list = service.create_list(list.list_query.where(:length => {"<" => 500}))
+        #
+        def list_query
+            return @manager.service.query(@type).select(@type + '.id').where(@type => self)
+        end
+
+        # A PathQuery::Query with all attributes selected for output, and restricted
+        # to the content of this list. This object is used to fetch elements for other 
+        # methods. This can be used for composing further filters on a list, or for
+        # adding other attributes for output.
+        #
+        #   list.query.select("pathways.*").each_result do |gene|
+        #     puts "#{gene.symbol}: #{gene.pathways.map {|p| p.identifier}.inspect}"
+        #   end
+        #
+        def query
+            return @manager.service.query(@type).where(@type => self)
+        end
+
+        # Returns a simple, readable representation of the list
+        #
+        #   puts list
+        #   => "My new list: 5 genes"
+        #
+        def to_s
+            return "#{@name}: #{@size} #{@type}s"
+        end
+
+        # Returns a detailed representation of the list, useful for debugging.
+        def inspect
+            return "<#{self.class.name} @name=#{@name.inspect} @size=#{@size} @type=#{@type.inspect} @description=#{@description.inspect} @title=#{@title.inspect} @dateCreated=#{@dateCreated.inspect} @authorized=#{@authorized.inspect} @tags=#{@tags.inspect}>"
+        end
+
+        # Update the name of the list, making sure that the name is also 
+        # changed in the respective service.
+        #
+        #   list.name = "My new list"
+        #
+        # If a list is created without a name, it will be considered as a "temporary"
+        # list until it is given one. All temporary lists are deleted from the webapp 
+        # when the program exits.
+        #
+        def name=(new_name)
+            return if (@name == new_name)
+            uri = URI.parse(@manager.service.root + Service::LIST_RENAME_PATH)
+            params = @manager.service.params.merge("oldname" => @name, "newname" => new_name)
+            res = Net::HTTP.post_form(uri, params)
+            @manager.process_list_creation_response(res)
+            @name = new_name
+        end
+
+        # Delete this list from the webservice. After this method is called this object
+        # should not be used again, and any attempt to do so will cause errors.
+        def delete
+            @manager.delete_lists(self)
+            @size = 0
+            @name = nil
+        end
+
+        # Add other items to this list. The other items can be identifiers in the same
+        # form as were used to create this list orginally (strings, or arrays or files).
+        # Or other lists or queries can be used to add items to the list. Any combination of these
+        # elements is possible.
+        #
+        #   list.add("Roughened", other_list, a_query)
+        #
+        def add(*others)
+            unionables, ids = classify_others(others)
+            unless unionables.empty?
+                if unionables.size == 1
+                    append_list(unionables.first)
+                else
+                    append_lists(unionables)
+                end
+            end
+            unless ids.empty?
+                ids.each {|x| append_ids(x)}
+            end
+            return self
+        end
+
+        # Add the other item to the list, exactly as in List#add
+        def <<(other)
+            return add(other)
+        end
+
+        # Remove items as specified by the arguments from this list. As in 
+        # List#add these others can be identifiers specified by strings or arrays
+        # or files, or other lists or queries. 
+        #
+        #  list.remove("eve", sub_list)
+        #
+        # If the items were not in the list in the first place, no error will be raised, 
+        # and the size of this list will simply not change.
+        #
+        def remove(*others)
+            unionables, ids = classify_others(others)
+            unless ids.empty?
+                unionables += ids.map {|x| @manager.create_list(x, @type)}
+            end
+            unless unionables.empty?
+                myname = @name
+                new_list = @manager.subtract([self], unionables, @tags, nil, @description)
+                self.delete
+                @size = new_list.size
+                @name = new_list.name
+                @description = new_list.description
+                @dateCreated = new_list.dateCreated
+                @tags = new_list.tags
+                self.name = myname
+            end
+            return self
+        end
+
+        private
+
+        # Used to interpret arguments to add and remove
+        def classify_others(others)
+            unionables = []
+            ids = []
+            others.each do |o|
+                case o
+                when List
+                    unionables << o
+                when o.respond_to?(:list_upload_uri)
+                    unionables << o
+                else 
+                    ids << o
+                end
+            end
+            return [unionables, ids]
+        end
+
+        # Used to handle the responses returned by queries used to update the list 
+        # by add and remove
+        def handle_response(res)
+            new_list = @manager.process_list_creation_response(res)
+            @unmatched_identifiers += new_list.unmatched_identifiers
+            @size = new_list.size
+        end
+
+        # Add a List to this List
+        def append_list(list)
+            q = (list.is_a?(List)) ? list.list_query : list
+            params = q.params.merge(@manager.service.params).merge("listName" => @name)
+            uri = URI.parse(q.list_append_uri)
+            res = Net::HTTP.post_form(uri, params)
+            handle_response(res)
+        end
+
+        # Add a collection of lists and queries to this List
+        def append_lists(lists)
+            addendum = @manager.union_of(lists)
+            append_list(addendum)
+        end
+
+        # Add items defined by ids to this list
+        def append_ids(ids)
+            uri = URI.parse(@manager.service.root + Service::LIST_APPEND_PATH)
+            params = {"name" => @name}
+            if ids.is_a?(File)
+                f = ids
+            elsif ids.is_a?(Array)
+                f = StringIO.new(ids.map {|x| '"' + x.gsub(/"/, '\"') + '"'}.join(" "))
+            elsif File.readable?(ids.to_s)
+                f = File.open(ids, "r")
+            else
+                f = StringIO.new(ids.to_s)
+            end
+            req = Net::HTTP::Post.new(uri.path + "?" + @manager.params_to_query_string(params))
+            req.body_stream = f
+            req.content_type = "text/plain"
+            req.content_length = f.size
+
+            res = Net::HTTP.start(uri.host, uri.port) do |http|
+                http.request(req)
+            end
+            handle_response(res)
+            f.close
+        end
+
+    end
+
+    # == Synopsis 
+    #
+    # An internal class for managing lists throughout the lifetime of a program. 
+    # The main Service object delegates list functionality to this class.
+    # 
+    #   # Creation
+    #   list = service.create_list("path/to/some/file.txt", "Gene", "my-favourite-genes")
+    #   # Retrieval
+    #   other_list = service.list("my-previously-saved-list")
+    #   # Combination
+    #   intersection = service.intersection_of([list, other_list])
+    #   # Deletion
+    #   service.delete_lists(list, other_list)
+    #
+    # == Description 
+    #
+    # This class contains logic for reading and updating the lists available 
+    # to a given user at a webservice. This class in particular is responsible for 
+    # parsing list responses, and performing the operations that combine lists into 
+    # new result sets (intersection, union, symmetric difference, subtraction).
+    #
+    #:include:contact_header.rdoc
+    #
+    class ListManager
+
+        # The name given by default to all lists you do not explicitly name
+        #
+        #  l = service.create_list("genes.txt", "Gene")
+        #  puts l.name
+        #  => "my_list_1"
+        #
+        DEFAULT_LIST_NAME = "my_list"
+
+        # The description given by default to all new lists for which you 
+        # do not provide a description explicitly. The purpose of this
+        # is to help you identify automatically created lists in you profile.
+        DEFAULT_DESCRIPTION = "Created with InterMine Ruby Webservice Client"
+
+        # The service this manager belongs to
+        attr_reader :service
+        
+        # The temporary lists created in this session. These will be deleted 
+        # at program exit.
+        attr_reader :temporary_lists
+
+        # Construct a new ListManager. 
+        #
+        # You will never need to call this constructor yourself.
+        #
+        def initialize(service)
+            @service = service
+            @lists = {}
+            @temporary_lists = []
+            do_at_exit(self)
+        end
+
+
+        # Get the lists currently available in the webservice. 
+        def lists
+            refresh_lists
+            return @lists.values
+        end
+
+        # Get the names of the lists currently available in the webservice
+        def list_names
+            refresh_lists
+            return @lists.keys.sort
+        end
+
+        # Get a list by name. Returns nil if the list does not exist.
+        def list(name)
+            refresh_lists
+            return @lists[name]
+        end
+
+        # Gets all lists with the given tags. If more than one tag is supplied, 
+        # then a list must have all given tags to be returned.
+        #
+        #   tagged = service.get_lists_with_tags("tagA", "tagB")
+        #
+        def get_lists_with_tags(*tags)
+            return lists.select do |l|
+                union = l.tags | tags
+                union.size == l.tags.size
+            end
+        end
+
+        # Update the stored record of lists. This method is 
+        # called before all list retrieval methods.
+        def refresh_lists
+            lists = JSON.parse(@service.get_list_data)
+            @lists = {}
+            lists["lists"].each {|hash| 
+                l = List.new(hash, self)
+                @lists[l.name] = l
+            }
+        end
+        
+        # === Create a new List with the given content.
+        #
+        # Creates a new List and stores it on the appropriate 
+        # webservice:
+        #
+        # Arguments:
+        # [+content+] Can be a string with delimited identifiers, an Array of 
+        #             identifiers, a File object containing identifiers, or 
+        #             a name of an unopened readable file containing identifiers.
+        #             It can also be another List (in which case the list is cloned)
+        #             or a query that describes a result set.
+        # [+type+]    Required when identifiers are being given (but not when the 
+        #             content is a PathQuery::Query or a List. This should be the kind
+        #             of object to look for (such as "Gene").
+        # [+tags+]    An Array of tags to apply to the new list. If a list is supplied as
+        #             the content, these tags will be added to the existing tags.
+        # [+name+]    The name of the new list. One will be generated if none is provided.
+        #             Lists created with generated names are considered temporary and will
+        #             be deleted upon program exit.
+        # [+description+] An informative description of the list
+        #
+        #   # With Array of Ids
+        #   list = service.create_list(%{eve bib zen}) 
+        #
+        #   # From a file
+        #   list = service.create_list("path/to/some/file.txt", "Gene", [], "my-stored-genes")
+        #
+        #   # With a query
+        #   list = service.create_list(service.query("Gene").select(:id).where(:length => {"<" => 500}))
+        #
+        #
+        def create_list(content, type=nil, tags=[], name=nil, description=nil)
+            name ||= get_unused_list_name
+            description ||= DEFAULT_DESCRIPTION
+
+            if content.is_a?(List) 
+                tags += content.tags
+                response = create_list_from_query(content.list_query, tags, name, description)
+            elsif content.respond_to?(:list_upload_uri)
+                response = create_list_from_query(content, tags, name, description)
+            else 
+                response = create_list_from_ids(content, type, tags, name, description)
+            end
+
+            return process_list_creation_response(response)
+        end
+
+        # Deletes the given lists from the webservice. The lists can be supplied
+        # as List objects, or as their names as Strings.
+        #
+        # Raises errors if problems occur with the deletion of these lists, including 
+        # if the lists do not exist.
+        #
+        def delete_lists(*lists)
+            lists.map {|x| x.is_a?(List) ? x.name : x.to_s}.uniq.each do |name|
+                uri = URI.parse(@service.root + Service::LISTS_PATH)
+                params = {"name" => name}
+                req = Net::HTTP::Delete.new(uri.path + "?" + params_to_query_string(params))
+                res = Net::HTTP.start(uri.host, uri.port) do |http|
+                    http.request(req)
+                end
+                check_response_for_error(res)
+            end
+            refresh_lists
+        end
+
+        # Create a new list in the webservice from the symmetric difference of two 
+        # or more lists, and return a List object that represents it.
+        #
+        # See ListManager#create_list for an explanation of tags, name and description
+        def symmetric_difference_of(lists=[], tags=[], name=nil, description=nil)
+            do_commutative_list_operation(Service::LIST_DIFFERENCE_PATH, "Symmetric difference", lists, tags, name, description)
+        end
+
+        # Create a new list in the webservice from the union of two
+        # or more lists, and return a List object that represents it.
+        #
+        # See ListManager#create_list for an explanation of tags, name and description
+        def union_of(lists=[], tags=[], name=nil, description=nil)
+            do_commutative_list_operation(Service::LIST_UNION_PATH, "Union", lists, tags, name, description)
+        end
+
+        # Create a new list in the webservice from the intersection of two
+        # or more lists, and return a List object that represents it.
+        #
+        # See ListManager#create_list for an explanation of tags, name and description
+        def intersection_of(lists=[], tags=[], name=nil, description=nil)
+            do_commutative_list_operation(Service::LIST_INTERSECTION_PATH, "Intersection", lists, tags, name, description)
+        end
+
+        # Create a new list in the webservice by subtracting all the elements in the 
+        # 'delenda' lists from all the elements in the 'reference' lists,
+        # and return a List object that represents it.
+        #
+        # See ListManager#create_list for an explanation of tags, name and description
+        def subtract(references=[], delenda=[], tags=[], name=nil, description=nil)
+            ref_names = make_list_names(references)
+            del_names = make_list_names(delenda)
+            name ||= get_unused_list_name
+            description ||= "Subtraction of #{del_names[0 .. -2].join(", ")} and #{del_names.last} from #{ref_names[0 .. -2].join(", ")} and #{ref_names.last}"
+            uri = URI.parse(@service.root + Service::LIST_SUBTRACTION_PATH)
+            params = @service.params.merge("name" => name, "description" => description, "references" => ref_names.join(';'),
+                                           "subtract" => del_names.join(';'), "tags" => tags.join(';'))
+            res = Net::HTTP.post_form(uri, params)
+            return process_list_creation_response(res)
+        end
+
+        # Common code to all list requests for interpreting the response 
+        # from the webservice. 
+        def process_list_creation_response(response)
+            check_response_for_error(response)
+            new_list = JSON.parse(response.body)
+            new_name = new_list["listName"]
+            failed_matches = new_list["unmatchedIdentifiers"] || []
+            refresh_lists
+            ret = list(new_name)
+            ret.unmatched_identifiers.replace(failed_matches)
+            return ret
+        end
+
+        # only handles single value keys!
+        def params_to_query_string(p)
+            return @service.params.merge(p).map { |k,v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&')
+        end
+
+        private 
+
+        # Clean up after itself by deleting 
+        # any temporary lists left lying about
+        def do_at_exit(this)
+            at_exit do 
+                unless this.temporary_lists.empty?
+                    this.lists.each do |x|
+                        begin
+                            x.delete if this.temporary_lists.include?(x.name)
+                        rescue
+                            # Ignore errors here.
+                        end
+                    end
+                end
+            end
+        end
+
+        # Transform a collection of objects containing Lists, Queries and Strings
+        # into a collection of Strings with list names.
+        #
+        # Raises errors if an object cannot be resolved to an accessible
+        # list.
+        def make_list_names(objs)
+            current_names = list_names
+            return objs.map do |x|
+                case x
+                when List
+                    x.name
+                when x.respond_to?(:list_upload_uri)
+                    create_list(x).name
+                when current_names.include?(x.to_s)
+                    x.to_s
+                else
+                    raise ArgumentError, "#{x} is not a list you can access"
+                end
+            end
+        end
+
+        # Common code behind the operation of union, intersection and symmetric difference operations.
+        def do_commutative_list_operation(path, operation, lists, tags=[], name=nil, description=nil)
+            list_names = make_list_names(lists)
+            name ||= get_unused_list_name
+            description ||= "#{operation} of #{list_names[0 .. -2].join(", ")} and #{list_names.last}"
+
+            uri = URI.parse(@service.root + path)
+            params = @service.params.merge(
+                "name" => name, "lists" => list_names.join(";"), 
+                "description" => description, "tags" => tags.join(';')
+            )
+            res = Net::HTTP::post_form(uri, params)
+            return process_list_creation_response(res)
+        end
+
+        # Error checking routine.
+        def check_response_for_error(response)
+            case response
+            when Net::HTTPSuccess
+                # Ok
+            else
+                begin
+                    container = JSON.parse(response.body)
+                    raise ServiceError, container["error"]
+                rescue
+                    response.error!
+                end
+            end
+        end
+
+        # Routine for creating a list from a PathQuery::Query
+        def create_list_from_query(query, tags=[], name=nil, description=nil)
+            uri = query.list_upload_uri
+            list_params = {
+                "listName" => name,
+                "description" => description,
+                "tags" => tags.join(";")
+            }
+            service_params = @service.params
+            params = query.params.merge(list_params).merge(service_params)
+            return Net::HTTP.post_form(URI.parse(uri), params)
+        end
+
+        # Routine for creating a List in a webservice from a list of Ids.
+        def create_list_from_ids(ids, type, tags=[], name=nil, description=nil)
+            if @service.model.get_cd(type).nil?
+                raise ArgumentError, "Invalid type (#{type.inspect})"
+            end
+            uri = URI.parse(@service.root + Service::LISTS_PATH)
+            list_params = {
+                "name" => name,
+                "description" => description,
+                "tags" => tags.join(";"),
+                "type" => type
+            }
+            if ids.is_a?(File)
+                f = ids
+            elsif ids.is_a?(Array)
+                f = StringIO.new(ids.map {|x| '"' + x.gsub(/"/, '\"') + '"'}.join(" "))
+            elsif File.readable?(ids.to_s)
+                f = File.open(ids, "r")
+            else
+                f = StringIO.new(ids.to_s)
+            end
+            req = Net::HTTP::Post.new(uri.path + "?" + params_to_query_string(list_params))
+            req.body_stream = f
+            req.content_type = "text/plain"
+            req.content_length = f.size
+
+            res = Net::HTTP.start(uri.host, uri.port) do |http|
+                http.request(req)
+            end
+            f.close
+            return res
+        end
+
+        # Helper to get an unused default name
+        def get_unused_list_name(no=1)
+            name = DEFAULT_LIST_NAME + "_" + no.to_s
+            names = list_names
+            while names.include?(name)
+                no += 1
+                name = DEFAULT_LIST_NAME + "_" + no.to_s
+            end
+            @temporary_lists.push(name)
+            return name
+        end
+
+    end
+end