rtm 0.2.0 → 0.2.1

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

@@ -1,65 +1,114 @@
 # Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar
-  module Topic
-    module Scoped
+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 = 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, 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 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 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
 
-      # 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
+    # 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
 
-      # 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
+    # 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
 
-      # 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
+    # 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

@@ -1,32 +1,83 @@
 # Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
 # License:   Apache License, Version 2.0
 
-module Sugar
+module RTM::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.
+      #
+      # 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:
-      #     topic_references -> Array of Strings
+      #     references -> Array of Strings
+      #     references(params = {}) -> 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}"}
+      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:
-      #   topic_references_as_locators -> Array of Locators
+      #   references_as_locators -> Array of Locators
       #
-      def topic_references_as_locators
-        # TODO Spec
+      def references_as_locators
         subject_identifiers.to_a + subject_locators.to_a + item_identifiers.to_a
       end
 

data/lib/rtm/sugar/topic/typed.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 Topic
     module Typed
       
@@ -152,8 +152,56 @@ module Sugar
       #   topic_is_a?(type)
       #
       def topic_is_a?(type)
-        self.transitive_types.include?(topic_map.get(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

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

@@ -0,0 +1,53 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+
+module RTM::Sugar
+  module TopicMap
+    module Themes
+
+      # Returns all topics in the topic map used
+      # in the scope property of Associations.
+      #
+      # The result may be empty.
+      #
+      # :call-seq:
+      #   association_themes -> Array of Topics
+      #
+      def association_themes
+        scoped_index.get_association_themes.to_a
+      end
+
+      # Returns all topics in the topic map used
+      # in the scope property of Names.
+      #
+      # :call-seq:
+      #   name_themes -> Array of Topics
+      #
+      def name_themes
+        scoped_index.get_name_themes.to_a
+      end
+
+      # Returns all topics in the topic map used
+      # in the scope property of Occurrences.
+      #
+      # :call-seq:
+      #   occurrence_themes -> Array of Topics
+      #
+      def occurrence_themes
+        scoped_index.get_occurrence_themes.to_a
+      end
+
+      # Returns all topics in the topic map used
+      # in the scope property of Variants.
+      #
+      # :call-seq:
+      #   variant_themes -> Array of Topics
+      #
+      def variant_themes
+        scoped_index.get_variant_themes.to_a
+      end
+
+    end
+  end
+end