voruby 1.1.1 → 2.0.0

data/lib/voruby/misc/libxml_ext.rb

@@ -0,0 +1,121 @@
+class XML::Node
+   def replace_with(other)
+     self.next = other
+     remove!
+   end
+end
+
+module XML
+  module Object
+    # A (essentially abstract) class that can be used in the
+    # creation of domain objects backed by XML documents.
+    class Base
+      # The XML::Node used to store the state of the domain object.
+      attr_reader :node
+  
+      # Create a domain object from an XML file on disk.
+      # _filename_:: the name of the file to parse
+      #
+      #  votable = VOTable::V1_1::VOTable.from_file('myvotable.xml')
+      def self.from_file(filename)
+        self.new(XML::Document.file(filename))
+      end
+      
+      # Get the name of the element when serialized
+      # to XML that the object in question will take on.
+      # By default, the name of the class.
+      def self.element_name
+        self.to_s
+      end
+  
+      # Create a new domain object from a number of source formats.
+      # _xml_ may be one of
+      # * a string
+      # * an IO object (i.e. a File object)
+      # * a LibXML Document (i.e. XML::Document)
+      # * a LibXML Node (i.e. XML::Node)
+      # * nothing (to create a blank object)
+      # * a hash where the keys of the hash represent the method to call
+      #
+      # Assuming VOTable::V1_1::VOTable is a subclass of Base...
+      #
+      #  votable = VOTable::V1_1::VOTable.new('<VOTABLE version="1.1"/>')
+      #  votable = VOTable::V1_1::VOTable.new(File.new('myvotable.xml'))  # you could also use #from_file
+      #  votable = VOTable::V1_1::VOTable.new(XML::Document.file('myvotable.xml'))
+      #  votable = VOTable::V1_1::VOTable.new(XML::Node.new('VOTABLE'))
+      #  votable = VOTable::V1_1::VOTable.new()
+      #  votable = VOTable::V1_1::VOTable.new(:version => '1.1')
+      def initialize(xml=nil)
+        @node = case xml
+          when String
+            parser = XML::Parser.new
+            parser.string = xml
+            parser.parse.root
+          when IO
+            parser = XML::Parser.new
+            parser.io = xml
+            parser.parse.root
+          when XML::Document
+            xml.root
+          when XML::Node
+            xml
+          when NilClass
+            doc = XML::Document.new
+            doc.root = XML::Node.new(self.class.element_name)
+            doc.root
+          when Hash
+            doc = XML::Document.new
+            doc.root = XML::Node.new(self.class.element_name)
+            doc.root
+          else
+            raise "XML must be a XML::Document, XML::Node, String or IO object"
+          end
+      
+          initialize_members(xml) if xml.is_a?(Hash)
+      end
+  
+      # Serialize the domain object to XML.
+      def to_s
+        self.node.to_s
+      end
+      
+      # Equality among domain objects.
+      # Always returns false, override to get less brain-dead result.
+      def ==(obj)
+        false
+      end
+      
+      protected
+  
+      # Retrieve the domain object that corresponds to
+      # the specified class.
+      def get_element(klass)
+        subnode = self.node.find_first(self.xpath_for(klass))
+        subnode ? klass.new(subnode) : nil
+      end
+  
+      # Set the specified domain object that corresponds to
+      # the specified class.
+      def set_element(klass, e)
+        descr_node = self.node.find_first(xpath_for(klass))
+        descr_node ? descr_node.replace_with(e.node) : @node.child_add(e.node.copy(true))
+      end
+      
+      # Determine the xpath corresponding to the specified class.
+      # By default, this is just the name of the class.
+      #   obj.xpath_for(Field)  # => 'Field'
+      def xpath_for(klass)
+        klass.to_s
+      end
+      
+      private
+      
+      def initialize_members(args)
+        args.each do |name, value|
+          send("#{name}=", value)
+        end
+      end
+    end
+    
+  end
+end

data/lib/voruby/misc/rexml_ext.rb

@@ -0,0 +1,223 @@
+require 'rexml/document'
+
+module REXML
+  module Object
+    
+    class ReflectiveElementList
+      include Enumerable
+
+      attr_reader :parent, :xpath
+
+      def initialize(parent, *xpath)
+        @parent = parent
+        @xpath = xpath
+      end
+
+      def [](i)
+        path = "#{self.xpath.first}[#{i+1}]"
+        XPath.first(self.parent, path, self.xpath.last)
+      end
+
+      def []=(i, element)
+        el = self[i]
+        el ? el.replace_with(element) : self<<(element)
+      end
+
+      def <<(element)
+        path = "#{self.xpath.first}[last()]"
+        last = XPath.first(self.parent, path, self.xpath.last)
+        last ? last.next_sibling = element : self.parent << element
+      end
+
+      def last
+        path = "#{self.xpath.first}[last()]"
+        XPath.first(self.parent, path, self.xpath.last)
+      end
+
+      def first
+        path = "#{self.xpath.first}[1]"
+        XPath.first(self.parent, path, self.xpath.last)
+      end
+
+      def delete_at(i)
+        path = "#{self.xpath.first}[#{i+1}]"
+        XPath.first(self.parent, path, self.xpath.last).remove
+      end
+
+      def size
+        path = "count(#{self.xpath.first})"
+        XPath.first(self.parent, path, self.xpath.last)
+      end
+
+      def to_a
+        XPath.match(self.parent, *self.xpath)
+      end
+
+      def clear
+        self.each { |el| el.remove }
+      end
+
+      def replace(ary)
+        self.clear
+        ary.each { |el| self<<(el) }
+      end
+
+      def each
+        XPath.each(self.parent, *self.xpath) { |el| yield el }
+      end
+    end
+    
+    class ClassifiedElementList < ReflectiveElementList
+      attr_reader :klass
+      
+      def initialize(klass, parent, *xpath)
+        @klass = klass
+        super(parent, *xpath)
+      end
+      
+      def [](i)
+        self.klass.new(super(i))
+      end
+
+      def []=(i, obj)
+        el = self[i]
+        el ? el.node.replace_with(obj.node) : self<<(obj.node)
+      end
+      
+      def <<(obj)
+        super(obj.node)
+      end
+
+      def last
+        self.klass.new(super())
+      end
+
+      def first
+        self.klass.new(super())
+      end
+
+      def to_a
+        super().collect{ |el| self.klass.new(el) }
+      end
+
+      def replace(ary)
+        self.clear
+        ary.each { |obj| self<<(obj) }
+      end
+
+      def each
+        XPath.each(self.parent, *self.xpath) { |el| yield self.klass.new(el) }
+      end
+      
+      def clear
+        self.each { |el| el.node.remove }
+      end
+      
+      def ==(ary)
+        return false if self.size != ary.size
+        
+        self.each_with_index do |item, i|
+          return false if item != ary[i]
+        end
+        
+        return true
+      end
+    end
+    
+    class Base
+      attr_reader :node, :xml_element_name
+
+      def self.xsi_namespace; 'http://www.w3.org/2001/XMLSchema-instance' end
+      def self.xsd_namespace; 'http://www.w3.org/2001/XMLSchema' end
+      def self.xml_type; self.class.to_s.split('::').last end
+
+      def initialize(defn=nil)
+        @node = case defn
+          when Document      then defn.root
+          when Element       then defn
+          when Hash          then Element.new(self.xml_element_name)
+          when NilClass      then Element.new(self.xml_element_name)
+          else
+            Document.new(defn).root
+        end
+
+        initialize_members(defn) if defn.is_a?(Hash)
+      end
+
+      def xml_element_name; self.class.to_s.split('::').last end
+
+      def find_namespace_by_href(href)
+        self.node.namespaces.find{ |prefix, uri| uri == href }
+      end
+
+      def get_attribute(name, ns=nil)
+        attribute = self.node.attributes.get_attribute_ns(ns, name)
+        attribute ? attribute.value : nil
+      end
+
+      def set_attribute(name, value, ns=nil)
+        self.node.attributes[attribute_xpath_for(name, ns)] = value.to_s
+      end
+
+      def get_element(name, ns=nil)
+        XPath.first(self.node, *element_xpath_for(name, ns))
+      end
+
+      def set_element(name, value, ns)
+        el = get_element(name, ns)
+
+        # The element doesn't exist...
+        if !el
+          el = REXML::Element.new(name)
+          @node << el # so insert it
+        end
+        
+        case value
+          when String               then el.text = value.to_s
+          when REXML::Element       then value.name = name; el.replace_with(value)
+        end
+        
+        el.add_namespace(ns) if !find_namespace_by_href(ns)
+      end
+      
+      def get_elements(name, ns=nil)
+        ReflectiveElementList.new(self.node, *element_xpath_for(name, ns))
+      end
+      
+      def set_elements(name, values, ns=nil)
+        get_elements(name, ns).replace(values)
+      end
+
+      def to_s
+        formatter = Formatters::Default.new
+        xml = ''
+        formatter.write(self.node, xml)
+        xml
+      end
+
+      protected
+
+      def attribute_xpath_for(name, ns=nil)
+        if ns
+          namespace = find_namespace_by_href(ns)
+          namespace ? "#{namespace.first}:#{name}" : name
+        else
+          name
+        end
+      end
+
+      def element_xpath_for(name, ns=nil)
+        ns ? ["x:#{name}", {'x' => ns}] : [name]
+      end
+
+      private
+
+      def initialize_members(args)
+        args.each do |name, value|
+          send("#{name}=", value)
+        end
+      end
+    end
+
+  end
+end

data/lib/voruby/resolver/resolver.rb

@@ -0,0 +1,12 @@
+require 'soap/rpc/driver'
+require 'ostruct'
+
+begin
+  require 'rubygems'
+rescue LoadError; end
+require 'xml/libxml'
+
+module VORuby
+  # Name resolvers (i.e. the CDS's sesame[http://cdsweb.u-strasbg.fr/cdsws/name_resolver.gml] service)
+  module Resolver; end
+end

data/lib/voruby/resolver/sesame.rb

@@ -0,0 +1,299 @@
+require 'voruby/resolver/resolver'
+
+module VORuby
+  module Resolver
+
+    # Sesame[http://cdsweb.u-strasbg.fr/cdsws/name_resolver.gml] is the standard
+    # name resolution service of the virtual observatory.  There are a couple of
+    # ways to use it, but typically one wants the RA and Dec of the target:
+    #
+    #   ra, dec = Sesame.resolve_position('m51')  # => the primary J2000 RA and Dec of M 51 in degrees
+    #   sesame = Sesame.resolve('m51')            # => a Sesame object with in-depth information about the name resolution
+    #   puts sesame.jradeg, sesame.jdedeg
+    #
+    # It's also possible to change the location of the web service used (to a mirror, say) and to specify
+    # which resolvers sesame should aggregate over (by default Simbad is used).     
+    class Sesame
+      # The result of the name resolution as an XML::Node.
+      # Not available until after #resolve has been called.
+      attr_reader :xml
+      
+      # Whether to try to determine if the sesame service
+      # is available or not before each name resolution.
+      # The default is false.
+      attr_accessor :check_availability
+      
+      # Resolve the <tt>target</tt>.
+      # The optional <tt>against</tt> may be one of <tt>:simbad</tt>, <tt>:ned</tt>, <tt>:vizier</tt> or <tt>:all</tt>.
+      # Simbad is the most reliable, so that's the default.
+      # <tt>options</tt> is a hash with the following keys:
+      #
+      # [<tt>:end_point</tt>]     the sesame SOAP endpoint to use (default: http://cdsws.u-strasbg.fr/axis/services/Sesame)
+      # [<tt>:check_availability</tt>] whether to try to determine if the sesame service is available or not before each name resolution (default: false)
+      #
+      # Returns a Sesame object, and is exactly equivalent to:
+      #
+      #   sesame = Sesame.new
+      #   sesame.resolve
+      def self.resolve(target, against=:simbad, options={})
+        sesame = Sesame.new(options)
+        sesame.resolve(target, against)
+        
+        sesame
+      end
+      
+      # Resolve the <tt>target</tt>, but return only the primary position and no
+      # other information.  The parameters are as for #resolve with the addition
+      # of <tt>as</tt> which may be <tt>:degrees</tt> (default) or <tt>:sexigesimal</tt>.
+      # In the former case, an array of floats (ra, dec) is returned while in the latter
+      # an array of strings.
+      #
+      #   Sesame.resolve_position('m51')                # => [202.4682083, 47.1946667]
+      #   Sesame.resolve_position('m51', :sexigesimal)  # => ['13:29:52.36', '+47:11:40.8']
+      def self.resolve_position(target, against=:simbad, as=:degrees, options={})
+        self.resolve(target, against, options).position(as)
+      end
+      
+      # Create a new sesame name resolver.
+      # <tt>options</tt> is a hash with the following keys:
+      #
+      # [<tt>:end_point</tt>]     the sesame SOAP endpoint to use (default: http://cdsws.u-strasbg.fr/axis/services/Sesame)
+      # [<tt>:check_availability</tt>] whether to try to determine if the sesame service is available or not before each name resolution (default: false)
+      #
+      #   sesame = Sesame.new(
+      #     :end_point => 'http://vizier.nao.ac.jp:8080/axis/services/Sesame' # maybe we're in Japan...
+      #     :check_availability => true # and we want to always check the availability of the service
+      #   )
+      def initialize(options={})        
+        self.end_point = options[:end_point] || 'http://cdsws.u-strasbg.fr/axis/services/Sesame'
+        self.check_availability = options[:check_availability] || false
+      end
+      
+      # The "end-point" or location of the name resolver's webservice.
+      def end_point
+        @end_point
+      end
+      
+      # Set the end-point or location of the name resolver's webservice.
+      #   sesame.end_point = 'http://vizier.nao.ac.jp:8080/axis/services/Sesame'
+      def end_point=(epoint)
+        @end_point = epoint
+        
+        # We don't use the WSDL for this because ruby doesn't deal well with method overloading.
+        @resolver = SOAP::RPC::Driver.new(@end_point)
+        @resolver.add_rpc_method('sesame', 'name', 'resultType', 'all', 'service')
+        @resolver.add_rpc_method('getAvailability')
+      end
+    
+      # Retrieve whatever information we can about the position of the specified <tt>target</tt>.
+      # The optional <tt>against</tt> may be one of <tt>:simbad</tt>, <tt>:ned</tt>, <tt>:vizier</tt> or <tt>:all</tt>.
+      # Simbad is the most reliable, so that's the default.
+      #
+      #   sesame.resolve('m51', :all)  # use all the resources at sesame's disposal
+      #
+      # This method may throw an exception if:
+      #
+      # * #end_point doesn't exist
+      # * you have set #check_availabilty to true and the resolver has indicated it is not available
+      def resolve(target, against=:simbad)
+        raise "Sesame at #{self.end_point} is not currently available" if self.check_availability and !self.available?
+        
+        parser = XML::Parser.new
+        parser.string = 
+          @resolver.sesame(target.to_s, 'x', true, service_designation(against))
+        @xml = parser.parse.root
+      end
+      
+      # The target you requested name resolution on.
+      def target
+        self.xml.find_first('target').content
+      end
+      
+      # Any information that sesame sent back with your results.
+      def infos
+        self.xml.find('INFO').collect{ |i| i.content }
+      end
+      
+      # Any errors reported by sesame sent back with your results.
+      def errors
+        self.xml.find('ERROR').collect{ |e| e.content }
+      end
+      
+      # Sesame actually aggregates results from a number of sources.
+      # Returns an array of ResolvedInfo objects, one for each resource
+      # polled (i.e. some combination of Simbad, VizieR and Ned).
+      def resolvers
+        self.xml.find('Resolver').collect{ |r| ResolvedInfo.new(r) }
+      end
+      
+      # A shortcut for ResolvedInfo#position.
+      # Assumes the first resolver is the one you're most
+      # interested in.
+      def position(as=:degrees)
+        self.resolvers.first.position(as)
+      end
+      
+      # Checks to see whether sesame is available.
+      # At this point it's assumed the service is present at
+      # the location specified by #end_point.  This just checks
+      # to see whether sesame reports itself as available or not.
+      def available?
+        # We don't use an XML parser here because (as of 2007-01-04)
+        # the validTo tag isn't closed properly, rendering the XML
+        # malformed.
+        result = @resolver.getAvailability
+        result.match(/<available>\s*(.*)\s*<\/available>/)[1] == 'true'
+      end
+    
+      private
+    
+      def service_designation(svc)
+        {
+          :simbad => 'S',
+          :ned => 'N',
+          :vizier => 'V',
+          :all => 'A'
+        }[svc] || svc
+      end
+      
+      # A simple object that represents a name resolution attempt.
+      class ResolvedInfo
+        attr_reader :xml
+        
+        # Create a ResolvedInfo object from an appropriate
+        # XML::Node (one that represents a <Resolver> XML element).
+        def initialize(xml)
+          @xml = xml
+        end
+        
+        # The name of the resolver (i.e. Simbad).
+        def name
+          self.xml['name']
+        end
+        
+        def code
+          self.xml['code']
+        end
+        
+        # Any info accompanying the name resolution.
+        # Returns an array of strings.
+        def infos
+          self.xml.find('INFO').collect{ |i| i.content }
+        end
+        
+        # Any errors accompanying the name resolution.
+        # Returns an array of string.
+        def errors
+          self.xml.find('ERROR').collect{ |e| e.content }
+        end
+        
+        # The classification of the object (i.e. Seyfert_2 or QSO).
+        def otype
+          self.xml.find_first('otype').content if self.xml.find_first('otype')
+        end
+        
+        # The J2000 coordinates of the object in sexigesimal format (i.e. '13:29:52.36 +47:11:40.8')
+        def jpos
+          self.xml.find_first('jpos').content if self.xml.find_first('jpos')
+        end
+        
+        # The J2000 right ascension of the object in decimal degrees.
+        def jradeg
+          self.xml.find_first('jradeg').content.to_f if self.xml.find_first('jradeg')
+        end
+        
+        # The J2000 declination of the object in decimal degrees.
+        def jdedeg
+          self.xml.find_first('jdedeg').content.to_f if self.xml.find_first('jdedeg')
+        end
+        
+        # A bibcode that corresponds to the publication in which the position
+        # of the object was determined.
+        def ref_pos
+          self.xml.find_first('refPos').content if self.xml.find_first('refPos')
+        end
+        
+        # The error of the right ascension in milliarcseconds.
+        def err_ra_mas
+          self.xml.find_first('errRAmas').content.to_f if self.xml.find_first('errRAmas')
+        end
+        
+        # The error of the declination in milliarcseconds.
+        def err_de_mas
+          self.xml.find_first('errDEmas').content.to_f if self.xml.find_first('errDEmas')
+        end
+        
+        # The redshift of the object.
+        def z
+          self.xml.find_first('z').content.to_f if self.xml.find_first('z')
+        end
+        
+        # The error in the redshift of the object.
+        def errz
+          self.xml.find_first('errz').content.to_i if self.xml.find_first('errz')
+        end
+        
+        # A bibcode that corresponds to the publication in which the redshift
+        # of the object was determined.
+        def refz
+          self.xml.find_first('refz').content if self.xml.find_first('refz')
+        end
+        
+        # The velocity of the object in km/s.
+        def vel
+          self.xml.find_first('Vel').content.to_f if self.xml.find_first('Vel')
+        end
+        
+        # The error in the velocity of the object in km/s.
+        def err_vel
+          self.xml.find_first('errVel').content.to_if if self.xml.find_first('errVel')
+        end
+        
+        # A bibcode that corresponds to the publication in which the velocity
+        # of the object was determined.
+        def ref_vel
+          self.xml.find_first('refVel').content if self.xml.find_first('refVel')
+        end
+        
+        # The morphological type of the object (i.e. Sc).
+        def mtype
+          self.xml.find_first('MType').content if self.xml.find_first('MType')
+        end
+        
+        # The spectral type of the object (i.e. A10)
+        def sptype
+          self.xml.find_first('spType').content if self.xml.find_first('spType')
+        end
+        
+        # The canonical name of the object.
+        def oname
+          self.xml.find_first('oname').content if self.xml.find_first('oname')
+        end
+        
+        # The number of references to this object.
+        def nrefs
+          self.xml.find_first('nrefs').content.to_i if self.xml.find_first('nrefs')
+        end
+        
+        # A list of aliases for the object.
+        # Returns a list of strings.
+        def aliases
+          self.xml.find('alias').collect{ |a| a.content }
+        end
+        
+        # The J2000 position of the object in degrees or sexigesimal format.
+        #   info.position(:degrees)     # => [202.4682083, 47.1946667]
+        #   info.position(:sexigesimal) # => ['13:29:52.36', '+47:11:40.8']
+        def position(as=:degrees)
+          case as
+          when :sexigesimal        then (self.jpos || '').split(/\s+/)
+          else
+            [self.jradeg, self.jdedeg]
+          end
+        end
+      end
+      
+    end
+      
+  end
+end