openlogic-rdf 0.3.6

data/lib/rdf/nquads.rb

@@ -0,0 +1,152 @@
+module RDF
+  ##
+  # **`RDF::NQuads`** provides support for the N-Quads serialization format.
+  #
+  # This has not yet been implemented as of RDF.rb 0.3.x.
+  module NQuads
+    include NTriples
+
+    ##
+    # N-Quads format specification.
+    #
+    # @example Obtaining an NQuads format class
+    #   RDF::Format.for(:nquads)     #=> RDF::NQuads::Format
+    #   RDF::Format.for("etc/doap.nq")
+    #   RDF::Format.for(:file_name      => "etc/doap.nq")
+    #   RDF::Format.for(:file_extension => "nq")
+    #   RDF::Format.for(:content_type   => "text/x-nquads")
+    #
+    # @see http://sw.deri.org/2008/07/n-quads/#mediatype
+    # @since  0.4.0
+    class Format < RDF::Format
+      content_type     'text/x-nquads', :extension => :nq
+      content_encoding 'utf-8'
+
+      reader { RDF::NQuads::Reader }
+      writer { RDF::NQuads::Writer }
+    
+      ##
+      # Sample detection to see if it matches N-Quads (or N-Triples)
+      #
+      # Use a text sample to detect the format of an input file. Sub-classes implement
+      # a matcher sufficient to detect probably format matches, including disambiguating
+      # between other similar formats.
+      #
+      # @param [String] sample Beginning several bytes (about 1K) of input.
+      # @return [Boolean]
+      def self.detect(sample)
+        !!sample.match(%r(
+          (?:\s*(?:<[^>]*>) | (?:_:\w+))                          # Subject
+          (?:\s*<[^>]*>)                                          # Predicate
+          \s*
+          (?:(?:<[^>]*>) | (?:_:\w+) | (?:"[^"\n]*"(?:^^|@\S+)?)) # Object
+          (?:\s*<[^>]*>)                                          # Context
+          \s*\.
+        )mx) && !(
+          sample.match(%r(@(base|prefix|keywords)|\{)) ||         # Not Turtle/N3/TriG
+          sample.match(%r(<(html|rdf))i)                          # Not HTML or XML
+        )
+      end
+    end
+
+    class Reader < NTriples::Reader
+      ##
+      # @param  [String] input
+      # @return [RDF::Term]
+      # @since  0.4.0
+      def self.parse_context(input)
+        parse_uri(input) || parse_node(input) || parse_literal(input)
+      end
+
+      ##
+      # Read a Quad, where the context is optional
+      #
+      # @return [Array]
+      # @see    http://sw.deri.org/2008/07/n-quads/#grammar
+      # @since  0.4.0
+      def read_triple
+        loop do
+          readline.strip! # EOFError thrown on end of input
+          line = @line    # for backtracking input in case of parse error
+
+          begin
+            unless blank? || read_comment
+              subject   = read_uriref || read_node || fail_subject
+              predicate = read_uriref(:intern => true) || fail_predicate
+              object    = read_uriref || read_node || read_literal || fail_object
+              context    = read_uriref || read_node || read_literal
+              return [subject, predicate, object, {:context => context}]
+            end
+          rescue RDF::ReaderError => e
+            @line = line  # this allows #read_value to work
+            raise e
+          end
+        end
+      end
+
+    end # Reader
+
+    class Writer < NTriples::Writer
+      ##
+      # @param  [RDF::Statement] statement
+      # @return [void] `self`
+      def write_statement(statement)
+        write_quad(*statement.to_quad)
+        self
+      end
+      alias_method :insert_statement, :write_statement # support the RDF::Writable interface
+
+      ##
+      # Outputs the N-Quads representation of a statement.
+      #
+      # @param  [RDF::Resource] subject
+      # @param  [RDF::URI]      predicate
+      # @param  [RDF::Term]     object
+      # @return [void]
+      def write_quad(subject, predicate, object, context)
+        puts format_quad(subject, predicate, object, context)
+      end
+
+      ##
+      # Returns the N-Quads representation of a statement.
+      #
+      # @param  [RDF::Statement] statement
+      # @return [String]
+      # @since  0.4.0
+      def format_statement(statement)
+        format_quad(*statement.to_quad)
+      end
+
+      ##
+      # Returns the N-Triples representation of a triple.
+      #
+      # @param  [RDF::Resource] subject
+      # @param  [RDF::URI]      predicate
+      # @param  [RDF::Term]     object
+      # @param  [RDF::Term]     context
+      # @return [String]
+      def format_quad(subject, predicate, object, context)
+        s = "%s %s %s " % [subject, predicate, object].map { |value| format_term(value) }
+        s += format_term(context) + " " if context
+        s + "."
+      end
+    end # Writer
+  end # NQuads
+
+
+  ##
+  # Extensions for `RDF::Value`.
+  module Value
+    ##
+    # Returns the N-Triples representation of this value.
+    #
+    # This method is only available when the 'rdf/ntriples' serializer has
+    # been explicitly required.
+    #
+    # @return [String]
+    # @since  0.4.0
+    def to_quad
+      RDF::NQuads.serialize(self)
+    end
+  end # Value
+end # RDF

data/lib/rdf/ntriples/format.rb

@@ -0,0 +1,48 @@
+module RDF::NTriples
+  ##
+  # N-Triples format specification.
+  #
+  # Note: Latest standards activities treat N-Triples as a subset
+  # of Turtle. This includes text/ntriples+turtle mime type and a
+  # new default encoding of utf-8.
+  #
+  # @example Obtaining an NTriples format class
+  #   RDF::Format.for(:ntriples)     #=> RDF::NTriples::Format
+  #   RDF::Format.for("etc/doap.nt")
+  #   RDF::Format.for(:file_name      => "etc/doap.nt")
+  #   RDF::Format.for(:file_extension => "nt")
+  #   RDF::Format.for(:content_type   => "text/plain")
+  #   RDF::Format.for(:content_type   => "text/ntriples+turtle")
+  #
+  # @see http://www.w3.org/TR/rdf-testcases/#ntriples
+  class Format < RDF::Format
+    content_type     'text/plain', :extension => :nt, :alias => 'text/ntriples+turtle'
+    content_encoding 'utf-8'
+
+    reader { RDF::NTriples::Reader }
+    writer { RDF::NTriples::Writer }
+    
+    ##
+    # Sample detection to see if it matches N-Triples
+    #
+    # Use a text sample to detect the format of an input file. Sub-classes implement
+    # a matcher sufficient to detect probably format matches, including disambiguating
+    # between other similar formats.
+    #
+    # @param [String] sample Beginning several bytes (about 1K) of input.
+    # @return [Boolean]
+    def self.detect(sample)
+      !!sample.match(%r(
+        (?:(?:<[^>]*>) | (?:_:\w+))                             # Subject
+        \s*
+        (?:<[^>]*>)                                             # Predicate
+        \s*
+        (?:(?:<[^>]*>) | (?:_:\w+) | (?:"[^"\n]*"(?:^^|@\S+)?)) # Object
+        \s*\.
+      )mx) && !(
+        sample.match(%r(@(base|prefix|keywords)|\{)) ||         # Not Turtle/N3/TriG
+        sample.match(%r(<(html|rdf))i)                          # Not HTML or XML
+      ) && !RDF::NQuads::Format.detect(sample)
+    end
+  end
+end

data/lib/rdf/ntriples/reader.rb

@@ -0,0 +1,239 @@
+module RDF::NTriples
+  ##
+  # N-Triples parser.
+  #
+  # @example Obtaining an NTriples reader class
+  #   RDF::Reader.for(:ntriples)     #=> RDF::NTriples::Reader
+  #   RDF::Reader.for("etc/doap.nt")
+  #   RDF::Reader.for(:file_name      => "etc/doap.nt")
+  #   RDF::Reader.for(:file_extension => "nt")
+  #   RDF::Reader.for(:content_type   => "text/plain")
+  #
+  # @example Parsing RDF statements from an NTriples file
+  #   RDF::NTriples::Reader.open("etc/doap.nt") do |reader|
+  #     reader.each_statement do |statement|
+  #       puts statement.inspect
+  #     end
+  #   end
+  #
+  # @example Parsing RDF statements from an NTriples string
+  #   data = StringIO.new(File.read("etc/doap.nt"))
+  #   RDF::NTriples::Reader.new(data) do |reader|
+  #     reader.each_statement do |statement|
+  #       puts statement.inspect
+  #     end
+  #   end
+  #
+  # @see http://www.w3.org/TR/rdf-testcases/#ntriples
+  class Reader < RDF::Reader
+    format RDF::NTriples::Format
+
+    # @see http://www.w3.org/TR/rdf-testcases/#ntrip_grammar
+    COMMENT               = /^#\s*(.*)$/.freeze
+    NODEID                = /^_:([A-Za-z][A-Za-z0-9\-_]*)/.freeze
+    URIREF                = /^<([^>]+)>/.freeze
+    LITERAL_PLAIN         = /^"((?:\\"|[^"])*)"/.freeze
+    LITERAL_WITH_LANGUAGE = /^"((?:\\"|[^"])*)"@([a-z]+[\-A-Za-z0-9]*)/.freeze
+    LITERAL_WITH_DATATYPE = /^"((?:\\"|[^"])*)"\^\^<([^>]+)>/.freeze
+    LANGUAGE_TAG          = /^@([a-z]+[\-A-Za-z0-9]*)/.freeze
+    DATATYPE_URI          = /^\^\^<([^>]+)>/.freeze
+    LITERAL               = Regexp.union(LITERAL_WITH_LANGUAGE, LITERAL_WITH_DATATYPE, LITERAL_PLAIN).freeze
+    SUBJECT               = Regexp.union(URIREF, NODEID).freeze
+    PREDICATE             = Regexp.union(URIREF).freeze
+    OBJECT                = Regexp.union(URIREF, NODEID, LITERAL).freeze
+
+    # @see http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    ESCAPE_CHARS          = ["\t", "\n", "\r", "\"", "\\"].freeze
+    ESCAPE_CHAR4          = /\\u([0-9A-Fa-f]{4,4})/.freeze
+    ESCAPE_CHAR8          = /\\U([0-9A-Fa-f]{8,8})/.freeze
+    ESCAPE_CHAR           = Regexp.union(ESCAPE_CHAR4, ESCAPE_CHAR8).freeze
+    ESCAPE_SURROGATE      = /\\u([0-9A-Fa-f]{4,4})\\u([0-9A-Fa-f]{4,4})/.freeze
+    ESCAPE_SURROGATE1     = (0xD800..0xDBFF).freeze
+    ESCAPE_SURROGATE2     = (0xDC00..0xDFFF).freeze
+
+    ##
+    # Reconstructs an RDF value from its serialized N-Triples
+    # representation.
+    #
+    # @param  [String] input
+    # @return [RDF::Term]
+    def self.unserialize(input)
+      case input
+        when nil then nil
+        else self.new(input).read_value
+      end
+    end
+
+    ##
+    # @param  [String] input
+    # @return [RDF::Resource]
+    def self.parse_subject(input)
+      parse_uri(input) || parse_node(input)
+    end
+
+    ##
+    # @param  [String] input
+    # @return [RDF::URI]
+    def self.parse_predicate(input)
+      parse_uri(input, :intern => true)
+    end
+
+    ##
+    # @param  [String] input
+    # @return [RDF::Term]
+    def self.parse_object(input)
+      parse_uri(input) || parse_node(input) || parse_literal(input)
+    end
+
+    ##
+    # @param  [String] input
+    # @return [RDF::Node]
+    def self.parse_node(input)
+      if input =~ NODEID
+        RDF::Node.new($1)
+      end
+    end
+
+    ##
+    # @param  [String] input
+    # @return [RDF::URI]
+    def self.parse_uri(input, options = {})
+      if input =~ URIREF
+        RDF::URI.send(options[:intern] ? :intern : :new, $1)
+      end
+    end
+
+    ##
+    # @param  [String] input
+    # @return [RDF::Literal]
+    def self.parse_literal(input)
+      case input
+        when LITERAL_WITH_LANGUAGE
+          RDF::Literal.new(unescape($1), :language => $2)
+        when LITERAL_WITH_DATATYPE
+          RDF::Literal.new(unescape($1), :datatype => $2)
+        when LITERAL_PLAIN
+          RDF::Literal.new(unescape($1))
+      end
+    end
+
+    ##
+    # @param  [String] string
+    # @return [String]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    # @see    http://blog.grayproductions.net/articles/understanding_m17n
+    # @see    http://yehudakatz.com/2010/05/17/encodings-unabridged/
+    def self.unescape(string)
+      string.force_encoding(Encoding::ASCII_8BIT) if string.respond_to?(:force_encoding)
+
+      # Decode \t|\n|\r|\"|\\ character escapes:
+      ESCAPE_CHARS.each { |escape| string.gsub!(escape.inspect[1...-1], escape) }
+
+      # Decode \uXXXX\uXXXX surrogate pairs:
+      while
+        (string.sub!(ESCAPE_SURROGATE) do
+          if ESCAPE_SURROGATE1.include?($1.hex) && ESCAPE_SURROGATE2.include?($2.hex)
+            s = [$1, $2].pack('H*H*')
+            s = s.respond_to?(:force_encoding) ?
+              s.force_encoding(Encoding::UTF_16BE).encode!(Encoding::UTF_8) : # for Ruby 1.9+
+              Iconv.conv('UTF-8', 'UTF-16BE', s)                              # for Ruby 1.8.x
+          else
+            s = [$1.hex].pack('U*') << '\u' << $2
+          end
+          s.respond_to?(:force_encoding) ? s.force_encoding(Encoding::ASCII_8BIT) : s
+        end)
+      end
+
+      # Decode \uXXXX and \UXXXXXXXX code points:
+      string.gsub!(ESCAPE_CHAR) do
+        s = [($1 || $2).hex].pack('U*')
+        s.respond_to?(:force_encoding) ? s.force_encoding(Encoding::ASCII_8BIT) : s
+      end
+
+      string.force_encoding(Encoding::UTF_8) if string.respond_to?(:force_encoding)
+      string
+    end
+
+    ##
+    # @return [RDF::Term]
+    def read_value
+      begin
+        read_statement
+      rescue RDF::ReaderError => e
+        read_uriref || read_node || read_literal
+      end
+    end
+
+    ##
+    # @return [Array]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar
+    def read_triple
+      loop do
+        readline.strip! # EOFError thrown on end of input
+        line = @line    # for backtracking input in case of parse error
+
+        begin
+          unless blank? || read_comment
+            subject   = read_uriref || read_node || fail_subject
+            predicate = read_uriref(:intern => true) || fail_predicate
+            object    = read_uriref || read_node || read_literal || fail_object
+            return [subject, predicate, object]
+          end
+        rescue RDF::ReaderError => e
+          @line = line  # this allows #read_value to work
+          raise e
+        end
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (comment)
+    def read_comment
+      match(COMMENT)
+    end
+
+    ##
+    # @return [RDF::URI]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (uriref)
+    def read_uriref(options = {})
+      if uri_str = match(URIREF)
+        uri_str = self.class.unescape(uri_str)
+        uri = RDF::URI.send(intern? && options[:intern] ? :intern : :new, uri_str)
+        uri.validate!     if validate?
+        uri.canonicalize! if canonicalize?
+        uri
+      end
+    end
+
+    ##
+    # @return [RDF::Node]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (nodeID)
+    def read_node
+      if node_id = match(NODEID)
+        @nodes ||= {}
+        @nodes[node_id] ||= RDF::Node.new(node_id)
+      end
+    end
+
+    ##
+    # @return [RDF::Literal]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (literal)
+    def read_literal
+      if literal_str = match(LITERAL_PLAIN)
+        literal_str = self.class.unescape(literal_str)
+        literal = case
+          when language = match(LANGUAGE_TAG)
+            RDF::Literal.new(literal_str, :language => language)
+          when datatype = match(/^(\^\^)/) # FIXME
+            RDF::Literal.new(literal_str, :datatype => read_uriref || fail_object)
+          else
+            RDF::Literal.new(literal_str) # plain string literal
+        end
+        literal.validate!     if validate?
+        literal.canonicalize! if canonicalize?
+        literal
+      end
+    end
+  end # Reader
+end # RDF::NTriples

data/lib/rdf/ntriples/writer.rb

@@ -0,0 +1,219 @@
+module RDF::NTriples
+  ##
+  # N-Triples serializer.
+  #
+  # @example Obtaining an NTriples writer class
+  #   RDF::Writer.for(:ntriples)     #=> RDF::NTriples::Writer
+  #   RDF::Writer.for("etc/test.nt")
+  #   RDF::Writer.for(:file_name      => "etc/test.nt")
+  #   RDF::Writer.for(:file_extension => "nt")
+  #   RDF::Writer.for(:content_type   => "text/plain")
+  #
+  # @example Serializing RDF statements into an NTriples file
+  #   RDF::NTriples::Writer.open("etc/test.nt") do |writer|
+  #     graph.each_statement do |statement|
+  #       writer << statement
+  #     end
+  #   end
+  #
+  # @example Serializing RDF statements into an NTriples string
+  #   RDF::NTriples::Writer.buffer do |writer|
+  #     graph.each_statement do |statement|
+  #       writer << statement
+  #     end
+  #   end
+  #
+  # @see http://www.w3.org/TR/rdf-testcases/#ntriples
+  class Writer < RDF::Writer
+    format RDF::NTriples::Format
+
+    # @see http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    ESCAPE_PLAIN = /\A[\x20-\x21\x23-\x5B\x5D-\x7E]*\z/m.freeze
+    ESCAPE_ASCII = /\A[\x00-\x7F]*\z/m.freeze
+
+    ##
+    # @param  [String] string
+    # @return [String]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    def self.escape(string)
+      case
+        when string =~ ESCAPE_PLAIN # a shortcut for the simple case
+          string
+        when string.respond_to?(:ascii_only?) && string.ascii_only?
+          StringIO.open do |buffer|
+            string.each_byte { |u| buffer << escape_ascii(u) }
+            buffer.string
+          end
+        when string.respond_to?(:each_codepoint)
+          StringIO.open do |buffer|
+            string.each_codepoint { |u| buffer << escape_unicode(u) }
+            buffer.string
+          end
+        else # works in Ruby 1.8.x, too
+          StringIO.open do |buffer|
+            string.scan(/./mu) { |c| buffer << escape_unicode(u = c.unpack('U*').first) }
+            buffer.string
+          end
+      end
+    end
+
+    ##
+    # @param  [Integer, #ord] u
+    # @return [String]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    def self.escape_unicode(u)
+      case (u = u.ord)
+        when (0x00..0x7F)        # ASCII 7-bit
+          escape_ascii(u)
+        when (0x80..0xFFFF)      # Unicode BMP
+          escape_utf16(u)
+        when (0x10000..0x10FFFF) # Unicode
+          escape_utf32(u)
+        else
+          raise ArgumentError.new("expected a Unicode codepoint in (0x00..0x10FFFF), but got 0x#{u.to_s(16)}")
+      end
+    end
+
+    ##
+    # @param  [Integer, #ord] u
+    # @return [String]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    def self.escape_ascii(u)
+      case (u = u.ord)
+        when (0x00..0x08) then escape_utf16(u)
+        when (0x09)       then "\\t"
+        when (0x0A)       then "\\n"
+        when (0x0B..0x0C) then escape_utf16(u)
+        when (0x0D)       then "\\r"
+        when (0x0E..0x1F) then escape_utf16(u)
+        when (0x22)       then "\\\""
+        when (0x5C)       then "\\\\"
+        when (0x7F)       then escape_utf16(u)
+        when (0x00..0x7F) then u.chr
+        else
+          raise ArgumentError.new("expected an ASCII character in (0x00..0x7F), but got 0x#{u.to_s(16)}")
+      end
+    end
+
+    ##
+    # @param  [Integer, #ord] u
+    # @return [String]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    def self.escape_utf16(u)
+      sprintf("\\u%04X", u.ord)
+    end
+
+    ##
+    # @param  [Integer, #ord] u
+    # @return [String]
+    # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_strings
+    def self.escape_utf32(u)
+      sprintf("\\U%08X", u.ord)
+    end
+
+    ##
+    # Returns the serialized N-Triples representation of the given RDF
+    # value.
+    #
+    # @param  [RDF::Value] value
+    # @return [String]
+    # @raise  [ArgumentError] if `value` is not an `RDF::Statement` or `RDF::Term`
+    def self.serialize(value)
+      writer = self.new
+      case value
+        when nil then nil
+        when FalseClass then value.to_s
+        when RDF::Statement
+          writer.format_statement(value) + "\n"
+        when RDF::Term
+          writer.format_term(value)
+        else
+          raise ArgumentError, "expected an RDF::Statement or RDF::Term, but got #{value.inspect}"
+      end
+    end
+
+    ##
+    # Outputs an N-Triples comment line.
+    #
+    # @param  [String] text
+    # @return [void]
+    def write_comment(text)
+      puts "# #{text.chomp}" # TODO: correctly output multi-line comments
+    end
+
+    ##
+    # Outputs the N-Triples representation of a triple.
+    #
+    # @param  [RDF::Resource] subject
+    # @param  [RDF::URI]      predicate
+    # @param  [RDF::Term]     object
+    # @return [void]
+    def write_triple(subject, predicate, object)
+      puts format_triple(subject, predicate, object)
+    end
+
+    ##
+    # Returns the N-Triples representation of a statement.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [String]
+    def format_statement(statement)
+      format_triple(*statement.to_triple)
+    end
+
+    ##
+    # Returns the N-Triples representation of a triple.
+    #
+    # @param  [RDF::Resource] subject
+    # @param  [RDF::URI]      predicate
+    # @param  [RDF::Term]     object
+    # @return [String]
+    def format_triple(subject, predicate, object)
+      "%s %s %s ." % [subject, predicate, object].map { |value| format_term(value) }
+    end
+
+    ##
+    # Returns the N-Triples representation of a blank node.
+    #
+    # @param  [RDF::Node] node
+    # @param  [Hash{Symbol => Object}] options
+    # @return [String]
+    def format_node(node, options = {})
+      "_:%s" % node.id
+    end
+
+    ##
+    # Returns the N-Triples representation of a URI reference.
+    #
+    # @param  [RDF::URI] literal
+    # @param  [Hash{Symbol => Object}] options
+    # @return [String]
+    def format_uri(uri, options = {})
+      "<%s>" % escaped(uri_for(uri))
+    end
+
+    ##
+    # Returns the N-Triples representation of a literal.
+    #
+    # @param  [RDF::Literal, String, #to_s] literal
+    # @param  [Hash{Symbol => Object}] options
+    # @return [String]
+    def format_literal(literal, options = {})
+      case literal
+        when RDF::Literal
+          text = quoted(escaped(literal.value))
+          text << "@#{literal.language}" if literal.has_language?
+          text << "^^<#{uri_for(literal.datatype)}>" if literal.has_datatype?
+          text
+        else
+          quoted(escaped(literal.to_s))
+      end
+    end
+
+    ##
+    # @private
+    def escaped(string)
+      self.class.escape(string)
+    end
+  end
+end