rdf 0.2.3 → 0.3.0.pre

data/lib/rdf/model/uri.rb

@@ -43,7 +43,7 @@ module RDF
     # The maximum number of cached interned URI references is given by the
     # `CACHE_SIZE` constant. This value is unlimited by default, in which
     # case an interned URI object will be purged only when the last strong
-    # reference to it is garbage collection (i.e., when its finalizer runs).
+    # reference to it is garbage collected (i.e., when its finalizer runs).
     #
     # Excepting special memory-limited circumstances, it should always be
     # safe and preferred to construct new URI references using
@@ -52,9 +52,9 @@ module RDF
     # to returning a freshly-allocated one.
     #
     # @param  [String, #to_s] str
-    # @return [RDF::URI]
+    # @return [RDF::URI] an immutable, frozen URI object
     def self.intern(str)
-      cache[str = str.to_s] ||= self.new(str)
+      (cache[str = str.to_s] ||= self.new(str)).freeze
     end
 
     ##
@@ -71,7 +71,7 @@ module RDF
 
     ##
     # @overload URI.new(uri)
-    #   @param  [URI, String, #to_s]    uri
+    #   @param  [RDF::URI, String, #to_s] uri
     #
     # @overload URI.new(options = {})
     #   @param  [Hash{Symbol => Object} options
@@ -89,7 +89,7 @@ module RDF
     ##
     # Returns `false`.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     def anonymous?
       false
     end
@@ -97,7 +97,7 @@ module RDF
     ##
     # Returns `true`.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     # @see    http://en.wikipedia.org/wiki/Uniform_Resource_Identifier
     def uri?
       true
@@ -106,41 +106,198 @@ module RDF
     ##
     # Returns `true` if this URI is a URN.
     #
-    # @return [Boolean]
+    # @example
+    #   RDF::URI('http://example.org/').urn?                    #=> false
+    #
+    # @return [Boolean] `true` or `false`
     # @see    http://en.wikipedia.org/wiki/Uniform_Resource_Name
     # @since  0.2.0
     def urn?
-      to_s.index('urn:') == 0
+      self.start_with?('urn:')
     end
 
     ##
     # Returns `true` if this URI is a URL.
     #
-    # @return [Boolean]
+    # @example
+    #   RDF::URI('http://example.org/').url?                    #=> true
+    #
+    # @return [Boolean] `true` or `false`
     # @see    http://en.wikipedia.org/wiki/Uniform_Resource_Locator
     # @since  0.2.0
     def url?
       !urn?
     end
 
+    ##
+    # Returns the string length of this URI.
+    #
+    # @example
+    #   RDF::URI('http://example.org/').length                  #=> 19
+    #
+    # @return [Integer]
+    # @since  0.3.0
+    def length
+      to_s.length
+    end
+    alias_method :size, :length
+
+    ##
+    # Validates this URI, raising an error if it is invalid.
+    #
+    # @return [RDF::URI] `self`
+    # @raise  [ArgumentError] if the URI is invalid
+    # @since  0.3.0
+    def validate!
+      # TODO: raise error if the URI fails validation
+      self
+    end
+    alias_method :validate, :validate!
+
+    ##
+    # Returns a copy of this URI converted into its canonical lexical
+    # representation.
+    #
+    # @return [RDF::URI]
+    # @since  0.3.0
+    def canonicalize
+      self.dup.canonicalize!
+    end
+
+    ##
+    # Converts this URI into its canonical lexical representation.
+    #
+    # @return [RDF::URI] `self`
+    # @since  0.3.0
+    def canonicalize!
+      # TODO: canonicalize this URI
+      self
+    end
+
     ##
     # Joins several URIs together.
     #
-    # @param  [Array<String, URI, #to_str>] uris
-    # @return [URI]
+    # This method conforms to join normalization semantics as per RFC3986,
+    # section 5.2.  This method normalizes URIs, removes some duplicate path
+    # information, such as double slashes, and other behavior specified in the
+    # RFC.
+    #
+    # Other URI building methods are `#/` and `#+`.
+    #
+    # For an up-to-date list of edge case behavior, see the shared examples for
+    # RDF::URI in the rdf-spec project.
+    #
+    # @example Joining two URIs
+    #     RDF::URI.new('http://example.org/foo/bar').join('/foo')
+    #     #=> RDF::URI('http://example.org/foo')
+    # @see <http://github.com/bendiken/rdf-spec/blob/master/lib/rdf/spec/uri.rb>
+    # @see <http://tools.ietf.org/html/rfc3986#section-5.2>
+    # @see RDF::URI#/
+    # @see RDF::URI#+
+    # @param  [Array<String, RDF::URI, #to_s>] uris
+    # @return [RDF::URI]
     def join(*uris)
-      result = @uri
+      result = @uri.dup
       uris.each do |uri|
-        result.path += '/' unless result.path[-1] == ?/ # '/'
         result = result.join(uri)
       end
       self.class.new(result)
     end
 
+    ##
+    # 'Smart separator' URI builder
+    #
+    # This method attempts to use some understanding of the most common use
+    # cases for URLs and URNs to create a simple method for building new URIs
+    # from fragments.  This means that it will always insert a separator of
+    # some sort, will remove duplicate seperators, will always assume that a
+    # fragment argument represents a relative and not absolute path, and throws
+    # an exception when an absolute URI is received for a fragment argument.
+    #
+    # This is separate from the semantics for `#join`, which are well-defined by
+    # RFC3986 section 5.2 as part of the merging and normalization process;
+    # this method does not perform any normalization, removal of spurious
+    # paths, or removal of parent directory references `(/../)`.
+    #
+    # See also `#+`, which concatenates the string forms of two URIs without
+    # any sort of checking or processing.
+    #
+    # For an up-to-date list of edge case behavior, see the shared examples for
+    # RDF::URI in the rdf-spec project.
+    #
+    # @param [Any] fragment A URI fragment to be appended to this URI
+    # @return [RDF::URI]
+    # @see RDF::URI#+
+    # @see RDF::URI#join
+    # @see <http://tools.ietf.org/html/rfc3986#section-5.2>
+    # @see <http://github.com/bendiken/rdf-spec/blob/master/lib/rdf/spec/uri.rb>
+    # @example Building a HTTP URL
+    #     RDF::URI.new('http://example.org') / 'jhacker' / 'foaf.ttl'
+    #     #=> RDF::URI('http://example.org/jhacker/foaf.ttl')
+    # @example Building a HTTP URL
+    #     RDF::URI.new('http://example.org/') / '/jhacker/' / '/foaf.ttl'
+    #     #=> RDF::URI('http://example.org/jhacker/foaf.ttl')
+    # @example Using an anchored base URI
+    #     RDF::URI.new('http://example.org/users#') / 'jhacker'
+    #     #=> RDF::URI('http://example.org/users#jhacker')
+    # @example Building a URN
+    #     RDF::URI.new('urn:isbn') / 125235111
+    #     #=> RDF::URI('urn:isbn:125235111')
+    def /(fragment)
+      fragment = fragment.respond_to?(:to_uri) ? fragment.to_uri : RDF::URI.intern(fragment.to_s)
+      raise ArgumentError, "Non-absolute URI or string required, got #{fragment}" unless fragment.relative?
+      if urn?
+        RDF::URI.intern(to_s.sub(/:+$/,'') + ':' + fragment.to_s.sub(/^:+/,''))
+      else # !urn?
+        case to_s[-1].chr
+          when '#'
+            case fragment.to_s[0].chr
+              when '/' then # Base ending with '#', fragment beginning with '/'.  The fragment wins, we use '/'.
+              RDF::URI.intern(to_s.sub(/#+$/,'') + '/' + fragment.to_s.sub(/^\/+/,''))
+            else
+              RDF::URI.intern(to_s.sub(/#+$/,'') + '#' + fragment.to_s.sub(/^#+/,''))
+            end
+          else # includes '/'.  Results from bases ending in '/' are the same as if there were no trailing slash.
+            case fragment.to_s[0].chr
+              when '#' then # Base ending with '/', fragment beginning with '#'.  The fragment wins, we use '#'.
+                RDF::URI.intern(to_s.sub(/\/+$/,'') + '#' + fragment.to_s.sub(/^#+/,''))
+              else
+                RDF::URI.intern(to_s.sub(/\/+$/,'') + '/' + fragment.to_s.sub(/^\/+/,''))
+              end
+          end
+      end
+    end
+
+    ##
+    # Simple concatenation operator.  Returns a URI formed from concatenating
+    # the string form of two elements.
+    #
+    # For building URIs from fragments, you may want to use the smart
+    # separator, `#/`.  `#join` implements another set of URI building
+    # semantics.
+    #
+    # @example Concatenating a string to a URI
+    #     RDF::URI.new('http://example.org/test') + 'test'
+    #     #=> RDF::URI('http://example.org/testtest')
+    # @example Concatenating two URIs
+    #     RDF::URI.new('http://example.org/test') + RDF::URI.new('test')
+    #     #=> RDF::URI('http://example.org/testtest')
+    # @see RDF::URI#/
+    # @see RDF::URI#join
+    # @param [Any]
+    # @return [RDF::URI]
+    def +(other)
+      RDF::URI.intern(self.to_s + other.to_s)
+    end
+
     ##
     # Returns `true` if this URI's path component is equal to `/`.
     #
-    # @return [Boolean]
+    # @example
+    #   RDF::URI('http://example.org/').root?                   #=> true
+    #   RDF::URI('http://example.org/path/').root?              #=> false
+    #
+    # @return [Boolean] `true` or `false`
     def root?
       self.path == '/' || self.path.empty?
     end
@@ -148,7 +305,11 @@ module RDF
     ##
     # Returns a copy of this URI with the path component set to `/`.
     #
-    # @return [URI]
+    # @example
+    #   RDF::URI('http://example.org/').root                    #=> RDF::URI('http://example.org/')
+    #   RDF::URI('http://example.org/path/').root               #=> RDF::URI('http://example.org/')
+    #
+    # @return [RDF::URI]
     def root
       if root?
         self
@@ -162,7 +323,11 @@ module RDF
     ##
     # Returns `true` if this URI's path component isn't equal to `/`.
     #
-    # @return [Boolean]
+    # @example
+    #   RDF::URI('http://example.org/').has_parent?             #=> false
+    #   RDF::URI('http://example.org/path/').has_parent?        #=> true
+    #
+    # @return [Boolean] `true` or `false`
     def has_parent?
       !root?
     end
@@ -171,7 +336,11 @@ module RDF
     # Returns a copy of this URI with the path component ascended to the
     # parent directory, if any.
     #
-    # @return [URI]
+    # @example
+    #   RDF::URI('http://example.org/').parent                  #=> nil
+    #   RDF::URI('http://example.org/path/').parent             #=> RDF::URI('http://example.org/')
+    #
+    # @return [RDF::URI]
     def parent
       case
         when root? then nil
@@ -189,33 +358,90 @@ module RDF
     ##
     # Returns a qualified name (QName) for this URI, if possible.
     #
-    # @return [Array(Symbol, Symbol)]
+    # @example
+    #   RDF::URI('http://purl.org/dc/terms/').qname             #=> [:dc, nil]
+    #   RDF::URI('http://purl.org/dc/terms/title').qname        #=> [:dc, :title]
+    #   RDF::DC.title.qname                                     #=> [:dc, :title]
+    #
+    # @return [Array(Symbol, Symbol)] or `nil` if no QName found
     def qname
-      Vocabulary.each do |vocab|
-        if to_s.index(vocab.to_uri.to_s) == 0
-          vocab_name = vocab.__name__.split('::').last.downcase
-          local_name = to_s[vocab.to_uri.to_s.size..-1]
-          unless vocab_name.empty? || local_name.empty?
-            return [vocab_name.to_sym, local_name.to_sym]
+      if self.to_s =~ %r([:/#]([^:/#]*)$)
+        local_name = $1
+        vocab_uri  = local_name.empty? ? self.to_s : self.to_s[0...-(local_name.length)]
+        Vocabulary.each do |vocab|
+          if vocab.to_uri == vocab_uri
+            return [vocab.__prefix__, local_name.empty? ? nil : local_name.to_sym]
+          end
+        end
+      else
+        Vocabulary.each do |vocab|
+          vocab_uri = vocab.to_uri
+          if self.start_with?(vocab_uri)
+            local_name = self.to_s[vocab_uri.length..-1]
+            return [vocab.__prefix__, local_name.empty? ? nil : local_name.to_sym]
           end
         end
       end
-      nil # no QName found
+      return nil # no QName found
     end
 
     ##
     # Returns a duplicate copy of `self`.
     #
-    # @return [URI]
+    # @return [RDF::URI]
     def dup
       self.class.new(@uri.dup)
     end
 
+    ##
+    # @private
+    def freeze
+      @uri.freeze
+      super
+    end
+
+    ##
+    # Returns `true` if this URI starts with the given `string`.
+    #
+    # @example
+    #   RDF::URI('http://example.org/').start_with?('http')     #=> true
+    #   RDF::URI('http://example.org/').start_with?('ftp')      #=> false
+    #
+    # @param  [String, #to_s] string
+    # @return [Boolean] `true` or `false`
+    # @see    String#start_with?
+    # @since  0.3.0
+    def start_with?(string)
+      to_s.start_with?(string.to_s)
+    end
+    alias_method :starts_with?, :start_with?
+
+    ##
+    # Returns `true` if this URI ends with the given `string`.
+    #
+    # @example
+    #   RDF::URI('http://example.org/').end_with?('/')          #=> true
+    #   RDF::URI('http://example.org/').end_with?('#')          #=> false
+    #
+    # @param  [String, #to_s] string
+    # @return [Boolean] `true` or `false`
+    # @see    String#end_with?
+    # @since  0.3.0
+    def end_with?(string)
+      to_s.end_with?(string.to_s)
+    end
+    alias_method :ends_with?, :end_with?
+
     ##
     # Checks whether this URI is equal to `other`.
     #
-    # @param  [URI] other
-    # @return [Boolean]
+    # @example
+    #   RDF::URI('http://t.co/').eql?(RDF::URI('http://t.co/')) #=> true
+    #   RDF::URI('http://t.co/').eql?('http://t.co/')           #=> false
+    #   RDF::URI('http://purl.org/dc/terms/').eql?(RDF::DC)     #=> false
+    #
+    # @param  [RDF::URI] other
+    # @return [Boolean] `true` or `false`
     def eql?(other)
       other.is_a?(URI) && self == other
     end
@@ -223,32 +449,78 @@ module RDF
     ##
     # Checks whether this URI is equal to `other`.
     #
+    # @example
+    #   RDF::URI('http://t.co/') == RDF::URI('http://t.co/')    #=> true
+    #   RDF::URI('http://t.co/') == 'http://t.co/'              #=> true
+    #   RDF::URI('http://purl.org/dc/terms/') == RDF::DC        #=> true
+    #
     # @param  [Object] other
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     def ==(other)
       case other
-        when Addressable::URI
-          to_s == other.to_s
-        else
-          other.respond_to?(:to_uri) && to_s == other.to_uri.to_s
+        when String then to_s == other
+        when URI, Addressable::URI then to_s == other.to_s
+        else other.respond_to?(:to_uri) && to_s == other.to_uri.to_s
+      end
+    end
+
+    ##
+    # Checks for case equality to the given `other` object.
+    #
+    # @example
+    #   RDF::URI('http://example.org/') === /example/           #=> true
+    #   RDF::URI('http://example.org/') === /foobar/            #=> false
+    #   RDF::URI('http://t.co/') === RDF::URI('http://t.co/')   #=> true
+    #   RDF::URI('http://t.co/') === 'http://t.co/'             #=> true
+    #   RDF::URI('http://purl.org/dc/terms/') === RDF::DC       #=> true
+    #
+    # @param  [Object] other
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def ===(other)
+      case other
+        when Regexp then other === to_s
+        else self == other
+      end
+    end
+
+    ##
+    # Performs a pattern match using the given regular expression.
+    #
+    # @example
+    #   RDF::URI('http://example.org/') =~ /example/            #=> 7
+    #   RDF::URI('http://example.org/') =~ /foobar/             #=> nil
+    #
+    # @param  [Regexp] pattern
+    # @return [Integer] the position the match starts
+    # @see    String#=~
+    # @since  0.3.0
+    def =~(pattern)
+      case pattern
+        when Regexp then to_s =~ pattern
+        else super # `Object#=~` returns `false`
       end
     end
 
     ##
     # Returns `self`.
     #
-    # @return [URI]
+    # @return [RDF::URI] `self`
     def to_uri
       self
     end
 
     ##
-    # Returns a string representation of this URI.
+    # Returns the string representation of this URI.
+    #
+    # @example
+    #   RDF::URI('http://example.org/').to_str                  #=> 'http://example.org/'
     #
     # @return [String]
-    def to_s
+    def to_str
       @uri.to_s
     end
+    alias_method :to_s, :to_str
 
     ##
     # Returns a hash code for this URI.
@@ -262,15 +534,18 @@ module RDF
     # Returns `true` if this URI instance supports the `symbol` method.
     #
     # @param  [Symbol, String, #to_s] symbol
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     def respond_to?(symbol)
       @uri.respond_to?(symbol) || super
     end
 
+  protected
+
     ##
     # @param  [Symbol, String, #to_s] symbol
-    # @param  [Array<Object>]         args
+    # @param  [Array<Object>] args
     # @yield
+    # @return [Object]
     # @private
     def method_missing(symbol, *args, &block)
       if @uri.respond_to?(symbol)
@@ -283,7 +558,5 @@ module RDF
         super
       end
     end
-
-    protected :method_missing
-  end
-end
+  end # URI
+end # RDF

data/lib/rdf/model/value.rb

@@ -104,7 +104,7 @@ module RDF
     #
     # @abstract
     # @param  [Object]  other
-    # @return [Integer] -1, 0, 1
+    # @return [Integer] `-1`, `0`, or `1`
     def <=>(other)
       self.to_s <=> other.to_s
     end

data/lib/rdf/ntriples/reader.rb

@@ -33,9 +33,9 @@ module RDF::NTriples
     NODEID                = /^_:([A-Za-z][A-Za-z0-9]*)/.freeze
     URIREF                = /^<([^>]+)>/.freeze
     LITERAL_PLAIN         = /^"((?:\\"|[^"])*)"/.freeze
-    LITERAL_WITH_LANGUAGE = /^"((?:\\"|[^"])*)"@([a-z]+[\-a-z0-9]*)/.freeze
+    LITERAL_WITH_LANGUAGE = /^"((?:\\"|[^"])*)"@([a-z]+[\-A-Za-z0-9]*)/.freeze
     LITERAL_WITH_DATATYPE = /^"((?:\\"|[^"])*)"\^\^<([^>]+)>/.freeze
-    LANGUAGE_TAG          = /^@([a-z]+[\-a-z0-9]*)/.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
@@ -197,8 +197,12 @@ module RDF::NTriples
     # @return [RDF::URI]
     # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (uriref)
     def read_uriref(options = {})
-      if uri = match(URIREF)
-        RDF::URI.send(options[:intern] ? :intern : :new, uri)
+      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
 
@@ -207,6 +211,7 @@ module RDF::NTriples
     # @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
@@ -215,17 +220,20 @@ module RDF::NTriples
     # @return [RDF::Literal]
     # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (literal)
     def read_literal
-      if literal = match(LITERAL_PLAIN)
-        literal = self.class.unescape(literal)
-
-        if language = match(LANGUAGE_TAG)
-          RDF::Literal.new(literal, :language => language)
-        elsif datatype = match(/^(\^\^)/) # FIXME
-          RDF::Literal.new(literal, :datatype => read_uriref || fail_object)
-        else
-          RDF::Literal.new(literal) # plain string 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
-end
+  end # Reader
+end # RDF::NTriples

data/lib/rdf/ntriples/writer.rb

@@ -185,7 +185,7 @@ module RDF::NTriples
     # @param  [Hash{Symbol => Object}] options
     # @return [String]
     def format_uri(uri, options = {})
-      "<%s>" % uri_for(uri)
+      "<%s>" % escaped(uri_for(uri))
     end
 
     ##