rtm 0.2.0 → 0.2.1

data/lib/rtm/sugar/association/hash_access.rb

@@ -1,7 +1,7 @@
 # Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar
+module RTM::Sugar
   module Association
     # This module implements methods for Hash-like access in Associations.
     module HashAccess
@@ -10,7 +10,7 @@ module Sugar
       #
       # If type is given, returns the Roles of this Association
       # whose Role type match type.
-      # Type may be a Topic or Topic-Reference.
+      # Type may be a topic reference.
       #
       # The result may be empty.
       #
@@ -32,7 +32,7 @@ module Sugar
       
       # Creates a new Role in this Association where type specifies the
       # Role type and player the associated Role player.
-      # Type and player may each be a Topic, String-Reference or Locator.
+      # Type and player may each be a topic reference.
       # 
       # :call-seq:
       #   [type]= player

data/lib/rtm/sugar/occurrence/dynamic_value.rb

@@ -1,34 +1,43 @@
 # Copyright: Copyright 2010 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar::Occurrence
+module RTM::Sugar::Occurrence
   module DynamicValue
-    # Returns the value of this occurrence cast as appropriate Ruby type.
+
+    # Given the occurrence's datatype this method returns the value of this
+    # occurrence cast as appropriate Ruby type.
+    #
+    # :call-seq:
+    #   dynamic_value -> Object
+    #
     def dynamic_value
-      case self.datatype.to_external_form # first_oc.datatype is actually of type Locator
-        when RTM::PSI[:Decimal]
-          self.value.to_f
-        when RTM::PSI[:Double]
-          self.value.to_f
-        when RTM::PSI[:Int]
-          self.value.to_i
-        when RTM::PSI[:Integer]
-          self.value.to_i
-        when RTM::PSI[:Float]
-          self.value.to_f
-        when RTM::PSI[:Long]
-          self.value.to_i
-        # Date, ... missing
-        else
-          self.value
-      end
-    end
-    
-    class NoDatatypeHandlerAvailableException < Exception
-      def initialize(value)
-        super "Cannot map #{value} to an occurrence value+datatype. Maybe you need to add a handler for your Ruby object type."
+      value = self.value # a String
+      case self.datatype.reference
+      when RTM::PSI[:IRI]
+        return topic_map.create_locator(value)
+      when RTM::PSI[:Decimal]
+        return value.to_f
+      when RTM::PSI[:Double]
+        return value.to_f
+      when RTM::PSI[:Int]
+        return value.to_i
+      when RTM::PSI[:Integer]
+        return value.to_i
+      when RTM::PSI[:Float]
+        return value.to_f
+      when RTM::PSI[:Long]
+        return value.to_i
+      when RTM::PSI[:Date]
+        return Date.parse(value)
+      when RTM::PSI[:DateTime]
+        return DateTime.parse(value)
+      when RTM::PSI[:Time]
+        return Time.parse(value)
+      else
+        return value
       end
     end
+
   end
 end
 
@@ -37,39 +46,13 @@ class Float
     s = self.to_s
     
     case s
-      when "Infinity"
-        "INF"
-      when "-Infinity"
-        "-INF"
-      else
-        s
+    when "Infinity"
+      "INF"
+    when "-Infinity"
+      "-INF"
+    else
+      s
     end
   end
 end
 
-module Sugar::Topic::Characteristics
-  #
-  # Weird. create_occurrence has an options hash, and we don't have one. We should unify the syntax. What is the right thing to do?
-  #
-  def dynamic_create_occurrence(type,value,datatype,scope = nil)
-    if !datatype # well, let's choose one
-      case value
-        when Integer
-          datatype = RTM::PSI[:Integer]
-          use_value = value.to_s
-        when Float
-          datatype = RTM::PSI[:Double]
-          use_value = value.to_xsd_double
-        when String
-          datatype = RTM::PSI[:String]
-          use_value = value
-        else
-          raise Sugar::Occurrence::DynamicValue::NoDatatypeHandlerAvailableException.new(value)
-      end
-    else
-      use_value = value
-    end
-    
-    create_occurrence(type,use_value,:datatype => datatype, :scope => scope)
-  end
-end

data/lib/rtm/sugar/occurrence/external.rb

@@ -0,0 +1,53 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar::Occurrence
+  module External
+    
+    # Creates an association out of this occurrence which represents the
+    # occurrence information in relation to the parent topic.
+    # 
+    # The association is of type "http://psi.topicmapslab.de/subject-representation".
+    # It includes two roles. The parent topic plays the role of type
+    # "http://psi.topicmapslab.de/represented-subject". The topic with the
+    # subject locator created from the occurrence value plays the role
+    # of a type the same as the occurrence type.
+    #
+    # The subject locator will be resolved using the get-method of RTM::TopicMap,
+    # that means if the occurrence value is stored as String and is not a valid uri
+    # the base_iri of the topic map is used to create one.
+    #
+    # The occurrence datatype may be xsd:anyURI as well as xsd:String.
+    # The occurrence value must be a valid URL.
+    #
+    # Example: Creates an association out of the occurrence with value
+    # "http://www.leipzig.de" and type "webpage" of the topic Leipzig:
+    # * association type: subject_representation
+    # * role 1: Leipzig plays the role "represented_subject"
+    # * role 2: topic with subject locator "http://www.leipzig.de" plays the role "webpage"
+    #
+    # :call-seq:
+    #   externalize -> Association
+    #
+    def externalize
+      topic_map.create_association(RTM::PSI[:subject_representation], RTM::PSI[:represented_subject] => parent, self.type => "=#{self.value}")
+    end
+
+    # Executes externalize and removes this occurrence from the topic map afterwards
+    #
+    # :call-seq:
+    #   externalize!
+    #
+    def externalize!(*args)
+      association = externalize(*args)
+      remove
+      return association
+    end
+
+    # Returns true, if the datatype of this occurrence equals xsd:anyURI.
+    def external?
+      return self.datatype.reference == RTM::PSI[:IRI] ? true : false
+    end
+
+  end
+end

data/lib/rtm/sugar/reifiable/reifier.rb

@@ -0,0 +1,21 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar::Reifiable
+  module CreateReifier
+
+    # Returns the reifier (a topic) of this Reifiable.
+    # If there is no current reifier, then a reifier will be generated.
+    # This reifier did not exist in the topic map before.
+    #
+    # :call-seq:
+    #   reifier! -> Topic
+    #
+    def reifier!
+      self.reifier ||= self.topic_map.create_topic
+    end
+    alias :create_reifier :reifier!
+    
+  end
+end
+ 

data/lib/rtm/sugar/role/counterparts.rb

@@ -1,14 +1,16 @@
 # Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar::Role
+module RTM::Sugar::Role
 	module Counterparts
     
-    # Returns all Roles from the parent Association of this Role,
+    # Returns all roles from the parent association of this role,
     # except itself.
     #
-    # A filter-hash may be used to filter for the type of the other Roles
-    # (:otype). The identfier may be a Topic or Topic-Reference.
+    # A filter-hash may be used to filter for the type of the other roles
+    # (:otype) or the player of the other roles (:oplayer).
+    #
+    #  The identfiers may be topic references.
     #
     # :call-seq:
     #   counterparts -> Array of Roles
@@ -16,7 +18,11 @@ module Sugar::Role
     #
     def counterparts(filter={})
       _roles = parent.roles.reject{|r| r.id==self.id}
-      return filter[:otype] ? _roles.select{|r| r.type == topic_map.get(filter[:otype]) } : _roles
+      otype = filter[:otype]
+      _roles = _roles.select{|r| r.type == topic_map.get(otype)} if otype && otype != :any
+      oplayer = filter[:oplayer]
+      _roles = _roles.select{|r| r.player == topic_map.get(oplayer)} if oplayer && oplayer != :any
+      return _roles
     end
 
     # Returns the other role, if the parent association is binary.
@@ -35,7 +41,7 @@ module Sugar::Role
     # except the player of itself.
     #
     # A filter-hash may be used to filter for the type of the other Roles
-    # (:otype). The identifier may be a Topic or Topic-Reference.
+    # (:otype). The identifier may be a topic reference.
     #
     # :call-seq:
     #   counterplayers -> Array of Topics

data/lib/rtm/sugar/topic/best_name.rb

@@ -0,0 +1,74 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar::Topic::BestName
+
+  # Tries to find the best matching name for a given topic.
+  #
+  def best_name (theme = nil)
+    all_names = self.names
+
+    # return last part of identifier if no name exist
+    return find_user_friendly_identifier(self) if all_names.empty
+
+    # collect name with default name type
+    default_names = []
+    all_names.each do |name|
+      type_of_name = name.getType
+
+      next if type_of_name.nil?
+      type_identifiers = type_of_name.subject_identifiers.to_a
+
+      type_identifiers.each do |i|
+        if i.toExternalForm == RTM::PSI[:name_type] then
+          default_names << name
+          break
+        end
+      end
+    end
+
+    default_names = all_names if default_names.empty?
+    default_names = default_names.select { |name| not name.scope.to_a.index(theme).nil? } if not theme.nil?
+    default_names = all_names if default_names.empty?
+
+    # get default name with the minimum number of scopes
+    min_scoped_name = default_names.sort_by{|n| n.value}.min {|n1,n2| n1.getScope.size <=> n2.getScope.size}
+    min_scoped_name.value
+  end
+
+  private
+  def find_user_friendly_identifier(topic)
+    return psi_prefix topic.
+      subject_identifiers.
+      sort_by{|sid| sid.value.length}.
+      first.
+      value unless topic.subject_identifiers.empty?
+
+    return topic.
+      topic_references.
+      map{|sid| sid.gsub /^[\^=]/, ''}.
+      sort_by{|sid| sid.length }.
+      first
+
+    # fallback
+    return create_shortest_topic_identifier topic
+  end
+
+  def create_shortest_topic_identifier(topic)
+    base_iri = topic.topic_map.base_locator
+
+    topic.getItemIdentifiers.each do |item_identifier|
+      iid_iri = item_identifier.value
+      iid_iri.scan(/(file:)?\/*#{base_iri}#(.*)/) { |pair| return "^#{pair[1]}" }
+    end
+
+    CGI::escape(topic.topic_references.sort_by { |reference| reference.length }.first.to_s)
+
+    # throw('Unable to create simplified identifier from topic.', topic)
+  end
+
+  # HACK
+  def psi_prefix(name)
+    name.gsub /^http\:\/\/psi\.topicmaps\.org\/iso13250\/model\//, 'tmdm:'
+  end
+end

data/lib/rtm/sugar/topic/characteristics.rb

@@ -1,9 +1,9 @@
 # Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar::Topic::Characteristics
+module RTM::Sugar::Topic::Characteristics
   
-  # Returns all Occurrences of this Topic whose Datatype is not IRI
+  # Returns all Occurrences of this Topic whose datatype is not IRI
   #
   # :call-seq:
   #   internal_occurrences -> Set of Occurrences
@@ -12,7 +12,7 @@ module Sugar::Topic::Characteristics
     occurrences.select{|x| x.getDatatype.toExternalForm != RTM::PSI[:IRI]}
   end
   
-  # Returns all Occurrences of this Topic whose Datatype is IRI
+  # Returns all Occurrences of this Topic whose datatype is IRI
   #
   # :call-seq:
   #   external_occurrences -> Set of Occurrences
@@ -21,15 +21,15 @@ module Sugar::Topic::Characteristics
     occurrences.select{|y| y.getDatatype.toExternalForm == RTM::PSI[:IRI]}
   end
   
-  # Returns the Names of this Topic which may be filtered for their type,
+  # Returns the names of this topic which may be filtered for their type,
   # value and/or scope.
   #
-  # If scope is set to :ucs, Names which exist in the unconstrained scope
+  # If scope is set to :ucs, names which exist in the unconstrained scope
   # are selected. If scope is set to :any (default), scope does not constrain
-  # the Names-Array. Else, only the Names which exist in the given scope
-  # are selected.
+  # the names-Array. Else, only the names which whose scope contains one of the
+  # given themes are returned.
   #
-  # Returns an empty Array if no Names match or if the Name type
+  # Returns an empty Array if no names match or if the name type
   # or scope does not exist.
   #
   # :call-seq:
@@ -57,8 +57,8 @@ module Sugar::Topic::Characteristics
   #
   # If scope is set to :ucs, Occurrences which exist in the unconstrained scope
   # are selected. If scope is set to :any (default), scope does not constrain
-  # the Occurrence-Array. Else, only the Occurrences which exist in the given scope
-  # are selected.
+  # the Occurrence-Array. Else, only the occurrences which whose scope contains
+  # one of the given themes are returned.
   #
   # Returns an empty Array if no Occurrences match or if the Occurrence type or
   # scope does not exist.

data/lib/rtm/sugar/topic/counterparts.rb

@@ -1,138 +1,150 @@
 # Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar
-  module Topic
-    module Counterparts
+module RTM::Sugar::Topic
+  module Counterparts
 
-      # Returns all Roles belonging to Associations in which this Topic
-      # is a player and for which this Topic is not the player.
-      #
-      # A filter-hash may be used to filter for the the type
-      # of the Role this Topic playes
-      # (:rtype), for the Association type (:atype) and/or
-      # for the type of the returned Roles (:otype). The
-      # identifier may be a Topic, String-Reference or Locator.
-      #
-      # The result may be empty.
-      #
-      # :call-seq:
-      #   counterparts                         -> Array of Roles
-      #   counterparts({:rtype => identifier}) -> Array of Roles
-      #   counterparts({:atype => identifier}) -> Array of Roles
-      #   counterparts({:otype => identifier}) -> Array of Roles
-      #   counterparts({:rtype => identifier, :atype => identifier}) -> Array of Roles
-      #   counterparts({:rtype => identifier, :atype => identifier, :otype => identifier}) -> Array of Roles
-      #
-      def counterparts(filter={})
-        roles.select{|r| filter[:rtype] ? r.type == self.topic_map.get(filter[:rtype]) : true}.
-            select{|r| filter[:atype] ? r.parent.type == self.topic_map.get(filter[:atype]) : true}.
-              inject([]){|all,r| all+=r.counterparts(filter)}
-      end
+    # Returns all Roles belonging to Associations in which this Topic
+    # is a player and for which this Topic is not the player.
+    #
+    # A filter-hash may be used to filter for the the type
+    # of the Role this Topic playes
+    # (:rtype), for the Association type (:atype) and/or
+    # for the type of the returned Roles (:otype). The
+    # identifier may be a topic reference.
+    #
+    # The result may be empty.
+    #
+    # :call-seq:
+    #   counterparts                         -> Array of Roles
+    #   counterparts({:rtype => identifier}) -> Array of Roles
+    #   counterparts({:atype => identifier}) -> Array of Roles
+    #   counterparts({:otype => identifier}) -> Array of Roles
+    #   counterparts({:rtype => identifier, :atype => identifier}) -> Array of Roles
+    #   counterparts({:rtype => identifier, :atype => identifier, :otype => identifier}) -> Array of Roles
+    #
+    def counterparts(filter={})
+      roles.select{|r| filter[:rtype] ? r.type == self.topic_map.get(filter[:rtype]) : true}.
+        select{|r| filter[:atype] ? r.parent.type == self.topic_map.get(filter[:atype]) : true}.
+        inject([]){|all,r| all+=r.counterparts(filter)}
+    end
 
-      # Returns all Topics that are players of Roles belonging to Associations
-      # in which this Topic is another player. The resulting Array does
-      # not contain duplicates.
-      #
-      # A filter-hash may be used to filter for the the type
-      # of the Role this Topic playes
-      # (:rtype), for the Association type (:atype) and/or
-      # for the type of the Roles the returned Topics play (:otype). The
-      # identifier may be a Topic, String-Reference or Locator.
-      #
-      # The result may be empty.
-      #
-      # :call-seq:
-      #   counterplayers                        -> Array of Topics
-      #   counterplayers(:rtype => identifier) -> Array of Topics
-      #   counterplayers(:atype => identifier) -> Array of Topics
-      #   counterplayers(:otype => identifier) -> Array of Topics
-      #   counterplayers(:rtype => identifier1, :atype => identifier2) -> Array of Topics
-      #   counterplayers(:rtype => identifier1, :atype => identifier2, :otype => identifier3) -> Array of Topics
-      #
-      def counterplayers(filter={})
-        return counterparts(filter).map{|r| r.player}.uniq
+    # Returns all Topics that are players of Roles belonging to Associations
+    # in which this Topic is another player. The resulting Array does
+    # not contain duplicates.
+    #
+    # A filter-hash may be used to filter for the the type
+    # of the Role this Topic playes
+    # (:rtype), for the Association type (:atype) and/or
+    # for the type of the Roles the returned Topics play (:otype). The
+    # identifier may be a topic reference.
+    #
+    # The result may be empty.
+    #
+    # :call-seq:
+    #   counterplayers                        -> Array of Topics
+    #   counterplayers(:rtype => identifier) -> Array of Topics
+    #   counterplayers(:atype => identifier) -> Array of Topics
+    #   counterplayers(:otype => identifier) -> Array of Topics
+    #   counterplayers(:rtype => identifier1, :atype => identifier2) -> Array of Topics
+    #   counterplayers(:rtype => identifier1, :atype => identifier2, :otype => identifier3) -> Array of Topics
+    #
+    def counterplayers(filter={})
+      topic_map.cached self, :counterplayers, filter do
+        counterparts(filter).map{|r| r.player}.uniq
       end
+    end
       
-      # Returns all players (Topics) which share a counterplayer with this Topic (player),
-      # If type is given, it may constrain the type of the Role this Topic should play
-      # (and therefore the type of the Roles the peers play)
-      # or the type of the Association this Topic plays a Role in
-      # (and therefore the type of the Associations the peers play an Role in).
-      #
-      # Type may be a Topic or Topic-Reference.
-      #
-      # The result may be empty.
-      # 
-      # :call-seq:
-      #   peers -> Array of Topics
-      #   peers(type) -> Array of Topics
-      #
-      def peers(type=:any)
-        _peers = []
-        if type == :any
-          self.roles.each do |r|
-            _peers = _peers + r.peers(:arity => :loose, :atype => :loose, :otype => :loose, :rtype => :loose)
-          end
-        else
-          type = topic_map.get(type)
-          if type
-            if self.roles.map{|r| r.type}.include?(type) #-> rtype
-              self.roles(type).each do |r|
-                _peers = _peers + r.peers(:arity => :loose, :atype => :loose, :otype => :loose, :rtype => :strict)
-              end 
-            elsif self.roles.map{|r| r.parent.type}.include?(type) #->atype
-              self.roles.select{|r| r.parent.type == type}.each do |r|
-                _peers = _peers + r.peers(:arity => :loose, :atype => :strict, :otype => :loose, :rtype => :strict)
-              end
-            elsif self.roles.map{|r| r.counterparts}.flatten.map{|r| r.type}.include?(type) #-> otype
-              # nothing can happen so far
-            else
-              return []
+    # Returns all players (Topics) which share a counterplayer with this Topic (player),
+    # If type is given, it may constrain the type of the Role this Topic should play
+    # (and therefore the type of the Roles the peers play)
+    # or the type of the Association this Topic plays a Role in
+    # (and therefore the type of the Associations the peers play an Role in).
+    #
+    # Type may be a topic reference.
+    #
+    # The result may be empty.
+    #
+    # :call-seq:
+    #   peers -> Array of Topics
+    #   peers(type) -> Array of Topics
+    #
+    def peers(type=:any)
+      _peers = []
+      if type == :any
+        self.roles.each do |r|
+          _peers = _peers + r.peers(:arity => :loose, :atype => :loose, :otype => :loose, :rtype => :loose)
+        end
+      else
+        type = topic_map.get(type)
+        if type
+          if self.roles.map{|r| r.type}.include?(type) #-> rtype
+            self.roles(type).each do |r|
+              _peers = _peers + r.peers(:arity => :loose, :atype => :loose, :otype => :loose, :rtype => :strict)
             end
+          elsif self.roles.map{|r| r.parent.type}.include?(type) #->atype
+            self.roles.select{|r| r.parent.type == type}.each do |r|
+              _peers = _peers + r.peers(:arity => :loose, :atype => :strict, :otype => :loose, :rtype => :strict)
+            end
+          elsif self.roles.map{|r| r.counterparts}.flatten.map{|r| r.type}.include?(type) #-> otype
+            # nothing can happen so far
           else
             return []
           end
+        else
+          return []
         end
-        return _peers.map{|r| r.player}
       end
+      return _peers.map{|r| r.player}
+    end
       
-      # Returns all Associations in which this Topic
-      # is a player.
-      #
-      # A filter-hash may be used to filter
-      # for the type of the Role this Topic plays (:rtype),
-      # for the Association type (:atype),
-      # for the type of another role (:otype) as well as
-      # for the player of this other role (:oplayer).
-      # Each value of this filter-hash may be a Topic, String-Reference or Locator.
-      #
-      # The result may be empty.
-      #
-      # :call-seq:
-      #   associations_played                         -> Array of Associations
-      #   associations_played({:rtype => identifier}) -> Array of Associations
-      #   associations_played({:atype => identifier}) -> Array of Associations
-      #   associations_played({:otype => identifier}) -> Array of Associations
-      #   associations_played({:otype => identifier, :oplayer => identifier}) -> Array of Associations
-      #   associations_played({:rtype => identifier, :atype => identifier}) -> Array of Associations
-      #   associations_played({:rtype => identifier, :atype => identifier, :otype => identifier}) -> Array of Associations
-      #   associations_played({:rtype => identifier, :atype => identifier, :otype => identifier, :oplayer => identifier}) -> Array of Associations
-      #
-      def associations_played(filter = {})
-        roles = self.counterparts(filter)
-        
-        if filter[:oplayer]
-          oplayer = topic_map.get(filter[:oplayer])
-          roles = roles.map do |role|
-            (role.player==oplayer)?role:nil
-          end.compact
+    # Returns all Associations in which this Topic
+    # is a player.
+    #
+    # A filter-hash may be used to filter
+    # for the type of the Role this Topic plays (:rtype),
+    # for the Association type (:atype),
+    # for the type of another role (:otype) as well as
+    # for the player of this other role (:oplayer).
+    # Each value of this filter-hash may be a topic reference.
+    #
+    # The result may be empty.
+    #
+    # :call-seq:
+    #   associations_played                         -> Array of Associations
+    #   associations_played({:rtype => identifier}) -> Array of Associations
+    #   associations_played({:atype => identifier}) -> Array of Associations
+    #   associations_played({:otype => identifier}) -> Array of Associations
+    #   associations_played({:otype => identifier, :oplayer => identifier}) -> Array of Associations
+    #   associations_played({:rtype => identifier, :atype => identifier}) -> Array of Associations
+    #   associations_played({:rtype => identifier, :atype => identifier, :otype => identifier}) -> Array of Associations
+    #   associations_played({:rtype => identifier, :atype => identifier, :otype => identifier, :oplayer => identifier}) -> Array of Associations
+    #
+    def associations_played(filter = {})
+      topic_map.cached self, :associations_played, filter do
+        raise("associations_played(filter): filter must be a Hash") unless filter.is_a?(Hash)
+        default_hash = {:rtype => :any, :atype => :any, :otype => :any, :oplayer => :any}
+        filter = default_hash.merge(filter)
+
+        # get all roles played
+        roles = self.roles_played(filter[:rtype], filter[:atype])
+        filter.delete(:rtype)
+        filter.delete(:atype)
+
+        #filter for the other roles types and players if there are other roles
+        roles = roles.reject do |role|
+          if role.parent.roles.size == 1 #association size
+            if (filter[:otype] != :any) || filter[:player] != :any
+            end
+          else
+            role.counterparts(filter).empty?
+          end
         end
-        
-        roles.map do |role|
-          role.parent
-        end.uniq
+
+        # return parent associations
+        roles.map{|role| role.parent}.uniq
       end
     end
+      
   end
 end