rtm 0.1.6 → 0.2

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

@@ -0,0 +1,114 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar::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 = 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
+      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
+      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
+      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
+      scoped_index.get_variants(self).to_a
+    end
+
+    # States if this topic occurs as theme in the scope of a scoped Construct.
+    #
+    # :call-seq:
+    #   used_as_theme? -> true or false
+    #
+    def used_as_theme?
+      used_as_name_theme? || used_as_occurrence_theme? || used_as_association_theme? || used_as_variant_theme?
+    end
+
+    # States if this topic occurs as theme in the scope of an Association.
+    #
+    # :call-seq:
+    #   used_as_association_theme? -> true or false
+    #
+    def used_as_association_theme?
+      not self.scoped_associations.empty?
+    end
+    
+    # States if this topic occurs as theme in the scope of a Name.
+    #
+    # :call-seq:
+    #   used_as_name_theme? -> true or false
+    #
+    def used_as_name_theme?
+      not self.scoped_names.empty?
+    end
+    
+    # States if this topic occurs as theme in the scope of an Occurrence.
+    #
+    # :call-seq:
+    #   used_as_occurrence_theme? -> true or false
+    #
+    def used_as_occurrence_theme?
+      not self.scoped_occurrences.empty?
+    end
+
+    # States if this topic occurs as theme in the scope of a Variant.
+    #
+    # :call-seq:
+    #   used_as_variant_theme? -> true or false
+    #
+    def used_as_variant_theme?
+      not self.scoped_variants.empty?
+    end
+
+    private
+    def scoped_index
+      @scoped_index ||= topic_map.scoped_index
+    end
+
+  end
+end
+  

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

@@ -0,0 +1,86 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar
+  module Topic
+    module TopicRef
+      
+      # Returns an Array including all identifiers of this Topic.
+      #
+      # This method takes a Hash as argument.
+      #
+      # The key :ouputstyle defines if the ctm style (value :ctm, this is
+      # the default), the YAML
+      # style (value :yaml) or no style (value :blank) is supported.
+      #
+      # In ctm style an item identifier starts with a "^",
+      # a subject locator starts with a "=" and
+      # a subject identifiers contains no prefix.
+      #
+      # In yaml style an item identifiers start with a "ii:",
+      # a subject locator starts with a "sl:" and
+      # a subject identifier start with a "si:".
+      #
+      # :call-seq:
+      #     references -> Array of Strings
+      #     references(params = {}) -> Array of Strings
+      #
+      def references(params = {})
+        default_hash = {:outputstyle => :ctm, :resolve_qnames => :false}
+        params = default_hash.merge(params) if params.is_a? Hash
+        
+        case params[:outputstyle]
+        when :yaml
+            identifiers = subject_identifiers.map{|si| "si:#{si.reference}"} +
+                          subject_locators.map{   |sl| "sl:#{sl.reference}"} +
+                          item_identifiers.map{   |ii| "ii:#{ii.reference}"}
+        when :blank
+            identifiers = subject_identifiers.map{|si| si.reference} +
+                          subject_locators.map{   |sl| sl.reference} +
+                          item_identifiers.map{   |ii| ii.reference}
+        else #:ctm default
+            identifiers = subject_identifiers.map{|si| si.reference} +
+                          subject_locators.map{   |sl| "=#{sl.reference}"} +
+                          item_identifiers.map{   |ii| "^#{ii.reference}"}
+        end
+        return identifiers
+      end
+
+      # Returns one identifier of this topic. If several exist, the shortest one
+      # is returned.
+      #
+      # This method takes a Hash as argument.
+      #
+      # The key :ouputstyle defines if the ctm style (value :ctm, this is
+      # the default), the YAML
+      # style (value :yaml) or no style (value :blank) is supported.
+      #
+      # In ctm style an item identifier starts with a "^",
+      # a subject locator starts with a "=" and
+      # a subject identifiers contains no prefix.
+      #
+      # In yaml style an item identifiers start with a "ii:",
+      # a subject locator starts with a "sl:" and
+      # a subject identifier start with a "si:".
+      #
+      #
+      # :call-seq:
+      #     reference -> String
+      #     reference(params = {}) -> String
+      #
+      def reference(params = {})
+        return references(params).sort_by{|identifier| identifier.size}.reverse.first
+      end
+
+      # Returns all identifiers of this Topic as Array of Locators.
+      #
+      # :call-seq:
+      #   references_as_locators -> Array of Locators
+      #
+      def references_as_locators
+        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,207 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::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)
+        topic_map.cached self, :is_a?, type do
+          self.transitive_types.include?(topic_map.get(type))
+        end
+      end
+
+      # States if this topic is used as type of a typed Construct.
+      #
+      # :call-seq:
+      #   used_as_type? -> true or false
+      #
+      def used_as_type?
+        used_as_name_type? || used_as_occurrence_type? || used_as_association_type? || used_as_role_type?
+      end
+
+      # States if this topic is used as type of an Association.
+      #
+      # :call-seq:
+      #   used_as_association_type? -> true or false
+      #
+      def used_as_association_type?
+        not self.typed_associations.empty?
+      end
+
+      # States if this topic is used as type of a Name.
+      #
+      # :call-seq:
+      #   used_as_name_type? -> true or false
+      #
+      def used_as_name_type?
+        not self.typed_names.empty?
+      end
+
+      # States if this topic is used as type of an Occurrence.
+      #
+      # :call-seq:
+      #   used_as_occurrence_type -> true or false
+      #
+      def used_as_occurrence_type?
+        not self.typed_occurrences.empty?
+      end
+
+      # States if this topic is used as type of a Role.
+      #
+      # :call-seq:
+      #   used_as_role_type? -> true or false
+      #
+      def used_as_role_type?
+        not self.typed_roles.empty?
+      end
+
+    end
+  end
+end

data/lib/rtm/sugar/topic_map/query_cache.rb

@@ -0,0 +1,66 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::Sugar
+  module TopicMap
+    module QueryCache 
+
+      # The query cache is disabled by default. Enables the query cache.
+      # Does not erase the cache if it was already enabled.
+      #
+      # :call-seq:
+      #   enable_query_cache -> nil
+      #
+      def enable_query_cache
+        @query_cache ||= {}
+        return
+      end
+
+      # The query cache is disabled by default. Disables the query cache.
+      #
+      # :call-seq:
+      #  disable_query_cache -> nil
+      #
+      def disable_query_cache
+        @query_cache = nil # FIXME: This method is unsafe in multithreaded environments: Setting "@query_cache = nil" while @query_cache is being accessed in method "cached" may cause exceptions to be raised. 
+        return
+      end
+
+      # Erases the query cache. This needs to be invoked every time there
+      # is a write access to the topic map.
+      #
+      # :call-seq:
+      #   reset_query_cache -> nil
+      #
+      def reset_query_cache
+        @query_cache = @query_cache? {} : nil
+        return
+      end
+
+      # If query caching is enabled, looks up the result of
+      # module_name.method_name(parameters) in the cache and if present,
+      # returns it. If
+      # the result has not yet been stored, executes module_name.method_name(parameters),
+      # stores the result and returns it.
+      #
+      # If query caching is disabled, executes module_name.method_name(parameters)
+      # and returns the result.
+      #
+      # :call-seq:
+      #   cached(module_name, method_name, parameters) {method_body} -> result
+      #
+      def cached(*args)
+        if @query_cache # Maybe we can optimize this simple if statement away by making enable_query_cache extend the particular TopicMap instance's metaclass. But maybe then the cached version is slower.
+          result = @query_cache.fetch(args,:not_found) # :not_found if not cached, if result is nil, we want to cache nil as well.
+          if result==:not_found
+            result = yield
+            @query_cache[args] = result
+          end
+          return result
+        else
+          yield #execute without caching
+        end
+      end
+    end
+  end
+end