rtm 0.1.6 → 0.2.0

data/lib/rtm/navigation/occurrence/atomify.rb

@@ -0,0 +1,19 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Occurrence
+      
+      # Returns the atomic value of the Characteristic (Name/Occurrence).
+      #
+      # :call-seq:
+      #   atomify -> String
+      #
+      def atomify
+        value
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/occurrence/characteristics.rb

@@ -0,0 +1,33 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Occurrence
+      
+      # Returns the Topic this Characteristic (Name/Occurrence) belongs to.
+      # The optional argument identifier filters the
+      # Characteristic for its type. If the type
+      # does not match, nil is returned.
+      #
+      # The identifier may be a Topic or Topic-Reference.
+      #
+      # :call-seq:
+      #   reverse_characteristics -> Topic
+      #   reverse_characteristics(identifier) -> Topic or nil
+      #
+      def reverse_characteristics(type=:any)
+        return parent if type == :any
+        _topic = topic_map.get(type)
+        return nil unless _topic
+        #filter the Name/Occurrence for its type:
+        if _topic == self.type
+          return parent
+        else
+          return nil
+        end
+      end
+      
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation  
+    module Topic
+      
+      # Returns all Names and Occurrences of this Topic.
+      # If an identifier is given, only those Names and Occurrences are returned,
+      # whose type or supertypes include the identifier.
+      #
+      # Identifier may be a Topic or Topic-Reference.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   characteristics -> Array of Names and Occurrences
+      #   characteristics(identifier) -> Array of Names and Occurrences
+      #
+      def characteristics(type=:any)
+        # FIXME which version of the code?
+        return names.to_a + occurrences.to_a if type == :any
+        _topic = topic_map.get(type)
+        return [] unless _topic
+        #names.select{|n| n.type.include?(_topic) || n.type.supertypes.include?(_topic)}.to_a +
+        #occurrences.select{|o| o.type.include?(_topic) || o.type.supertypes.include?(_topic)}.to_a
+        names.select{|n| n.type.supertypes.include?(_topic)}.to_a +
+        occurrences.select{|o| o.type.supertypes.include?(_topic)}.to_a
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/indicators.rb

@@ -0,0 +1,31 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation  
+    module Topic
+      
+      # Returns all indicators (subject identifiers) of this Topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   indicators -> Array of Strings
+      #
+      def indicators
+        getSubjectIdentifiers.map{|locator| locator.value}
+      end
+      
+      # Returns one indicator (subject identifier) of this Topic or nil
+      # if this Topic has no indicator.
+      #
+      # :call-seq:
+      #   indicator -> String or nil
+      #
+      def indicator
+        return indicators.empty? ? nil : indicators.sort.first # TODO Which sorting algorithm?
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/items.rb

@@ -0,0 +1,31 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation 
+    module Topic
+           
+      # Returns all item identifier of this Topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   items -> Array of Strings
+      #
+      def items
+        getItemIdentifiers.map{|locator| locator.value}
+      end
+      
+      # Returns one item identifier of this Topic or nil
+      # if this Topic has no item identifier.
+      #
+      # :call-seq:
+      #   item -> String or nil
+      #   
+      def item
+        return items.empty? ?  nil : items.sort.first # TODO Which sorting algorithm?
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/locators.rb

@@ -0,0 +1,31 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Topic
+      
+      # Returns all subject locators of this Topic.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   locators -> Array of Strings
+      #
+      def locators
+        getSubjectLocators.map{|locator| locator.value}
+      end
+      
+      # Returns one subject locator of this Topic or nil
+      # if this Topic has no subject locator.
+      #
+      # :call-seq:
+      #   locator -> String or nil
+      #
+      def locator
+        return locators.empty? ? nil : locators.sort.first # TODO Which sorting algorithm?
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/players.rb

@@ -0,0 +1,27 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Topic
+      
+      # Returns all Associations in which this Topic plays a Role.
+      #
+      # The optional
+      # identifier specifies the type of the Roles to be considered.
+      # The identifier may be a Topic or Topic-Reference.
+      #
+      # Multiple instances of the same Association are possible.
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   reverse_players -> Array of Associations
+      #   reverse_players(identifier) -> Array of Associations
+      #
+      def reverse_players(type = :any)
+        roles_played(type).map{|r| r.parent}
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/supertypes.rb

@@ -0,0 +1,162 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Topic
+      
+      # Returns all Topic players that exist in binary supertype-subtype Associations
+      # where this Topic playes the subtype-Role.
+      #
+      # The result may be an empty Array.
+      #
+      # :call-seq:
+      #   direct-supertypes -> Array of Topics
+      #
+      def direct_supertypes
+        roles_played(topic_map.get(RTM::PSI[:subtype]),topic_map.get(RTM::PSI[:supertype_subtype])).
+          reject{|r| r.getParent.getRoles.size!=2}.
+          map{|r| r.parent[RTM::PSI[:supertype]].first.player}.flatten.uniq
+      end
+      
+      # Creates a binary supertype-subtype-Association where identifier defines
+      # the player of the supertype-Role. The current Topic will play the
+      # subtype-Role. Returns the created Association.
+      #
+      # Identifier may be a Topic or Topic-Reference.
+      #
+      # :call-seq:
+      #   add_supertype(identifier) -> Association
+      #
+      def add_supertype(new_supertype)
+        asso = topic_map.create_association(RTM::PSI[:supertype_subtype])
+        asso.create_role(RTM::PSI[:subtype],self)
+        asso.create_role(RTM::PSI[:supertype],new_supertype)
+        asso
+      end
+
+      # Creates one or several binary supertype-subtype-Associations where
+      # each identifier defines
+      # the player of a supertype-Role. The current topic will play the
+      # subtype-Role in each association. Returns the associations.
+      #
+      # The identifier may be topic references.
+      #
+      # :call-seq:
+      #   add_supertypes(identifier1, identifier2, ...) -> Array of Associtions
+      #
+      def add_supertypes(*args)
+        args.flatten!
+        args.map{|identifier| add_supertype(identifier)}
+      end
+
+      # Returns all supertypes of this Topic. The result includes 
+      # all direct supertypes
+      # and the supertypes of these direct supertypes.
+      #
+      # The result may be an empty Array.
+      #
+      # :call-seq:
+      #   transitive_supertypes -> Array of Topics
+      #
+      def transitive_supertypes
+        result_types = new_s_t = direct_supertypes
+        until new_s_t.empty?
+          new_s_t = new_s_t.map{|s| s.direct_supertypes}.flatten.uniq
+          new_s_t = new_s_t.reject{|s| result_types.include?(s)}
+          result_types = result_types + new_s_t
+        end
+        return result_types
+      end
+      
+      # Returns all supertypes of this Topic. The result includes the direct_supertypes
+      # and the supertypes of these direct_supertypes of this Topic as well as the Topic itself.
+      #
+      # :call-seq:
+      #   transitive_supertypes_with_self -> Array of Topics
+      #
+      def transitive_supertypes_with_self
+        transitive_supertypes + self
+      end
+      
+      # Returns all Topics that exist in binary supertype-subtype Associations
+      # where this Topic playes the supertype-Role.
+      #
+      # The result may be an empty Array.
+      #
+      # :call-seq:
+      #   direct-subtypes -> Array of Topics
+      #
+      def direct_subtypes
+        roles(topic_map.get(RTM::PSI[:supertype]),topic_map.get(RTM::PSI[:supertype_subtype])).
+          reject{|r| r.getParent.getRoles.size!=2}.
+          map {|r| r.getParent[RTM::PSI[:subtype]].first.player}.flatten.uniq
+      end
+      
+      # Creates a binary supertype-subtype-Association where identifier defines
+      # the player of the subtype-Role. The current Topic will play the
+      # supertype-Role. Returns the created Association.
+      #
+      # Identifier may be Topic or Topic Reference.
+      #
+      # :call-seq:
+      #   add_subtype(identifier) -> Association
+      #
+      def add_subtype(new_subtype)
+        asso = topic_map.create_association(RTM::PSI[:supertype_subtype])
+        asso.create_role(RTM::PSI[:supertype],self)
+        asso.create_role(RTM::PSI[:subtype],new_subtype)
+        asso
+      end
+
+      # Creates one or several binary supertype-subtype-Associations where
+      # each identifier defines
+      # the player of a subtype-Role. The current topic will play the
+      # supertype-Role in each association. Returns the associations.
+      #
+      # The identifier may be topic references.
+      #
+      # :call-seq:
+      #   add_subtypes(identifier1, identifier2, ...) -> Array of Associtions
+      #
+      def add_subtypes(*args)
+        args.flatten!
+        args.map{|identifier| add_subtype(identifier)}
+      end
+
+      # Returns all subtypes of this Topic. The result includes the direct subtypes
+      # and the subtypes of these direct subtypes.
+      #
+      # The result may be an empty Array.
+      #
+      # :call-seq:
+      #   transitive_subtypes -> Array of Topics
+      #
+      def transitive_subtypes
+        result_types = new_s_t = direct_subtypes
+        until new_s_t.empty?
+          new_s_t = new_s_t.map{|s| s.direct_subtypes}.flatten.uniq
+          new_s_t = new_s_t.reject{|s| result_types.include?(s)}
+          result_types = result_types + new_s_t
+        end
+        return result_types
+      end
+      
+      # Returns all subtypes of this Topic. The result includes the direct_subtypes
+      # and the subtypes of these direct_subtypes of this Topic as well as the Topic itself.
+      #
+      # :call-seq:
+      #   transitive_subtypes_with_self -> Array of Topics
+      #
+      def transitive_subtypes_with_self
+        transitive_subtypes + self
+      end
+      
+      alias :supertypes :transitive_supertypes
+      alias :subtypes :transitive_subtypes
+      alias :reverse_subtypes :supertypes
+      alias :reverse_supertypes :subtypes
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/traverse.rb

@@ -0,0 +1,51 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Topic
+      
+      # First computes all Associations where this Topic playes a Role.
+      # There, the optional identifier filters the Associations for their type.
+      # 
+      # Returns all Players of all Roles in these Associations.
+      # The current Topic is not included in the result.
+      # The result may be empty.
+      #
+      # The identifier may be a Topic or Topic-Reference.
+      #
+      # :call-seq:
+      #   traverse(identifier) -> Array of Topics
+      #
+      def traverse(type = :any)
+        unless type == :any
+          _topic = topic_map.get(type)
+          return [] unless _topic
+        end
+        _res = roles_played.map{|r| r.parent} #associations
+        _res = _res.select{|a| a.type == _topic} unless type == :any
+        _res = _res.map{|a| a.roles.map{ |r| r.player}}.flatten #players of all roles in these associations
+        #            unless _res.empty?
+        #              _res.each_with_index do |x,i|
+        #                if x == self
+        #                  _res.delete_at(i)
+        #                  break
+        #                end
+        #              end
+        #            end
+        _res =_res.reject{|p| p == self}
+        return _res
+      end
+      
+      # Always returns an empty Array
+      #
+      # :call-seq:
+      #   reverse_traverse -> Array
+      #
+      def reverse_traverse 
+        Array.new
+      end
+      
+    end
+  end
+end

data/lib/rtm/navigation/topic/types.rb

@@ -0,0 +1,107 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM
+  module Navigation
+    module Topic
+      
+      # Returns the topics this topic is an instance of.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   types -> Set of Topics
+      #
+      def types
+        # NO SUPERISE IN Axes/NAVIGATION
+        raise "This method (types) should never be executed because the corresponding TMAPI function should be called"
+        getTypes
+      end
+      
+      # Returns the topic this topic is an instance of. It must have
+      # exactly one type, else an error is raised.
+      #
+      # Returns nil if this Topic has no type.
+      #
+      # :call-seq:
+      #   type -> Topic or nil
+      #
+      def type
+        raise "Topic must have exactly one type to call the type-method. Use the types-method instead." unless types.size < 2
+        types.size == 1 ? types.to_a.first : nil
+      end
+      
+      # Returns the topics which are instances of this topic.
+      # This method uses the TMAPI TypeInstanceIndex.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   instances -> Set of Topics
+      #
+      def instances
+        type_instance_index.getTopics(self)
+      end
+      
+      # Returns the instance of this Topic. It must have exactly one
+      # instance, else an error is raised.
+      #
+      # Returns nil if this Topic has no instance.
+      #
+      # :call-seq:
+      #   instance -> Topic
+      #
+      def instance
+        raise "Topic must have exactly one instance to call the instance-method. Use the instances-method instead." unless instances.size < 2
+        instances.size == 1 ?  instances.to_a.first : nil
+      end
+      
+      alias :reverse_types :instances
+      
+      # Returns the types this topic is an instance of. Calls
+      # the TMAPI getTypes method.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   reverse_instances -> Set of Topics
+      #
+      def reverse_instances
+        types
+      end
+
+      # Returns the types and all transitive supertypes of the types of
+      # this topic. No duplicates are returned.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_types -> Array of Topics
+      #
+      def transitive_types
+        trans_types = types.to_a #may be empty
+        types.each do |type|
+          trans_types.concat(type.transitive_supertypes)
+        end
+        trans_types = trans_types.uniq #no duplicates outside of tmql mode
+      end
+
+      # Returns instances and the instances of all transitive subtypes
+      # of this topic. No duplicates are returned.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   transitive_instances -> Array of Topics
+      #
+      def transitive_instances
+        trans_instances = instances.to_a #may be empty
+        transitive_subtypes.each do |subtype|
+          trans_instances.concat(subtype.instances.to_a)
+        end
+        trans_instances = trans_instances.uniq #no duplicates outside of tmql mode
+      end
+
+    end
+  end
+end