rtm 0.1.6 → 0.2.0

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

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

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

@@ -0,0 +1,65 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module Sugar
+  module Topic
+    module Scoped
+      
+      # Returns the Associations, Names, Occurrences and Variants
+      # whose scope contains this Topic. Beware: The scope of a Variant includes
+      # the themes of the Name this Variant belongs to.
+      #
+      # :call-seq:
+      #   scoped -> Array of Associations, Names, Occurrences and Variants
+      #
+      def scoped
+        _index = topic_map.scoped_index
+        _index.get_associations(self).to_a + _index.get_names(self).to_a + _index.get_occurrences(self).to_a + _index.get_variants(self).to_a
+      end
+
+      # Returns the Associations whose scope contains this Topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   scoped_associations -> Array of Associations
+      #
+      def scoped_associations
+        topic_map.scoped_index.get_associations(self).to_a
+      end
+
+      # Returns the Names whose scope contains this Topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   scoped_names -> Array of Names
+      #
+      def scoped_names
+        topic_map.scoped_index.get_names(self).to_a
+      end
+
+      # Returns the Occurrences whose scope contains this Topic.
+      #
+      # :call-seq:
+      #   scoped_occurrences -> Array of Occurrences
+      #
+      def scoped_occurrences
+        topic_map.scoped_index.get_occurrences(self).to_a
+      end
+
+      # Returns the Variants whose scope (including the scope of the parent Name)
+      # contains this Topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   scoped_variants -> Array of Variants
+      #
+      def scoped_variants
+        topic_map.scoped_index.get_variants(self).to_a
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module Sugar
+  module Topic
+    module TopicRef
+      
+      # Returns an Array including all identifiers of this Topic.
+      # Item identifiers start with a "^", subject locators start
+      # with a "=", subject identifiers contain no prefix.
+      #
+      # :call-seq:
+      #     topic_references -> Array of Strings
+      #
+      def topic_references
+      #def identifiers
+        subject_identifiers.map{|si| si.reference} +
+        subject_locators.map{|sl| "=#{sl.reference}"} +
+        item_identifiers.map{|ii| "^#{ii.reference}"}
+      end
+
+
+      # Returns all identifiers of this Topic as Array of Locators.
+      #
+      # :call-seq:
+      #   topic_references_as_locators -> Array of Locators
+      #
+      def topic_references_as_locators
+        # TODO Spec
+        subject_identifiers.to_a + subject_locators.to_a + item_identifiers.to_a
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,159 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module Sugar
+  module Topic
+    module Typed
+      
+      # Returns the associations, names, occurrences and roles whose
+      # type equals this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   typed -> Array of Associations, Names, Occurrences and Roles
+      #
+      def typed
+        _index = topic_map.type_instance_index
+        _index.get_associations(self).to_a + _index.get_names(self).to_a + _index.get_occurrences(self).to_a + _index.get_roles(self).to_a
+      end
+
+      # Returns the associations, names, occurrences and roles whose
+      # type equals this topic or subtypes
+      # of this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_typed -> Array of Associations, Names, Occurrences and Roles
+      #
+      def transitive_typed
+        trans_typed = typed #may be empty
+        transitive_subtypes.each do |subtype|
+          trans_typed.concat(subtype.typed)
+        end
+        trans_typed = trans_typed.uniq #no duplicates outside of tmql mode
+      end
+
+      # Returns the associations whose type equals this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   typed_associations -> Array of Associations
+      #
+      def typed_associations
+        topic_map.type_instance_index.get_associations(self).to_a
+      end
+
+      # Returns the associations whose type equals this topic or subtypes
+      # of this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_typed_associations -> Array of Associations
+      #
+      def transitive_typed_associations
+        trans_types_assocs = typed_associations #may be empty
+        transitive_subtypes.each do |subtype|
+          trans_types_assocs.concat(subtype.typed_associations)
+        end
+        trans_types_assocs = trans_types_assocs.uniq #no duplicates outside of tmql mode
+      end
+
+      # Returns the names whose type equals this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   typed_names -> Array of Names
+      #
+      def typed_names
+        topic_map.type_instance_index.get_names(self).to_a
+      end
+
+      # Returns the names whose type equals this topic or subtypes
+      # of this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_typed_names -> Array of Associations
+      #
+      def transitive_typed_names
+        trans_types_names = typed_names #may be empty
+        transitive_subtypes.each do |subtype|
+          trans_types_names.concat(subtype.typed_names)
+        end
+        trans_types_names = trans_types_names.uniq #no duplicates outside of tmql mode
+      end
+
+      # Returns the occurrences whose type equals this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   typed_occurrences -> Array of Occurrences
+      #
+      def typed_occurrences
+        topic_map.type_instance_index.get_occurrences(self).to_a
+      end
+
+      # Returns the occurrences whose type equals this topic or subtypes
+      # of this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_typed_occurrences -> Array of Associations
+      #
+      def transitive_typed_occurrences
+        trans_types_occs = typed_occurrences #may be empty
+        transitive_subtypes.each do |subtype|
+          trans_types_occs.concat(subtype.typed_occurrences)
+        end
+        trans_types_occs = trans_types_occs.uniq #no duplicates outside of tmql mode
+      end
+
+      # Returns the roles whose type equals this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   typed_roles -> Array of Roles
+      #
+      def typed_roles
+        topic_map.type_instance_index.get_roles(self).to_a
+      end
+
+      # Returns the roles whose type equals this topic or subtypes
+      # of this topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_typed_roles -> Array of Associations
+      #
+      def transitive_typed_roles
+        trans_types_roles = typed_roles #may be empty
+        transitive_subtypes.each do |subtype|
+          trans_types_roles.concat(subtype.typed_roles)
+        end
+        trans_types_roles = trans_types_roles.uniq #no duplicates outside of tmql mode
+      end
+
+      # Determines whether this topic is instance (directly or indirectly)
+      # of the argument type.
+      #
+      # Type may be a topic reference.
+      #
+      # :call-seq:
+      #   topic_is_a?(type)
+      #
+      def topic_is_a?(type)
+        self.transitive_types.include?(topic_map.get(type))
+      end
+    end
+  end
+end