rtm 0.2.0 → 0.2.1

data/lib/rtm/io.rb

@@ -14,5 +14,6 @@ end
 
 
 require 'rtm/io/to_yaml'
-require 'rtm/io/tmapix'
+require 'rtm/io/tmapix_from'
+require 'rtm/io/tmapix_to'
 require 'rtm/io/to_string'

data/lib/rtm/io/tmapix_from.rb

@@ -0,0 +1,155 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::IO
+  # Import for TMAPI Topic Maps
+  # Utilizing the TMAPIX libary http://code.google.com/p/tmapix/
+  # Consequently the deserializers provided here are only wrappers
+
+  module TmapiXFrom
+    module TopicMap
+
+      def from_anything(reader_class, *args)
+        raise "Only supported for TMAPI backends!!" unless self.kind_of?(Java::OrgTmapiCore::TopicMap) || self.kind_of?(Java::OrgTmapiCore::TopicMapSystem)
+
+        params = {}
+        # See if we got a params hash. It must be at the end, if it is given.
+        # Take it off, so it won't be unshifted later.
+        params = args.pop if args.last.is_a?(Hash)
+
+        # Take the source as next (i.e. second after the writer) positional parameter or from hash.
+        # Leave nil if neither found.
+        source = args.shift || params[:source]
+
+        # Take the base_iri as next (i.e. third after the file) positional parameter or from the hash.
+        # Use the topic maps's base_iri if neither found.
+        base_iri = args.shift || params[:base_iri]
+        unless base_iri
+          if self.kind_of?(RTM::TopicMap)
+            base_iri = self.base_iri
+          else
+            base_iri = "imported:FIXME"
+          end
+        end
+
+        if self.kind_of?(RTM::TopicMap)
+          topic_map = self
+        else
+          topic_map = create(base_iri)
+        end
+
+        reader_class.new(topic_map, java.io.File.new(source)).read
+        topic_map
+      end
+
+      # Reads a Topic Map from an LTM File
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_ltm(filename)
+      #
+      def from_ltm(*args)
+        from_anything(org.tmapix.io.LTMTopicMapReader, *args)
+      end
+
+      # Reads a Topic Map from an CTM File
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_ctm(filename)
+      #
+      def from_ctm(*args)
+        from_anything(org.tmapix.io.CTMTopicMapReader, *args)
+      end
+
+      # Reads a JSON Topic Maps (JTM) File
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_jtm(filename)
+      #
+      def from_jtm(*args)
+        # seems not to acceped all files that are found to be valid by the JTM validator
+        from_anything(org.tmapix.io.JTMTopicMapReader, *args)
+      end
+
+      # Reads a Friendly Topic Maps XML (TM/XML) File
+      # independent of the version
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_tmxml(filename)
+      #
+      def from_tmxml(*args)
+        from_anything(org.tmapix.io.TMXMLTopicMapReader, *args)
+      end
+
+      # Reads a XML Topic Maps (XTM) 1.0 File
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_xtm10(filename)
+      #
+      def from_xtm10(*args)
+        from_anything(org.tmapix.io.XTM10TopicMapReader, *args)
+      end
+      alias :from_xtm1 :from_xtm10
+
+      # Reads a XML Topic Maps (XTM) 2.0 File
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_xtm20(filename)
+      #
+      def from_xtm20(*args)
+        from_xtm(*args)
+      end
+      alias :from_xtm2 :from_xtm20
+
+      # Reads a XML Topic Maps (XTM) File
+      # independent of the version
+      # whose location is given as String parameter.
+      #
+      # :call-seq:
+      #   from_xtm(filename)
+      #
+      def from_xtm(*args)
+        from_anything(org.tmapix.io.XTMTopicMapReader, *args)
+      end
+
+      # Reads a Notation3 (N3) File
+      # whose location is given as String .
+      # The source vocabulary must
+      # provide the mapping vocabulary.
+      # The syntax of the vocabulary is guessed.
+      #
+      # :call-seq:
+      #   from_n3(filename, source vocabulary)
+      #
+      def from_n3(filename, vocab)
+        raise "Only supported for TMAPI backends!!" unless self.kind_of? Java::OrgTmapiCore::TopicMap
+        reader = org.tmapix.io.N3TopicMapReader.new self,  java.io.File.new(filename)
+        reader.setMappingSource(java.io.File.new(vocab))
+        reader.read
+      end
+
+      # Reads a RDF/XML File
+      # whose location is given as String
+      # The source vocabulary must
+      # provide the mapping vocabulary.
+      # The syntax of the vocabulary is guessed.
+      #
+      # :call-seq:
+      #   from_rdfxml(filename, source vocabulary)
+      #
+      def from_rdfxml(filename, vocab)
+        raise "Only supported for TMAPI backends!!" unless self.kind_of? Java::OrgTmapiCore::TopicMap
+        reader = org.tmapix.io.RDFXMLTopicMapReader.new self,  java.io.File.new(filename)
+        reader.setMappingSource(java.io.File.new(vocab))
+        reader.read
+      end
+    end
+    TopicMapSystem = TopicMap # We want importers for both, TopicMap and TopicMapSystem
+    RTM.register_extension(self)
+  end
+end

data/lib/rtm/io/tmapix_to.rb

@@ -0,0 +1,223 @@
+# Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig.
+# License:   Apache License, Version 2.0
+
+module RTM::IO
+  # Export of TMAPI Topic Maps
+  # Utilizing the TMAPIX libary http://code.google.com/p/tmapix/
+  # Consequently the serializers provided here are only wrappers
+
+  module TmapiXTo
+    module TopicMap
+
+      private
+      # Serializes a Topic Map using the given writer.
+      #
+      # If the optional file is given (using the positional parameter or the :file keys in the params hash),
+      # it is written to that file, otherwise a String will be returned.
+      # The file can be provided as a String (which is then interpreted as a filename) or as a java.io.OutputStream.
+      # E.g. to_anything(my_writer, "/some/file") # writes to the file
+      #      to_anything(my_writer, some_output_stream) # writes to the outputstream
+      # E.g. to_anything(my_writer, :file => "/some/file") # writes to the file
+      #      to_anything(my_writer) # returns a string
+      #
+      # If the optional base_iri is given (using the positional parameter or the :base_iri key in the params hash),
+      # the given base_iri will be used during export. Otherwise the topic maps's base_iri will be used.
+      # E.g. to_anything(my_writer, "/some/file", "http://example.org/something") # uses the base_iri given
+      #      to_anything(my_writer) # uses the base_iri of the topic map
+      #
+      # Please be aware that you cannot leave out the filename positional parameter and just provide the base_iri.
+      # If you want to provide a base_iri but no filename provide +nil+ as filename or use the params hash.
+      # E.g. to_anything(my_writer, nil, my_base_iri)
+      #      to_anything(my_writer, :base_iri => my_base_iri)
+      #
+      # :call-seq:
+      #   to_anything(writer_class, params = {})
+      #   to_anything(writer_class, file, params = {})
+      #   to_anything(writer_class, file, base_iri, params={})
+      #
+      def to_anything(writer_class, *args)
+        raise("Only supported for TMAPI backends.") unless self.kind_of?(Java::OrgTmapiCore::TopicMap)
+        params = {}
+        # See if we got a params hash. It must be at the end, if it is given.
+        # Take it off, so it won't be unshifted later.
+        params = args.pop if args.last.is_a?(Hash)
+
+        # Take the file as next (i.e. second after the writer) positional parameter or from hash.
+        # Leave nil if neither found.
+        file = args.shift || params[:file]
+
+        # Take the base_iri as next (i.e. third after the file) positional parameter or from the hash.
+        # Use the topic maps's base_iri if neither found.
+        base_iri = args.shift || params[:base_iri] || self.base_iri
+
+        # If a file was provided somehow, we wrap it with output streams
+        if file
+          if file.is_a?(java.io.OutputStream)
+            out_stream = file
+          else
+            out_stream = java.io.BufferedOutputStream.new(java.io.FileOutputStream.new(file))
+          end
+        else
+          # if no file was given we want to return a string which will be written into a stream by the writer
+          out_stream = java.io.ByteArrayOutputStream.new
+        end
+
+        # create the java writer
+        writer = writer_class.new(out_stream, base_iri)
+        # set params
+        params.each do |k,v|
+          # skip our params, as they're not of interest for the writer
+          next if k == :file || k == :base_iri
+          writer.setProperty(k.to_s,v.to_s)
+        end if writer.respond_to?(:setProperty)
+        # do the actual work
+        writer.write(self)
+        out_stream.flush
+
+        # close the file unless we were provided with a stream
+        out_stream.close unless file && file.is_a?(java.io.OutputStream)
+
+        # if there was no file, we have a ByteArrayOutputStream. Get the String out of it (and return it)
+        # otherwise, we return true
+        return file ? true : out_stream.to_s
+      end
+
+      public
+      # Serializes an RTM::TopicMap to XTM v. 2.0.
+      #
+      # If no argument is given, a String is returned.
+      #
+      # The argument file can be provided as a String
+      # (which is then interpreted as a filename) or as a java.io.OutputStream.
+      #
+      # The argument base_iri may be used to define a new base_iri, if not, the current
+      # one is used. Base_iri may be a String.
+      #
+      # :call-seq:
+      #   to_xtm20
+      #   to_xtm20(file)
+      #   to_xtm20(file, base_iri)
+      #
+      def to_xtm20(*args)
+        to_anything(org.tmapix.io.XTM20TopicMapWriter, *args)
+      end
+      alias :to_xtm :to_xtm20
+      alias :to_xtm2 :to_xtm20
+
+      # Serializes an RTM::TopicMap to XTM v. 1.0.
+      #
+      # If no argument is given, a String is returned.
+      #
+      # The argument file can be provided as a String
+      # (which is then interpreted as a filename) or as a java.io.OutputStream.
+      #
+      # The argument base_iri may be used to define a new base_iri, if not, the current
+      # one is used. Base_iri may be a String.
+      #
+      # :call-seq:
+      #   to_xtm10
+      #   to_xtm10(file)
+      #   to_xtm10(file, base_iri)
+      #
+      def to_xtm10(*args)
+        to_anything(org.tmapix.io.XTM10TopicMapWriter, *args)
+      end
+      alias :to_xtm1 :to_xtm10
+
+      # Serializes an RTM::TopicMap to JTM.
+      #
+      # If no argument is given, a String is returned.
+      #
+      # The argument file can be provided as a String
+      # (which is then interpreted as a filename) or as a java.io.OutputStream.
+      #
+      # The argument base_iri may be used to define a new base_iri, if not, the current
+      # one is used. Base_iri may be a String.
+      #
+      # :call-seq:
+      #   to_jtm
+      #   to_jtm(file)
+      #   to_jtm(file, base_iri)
+      #
+      def to_jtm(*args)
+        to_anything(org.tmapix.io.JTMTopicMapWriter, *args)
+      end
+      alias :to_json :to_jtm
+
+      # Serializes an RTM::TopicMap to LTM.
+      #
+      # If no argument is given, a String is returned.
+      #
+      # The argument file can be provided as a String
+      # (which is then interpreted as a filename) or as a java.io.OutputStream.
+      #
+      # The argument base_iri may be used to define a new base_iri, if not, the current
+      # one is used. Base_iri may be a String.
+      #
+      # :call-seq:
+      #   to_ltm
+      #   to_ltm(file)
+      #   to_ltm(file, base_iri)
+      #
+      def to_ltm(*args)
+        to_anything(org.tmapix.io.LTMTopicMapWriter, *args)
+      end
+
+      # Serializes an RTM::TopicMap to TM/XML.
+      #
+      # If no argument is given, a String is returned.
+      #
+      # The argument file can be provided as a String
+      # (which is then interpreted as a filename) or as a java.io.OutputStream.
+      #
+      # The argument base_iri may be used to define a new base_iri, if not, the current
+      # one is used. Base_iri may be a String.
+      #
+      # :call-seq:
+      #   to_tmxml
+      #   to_tmxml(file)
+      #   to_tmxml(file, base_iri)
+      #
+      def to_tmxml(*args)
+        to_anything(org.tmapix.io.TMXMLTopicMapWriter, *args)
+      end
+
+      # Serializes an RTM::TopicMap to CTM.
+      #
+      # If no argument is given, a String is returned.
+      #
+      # The argument file can be provided as a String
+      # (which is then interpreted as a filename) or as a java.io.OutputStream.
+      # 
+      # The argument base_iri may be used to define a new base_iri, if not, the current
+      # one is used. Base_iri may be a String.
+      #
+      # A property-Hash may be given to set properties of the writer.
+      #
+      # :call-seq:
+      #   to_ctm(properties={})
+      #   to_ctm(file, properties={})
+      #   to_ctm(file, base_iri, properties={})
+      #
+      def to_ctm(*args)
+        # set default params
+        default_params = {
+          "writer.features.export.itemidentifier" => false,
+          "writer.features.prefixDetection.enabled" => false,
+          "writer.features.templateDetection.enabled" => false,
+          "writer.features.templateDetection.topicTemplates" => false,
+          "writer.features.templateDetection.associationTemplates" => false,
+          "writer.features.templateMerger.enabled" => false
+        }
+        # enhance the args with the default params
+        if args.last.is_a?(Hash)
+          args.push(default_params.merge(args.pop))
+        else
+          args.push(default_params)
+        end
+        to_anything(de.topicmapslab.ctm.writer.core.CTMTopicMapWriter, *args)
+      end
+    end
+    RTM.register_extension(self)
+  end
+end

data/lib/rtm/io/to_hash.rb

@@ -2,25 +2,39 @@
 # License:   Apache License, Version 2.0
 
 module RTM::IO
-  # HASH Export.
+  # Hash Export.
   # Each Topic Maps Construct gets a to_hash method.
-  module TOHASH
+  module ToHash
 
     module TopicMap
-      # Returns the Hash representation of this RTM::TopicMap
+      # Returns the Hash representation of this topic map.
+      #
+      # The returned Hash holds information about the :reifier,
+      # the :item_identifiers, the :topics and :associations.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
       def to_hash
         h={}
-        h[:reifier] = reifier.to_ref if reifier
+        h[:reifier] = reifier.reference if reifier
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
         h[:topics] = topics.map{|i| i.to_hash} unless topics.empty?
         h[:associations] = associations.map{|i| i.to_hash} unless associations.empty?
         h
       end
     end
-    
-    
+       
     module Topic
-      # Returns the Hash representation of this RTM::Topic
+      # Returns the Hash representation of this topic.
+      #
+      # The returned Hash holds information about the :subject_identifiers,
+      # the :item_identifiers, the :subject_locators, the :names and the
+      # :occurrences.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
       def to_hash
         h = {}
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
@@ -30,87 +44,111 @@ module RTM::IO
         h[:occurrences] = occurrences.map{|i| i.to_hash} unless occurrences.empty?
         h
       end
-      # Returns the reference to the Topic
-      def to_ref
-        if subject_identifiers.first
-          return "si:#{subject_identifiers.first.reference.to_s}"
-        end
-        if item_identifiers.first
-          return "ii:#{item_identifiers.first.reference.to_s}"
-        end
-        # "t#{id}"
-      end
     end
 
     module Name
-      # Returns the Hash representation of this RTM::Name
+      # Returns the Hash representation of this name.
+      #
+      # The returned Hash holds information about the :reifier,
+      # the :item_identifiers, the :value, the :type, the :scope and the
+      # :variants.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
       def to_hash
         h={}
-        h[:reifier] = reifier.to_ref if reifier
+        h[:reifier] = reifier.reference if reifier
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
         h[:value] = value if value
-        h[:type] = type.to_ref if type
-        h[:scope] = scope.map{|i| i.to_ref} unless scope.empty?
+        h[:type] = type.reference if type
+        h[:scope] = scope.map{|i| i.reference} unless scope.empty?
         h[:variants] = variants.map{|i| i.to_hash} unless variants.empty?
         h
       end
     end
     
-    
     module Association
-      # Returns the Hash representation of this RTM::Association
+      # Returns the Hash representation of this association.
+      #
+      # The returned Hash holds information about the :reifier,
+      # the :item_identifiers, the :type, the :scope and the :roles.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
       def to_hash
         h={}
-        h[:reifier] = reifier.to_ref if reifier
+        h[:reifier] = reifier.reference if reifier
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
-        h[:type] = type.to_ref if type
-        h[:scope] = scope.map{|i| i.to_ref} unless scope.empty?
+        h[:type] = type.reference if type
+        h[:scope] = scope.map{|i| i.reference} unless scope.empty?
         h[:roles] = roles.map{|i| i.to_hash} unless roles.empty?
         h
       end  
     end
     
-    
-    
     module Occurrence
-      # Returns the Hash representation of this RTM::Occurrence
+      # Returns the Hash representation of this occurrence.
+      #
+      # The returned Hash holds information about the :reifier,
+      # the :item_identifiers, the :value, the :datatype, the :type
+      # and the :scope.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
       def to_hash
         h={}
-        h[:reifier] = reifier.to_ref if reifier
+        h[:reifier] = reifier.reference if reifier
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
         h[:value] = value if value
         h[:datatype] = datatype.reference if datatype
-        h[:type] = type.to_ref if type
-        h[:scope] = scope.map{|i| i.to_ref} unless scope.empty?
+        h[:type] = type.reference if type
+        h[:scope] = scope.map{|i| i.reference} unless scope.empty?
         h
       end
     end
 
     module Role
-      # Returns the Hash representation of this RTM::Role
+      # Returns the Hash representation of this role.
+      #
+      # The returned Hash holds information about the :reifier,
+      # the :item_identifiers, the :player, and the :type.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
       def to_hash
         h={}
-        h[:reifier] = reifier.to_ref if reifier
+        h[:reifier] = reifier.reference if reifier
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
-        h[:player] = player.to_ref if player
-        h[:type] = type.to_ref if type
+        h[:player] = player.reference if player
+        h[:type] = type.reference if type
         h
       end
     end
 
     module Variant
-      # Returns the Hash representation of this RTM::Variant
-      def to_hash(*a)
+      # Returns the Hash representation of this variant.
+      #
+      # The returned Hash holds information about the :reifier,
+      # the :item_identifiers, the :value and the :scope.
+      #
+      # :call-seq:
+      #   to_hash -> Hash
+      #
+      def to_hash
         h={}
-        h[:reifier] = reifier.to_ref if reifier
+        h[:reifier] = reifier.reference if reifier
         h[:item_identifiers] = item_identifiers.map{|i| i.reference} unless item_identifiers.empty?
         h[:value] = value if value
-        h[:scope] = scope.map{|i| i.to_ref} unless scope.empty?
+        h[:scope] = scope.map{|i| i.reference} unless scope.empty?
         h
       end
     end
     
-    RTM.register_extension self 
+    RTM.register_extension self
   
   end  
 end