rtm 0.1.6 → 0.2

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,15 +1,129 @@
-module RTM::Sugar
-  module Topic
-    module Characteristics
-      def characteristics
-        topic_names.to_a + occurrences.to_a
-      end
-      def internal_occurrences
-        occurrences.select{|o| o.datatype != RTM::PSI[:IRI]}
-      end
-      def external_occurrences
-        occurrences.select{|o| o.datatype == RTM::PSI[:IRI]}
-      end      
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar::Topic::Characteristics
+  
+  # Returns all Occurrences of this Topic whose datatype is not IRI
+  #
+  # :call-seq:
+  #   internal_occurrences -> Set of Occurrences
+  #
+  def internal_occurrences
+    occurrences.select{|x| x.getDatatype.toExternalForm != RTM::PSI[:IRI]}
+  end
+  
+  # Returns all Occurrences of this Topic whose datatype is IRI
+  #
+  # :call-seq:
+  #   external_occurrences -> Set of Occurrences
+  #
+  def external_occurrences
+    occurrences.select{|y| y.getDatatype.toExternalForm == RTM::PSI[:IRI]}
+  end
+  
+  # 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
+  # are selected. If scope is set to :any (default), scope does not constrain
+  # 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
+  # or scope does not exist.
+  #
+  # :call-seq:
+  #   names_by -> Array of Names
+  #   names_by(:type => identifier) -> Array of Names
+  #   names_by(:value => string) -> Array of Names
+  #   names_by(:scope => identifier) -> Array of Names
+  #   names_by(:type => identifier, :value => string) -> Array of Names
+  #   names_by(:type => identifier, :value => string, :scope => identifier) -> Array of Names
+  #   and so on
+  #
+  def names_by(args = {})
+    raise("names_by: arguments must be a Hash") unless args.is_a?(Hash)
+    default_hash = {:type => :any, :value => :any, :scope => :any}   
+    args = default_hash.merge(args)
+    #filter for type
+    _names = args[:type] == :any ? names : names(args[:type])
+    _names = self.filter_by(_names,args)
+    # return Array
+    return _names.to_a
+  end
+  
+  # Returns Occurrences of this Topic which may be filtered for their type,
+  # value, datatype and/or scope.
+  #
+  # 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 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.
+  #
+  # :call-seq:
+  #   occurrence_by -> Array of Occurrences
+  #   occurrences_by(:type => argument) -> Array of Occurrences
+  #   occurrences_by(:value => argument) -> Array of Occurrences
+  #   occurrences_by(:scope => argument) -> Array of Occurrences
+  #   occurrences_by(:datatype => argument) -> Array of Occurrences
+  #   occurrences_by(:type => argument1, :value => argument2) -> Array of Occurrences
+  #   occurrences_by(:type => argument1, :value => argument2, :scope => argument3, :datatype => argument4) -> Array of Occurrences
+  #   and so on
+  #
+  def occurrences_by(args = {})
+    raise("occurrences_by: arguments must be a Hash") unless args.is_a?(Hash)
+    default_hash = {:type => :any, :value => :any, :scope => :any, :datatype => :any}
+    args = default_hash.merge(args)
+    #filter for type
+    _occurrences = args[:type] == :any ? occurrences : occurrences(args[:type])
+    _occurrences = self.filter_by(_occurrences,args)
+    #filter for datatype
+    _occurrences = _occurrences.select{|o| o.datatype == args[:datatype]} unless args[:datatype] == :any
+    return _occurrences.to_a
+  end
+  
+ protected
+  def filter_by(_characteristics,args)
+    #filter for value
+    unless args[:value] == :any
+      _characteristics = args[:value].is_a?(Array) ? _characteristics.select{|o| args[:value].any?{|v| o.value == v}} : _characteristics.select{|o| o.value == args[:value]}
+    end
+    #filter for scope
+    case args[:scope]
+      when :any
+      when :ucs, []
+        _characteristics = _characteristics.select{|o| o.scope.empty?}
+      else
+        _scope = topic_map.get(args[:scope])
+        _characteristics = _scope.is_a?(Array) ? _characteristics.select{|o| _scope.any?{|theme| o.scope.include?(theme)}} : _characteristics.select{|o| o.scope.include?(_scope)}
     end
+    _characteristics
   end
+  
+  # Returns the Occurrences and Names of this Topic which have the specified type as
+  # Occurrence/Name type. Additionally, scope may constrain the the selection.
+  #
+  # If scope is set to :ucs, Occurrences/Names which exist in the unconstrained scope
+  # are selected. If scope is set to :any (default), scope does not constrain
+  # the Occurrence/Names-Array. Else, only the Occurrences/Names which exist in the given scope
+  # are selected.
+  #
+  # Returns an empty Array if no Occurrences or Names match or if the Occurrence/Name type or
+  # scope does not exist.
+  #
+  # :call-seq:
+  #    characteristics_by -> Array of Occurrences and Names
+  #
+#  def characteristics_by(args = {})
+#    raise("characteristics_by: arguments must be a Hash") unless args.is_a?(Hash)
+#    default_hash = {:type => :any, :value => :any, :scope => :any, :datatype => :any}
+#    args = default_hash.merge(args)
+#    _names = names_by(args) if args[:datatype].include(:any) || args[:datatype] == RTM::PSI[:String] || args[:datatype] == topic_map.create_locator(RTM::PSI[:String])
+#    _occurrences = occurrences_by(args)
+#    
+#  end
+  
 end

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

@@ -1,15 +1,150 @@
-module RTM::Sugar
-  module Topic
-    module Counterparts
-      def counterparts(filter={})
-        self.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)}                  
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+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 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 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 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
       end
-      def counterplayers(*args)
-        return self.counterparts(*args).map{|r| r.player}
+      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 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
+
+        # return parent associations
+        roles.map{|role| role.parent}.uniq
       end
     end
+      
   end
 end

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

@@ -1,52 +1,162 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
 module RTM::Sugar
   module Topic
+    # This module implements methods for Hash-like access in Topics.
     module HashAccess
-      def [](cref)
-        raise "Characteristic reference must be a String" unless cref.is_a? String
-        is_name, type_reference, scope_reference = resolve_characteristic(cref)
-        if is_name
+
+      # Returns an Array of Names or Occurrences of
+      # this Topic depending on the argument given.
+      #
+      # If argument is a Topic, an Array of Occurrences of this Topic which
+      # have the specified type is returned.
+      #
+      # Argument may be a String. Then the structure should resemble "-type @scope"
+      # or "type @scope".
+      #
+      # If argument starts with a "-", an Array of Names of this
+      # Topic, which have the specified type (trailing the "-"),
+      # is returned.
+      # 
+      # If argument equals "-", Names that have the standard name type
+      # are returned.
+      #
+      # If argument starts with a "*", both Names and Occurrences, which have the
+      # specified type (trailing the "*") are returned as Array.
+      #
+      # If argument equals "*", all Names and Occurrences of this Topic are
+      # returned. In this case this method equals the characteristics()-method.
+      #
+      # Else, if argument is a String, an Array of Occurrences
+      # of this Topic, which have the specified type,
+      # is returned.
+      #
+      # The argument may include an "@" after the type.
+      # The String trailing the @ defines the
+      # scope the selected Names and Occurrences should live in. Themes in the
+      # scope may be c.
+      #
+      # Examples:
+      #  topic[occtype_topic]
+      #  topic["-"]
+      #  topic["*"]
+      #  topic["-nametype"]
+      #  topic["-nametype @scope]
+      #  topic["occtype @scope1, scope2"]
+      #  topic["*type"]
+      #  topic["*type @scope"]
+      #
+      # :call-seq:
+      #   [argument=Topic]  -> Array of Occurrences
+      #   [argument=String] -> Array of Names and/or Occurrences
+      #
+      def [](identifier = :any)
+        # return occurrences by type if topic is given
+        return [] unless identifier
+        return occurrences(identifier).to_a if (identifier.is_a?(RTM::Topic) || identifier == :any)
+        prefix, type_reference, scope_reference = resolve_characteristic(identifier)
+        if prefix == :name
           type_reference = RTM::PSI[:name_type] if type_reference == :any
-          names.select{|n| n.type == topic_map.get(type_reference)}
-        else
+          ret = names(type_reference).to_a
+        elsif prefix == :occurrence
           raise "No occurrence type given" if type_reference == :any
-          occurrences.select{|o| o.type == topic_map.get(type_reference)}
+          ret = occurrences(type_reference).to_a
+        elsif prefix == :both
+          ret = names(type_reference).to_a + occurrences(type_reference).to_a # type_reference == :any or not :any
+        else
+          
+        end
+        # we now have a list of names or occurrences, now we have to select for scope
+        return ret if scope_reference == :any
+        if scope_reference == :ucs
+          ret.select{|i| i.scope.size == 0}
+        else
+          ret = ret.select{|i| scope_reference.all?{|sr| i.scope.include? getParent.get(sr)}}
         end
+        ret
       end
 
-      def []=(cref, value)
-        is_name, type_reference, scope_reference = resolve_characteristic(cref)
-        if is_name
-          type_reference = nil if type_reference == :any
-          nametype = type_reference || topic_map.get!(RTM::PSI[:name_type])
-          n = create_name(value, nametype)
-          n
-        else
+      # Creates a Name or Occurrence of this Topic depending on the
+      # argument given and returns this Name/Occurrence.
+      #
+      # Argument may be a String whose structure should resemble "-type @scope"
+      # or "type @scope".
+      #
+      # If argument starts with a "-", a Name that has the specified type
+      # (trailing the "-") is created.
+      #
+      # If argument equals "-", a Name that hase the standard name type
+      # is created.
+      #
+      # Else, an Occurrence that has the specified type is created.
+      #
+      # The argument may include an "@" after the type. The String trailing
+      # the @ defines the optional scope the Name or Occurrence
+      # should live in. Themes in the scope may be comma- and/or space-separated.
+      #
+      # The value should be a String.
+      #
+      # Example:
+      #  topic[occtype]= "occvalue"
+      #  topic["-"]= "name"
+      #  topic["-nametype"]= "name"
+      #  topic["-nametype @scope]= "name"
+      #  topic["occtype @scope1, scope2"]= "occvalue"
+      #
+      # :call-seq:
+      #   [argument]= value
+      #
+      def []=(identifier, value)
+        prefix, type_reference, scope_reference = resolve_characteristic(identifier)
+        if prefix == :name
+          nametype = (type_reference==:any) ? topic_map.get!(RTM::PSI[:name_type]) : type_reference
+          scope_reference = scope_reference==:any ? [] : scope_reference
+          raise("Value is not a String") unless value.is_a?(String)
+          ret = create_name(nametype, value, scope_reference)
+        elsif prefix == :occurrence
           raise "No occurrence type given" if type_reference == :any
-          o = create_occurrence(value, type_reference)
-          o
+          ret = create_occurrence(type_reference, value)
+        else
+          return nil
         end
+        # return object without scope if any or ucs
+        return ret if [:any, :ucs].include? scope_reference
+        # set scope
+        ret.add_scope(scope_reference)
+        ret
       end
-      
+
       private
-      def resolve_characteristic(ref)
-        ref =~ /^(-\s*)?(.+)?$/
-        is_name = $1 ? true : false
+
+      def resolve_characteristic(identifier)
+        # spaces(-|*)?spaces(anything)
+        prefix = :occurrence
+        identifier =~ /^\s*(-|\*)?\s*(.+)?$/ # - or * and then everything else
+        if $1
+          prefix = ($1 == "-") ? :name : :both
+        end
         type, scope = resolve_type_and_scope($2)
-        [is_name, type, scope]
+        [prefix, type, scope]
       end
-      
+
       def resolve_type_and_scope(ref)
         return [:any, :any] unless ref
-        return [ref, :ucs] if ref.is_a? Topic
-        type, scope = ref.split('@', -1)
-        if type.blank?
+        if ref[0] == ?@
           type = :any
+          scope = ref[1..-1] #cut "@"
         else
-          type.strip!
+          type, scope = ref.split(' @', -1) # -1 -> trailing null fields are not suppressed
+          if (type == nil) || (type.length == 0)
+            type = :any
+          else
+            type.strip! #\s removed
+          end
         end
+        
         if scope
-          scope = scope.strip.split(/\s+/)
-          scope = :ucs if scope.blank?
+          scope = scope.strip.split(/\s*,?\s+/) #divided at \s,\s
+          scope = :ucs if (scope == nil) || (scope.length == 0)
         else
           scope = :any
         end
@@ -54,4 +164,4 @@ module RTM::Sugar
       end
     end
   end
-end
+end