rdf 2.1.1 → 2.2.0.pre.rc1

data/lib/rdf/ntriples/writer.rb

@@ -182,15 +182,14 @@ module RDF::NTriples
     #
     # @param  [IO, File] output
     #   the output stream
-    # @param  [Hash{Symbol => Object}] options = ({})
-    #   any additional options. See {RDF::Writer#initialize}
-    # @option options [Boolean]  :validate (true)
+    # @param [Boolean]  validate (true)
     #   whether to validate terms when serializing
+    # @param  [Hash{Symbol => Object}] options ({})
+    #   any additional options. See {RDF::Writer#initialize}
     # @yield  [writer] `self`
     # @yieldparam  [RDF::Writer] writer
     # @yieldreturn [void]
-    def initialize(output = $stdout, options = {}, &block)
-      options = {validate: true}.merge(options)
+    def initialize(output = $stdout, validate: true, **options, &block)
       super
     end
 
@@ -218,10 +217,10 @@ module RDF::NTriples
     # Returns the N-Triples representation of a statement.
     #
     # @param  [RDF::Statement] statement
-    # @param  [Hash{Symbol => Object}] options = ({})
+    # @param  [Hash{Symbol => Object}] options ({})
     # @return [String]
-    def format_statement(statement, options = {})
-      format_triple(*statement.to_triple, options)
+    def format_statement(statement, **options)
+      format_triple(*statement.to_triple, **options)
     end
 
     ##
@@ -230,31 +229,31 @@ module RDF::NTriples
     # @param  [RDF::Resource] subject
     # @param  [RDF::URI]      predicate
     # @param  [RDF::Term]     object
-    # @param  [Hash{Symbol => Object}] options = ({})
+    # @param  [Hash{Symbol => Object}] options ({})
     # @return [String]
-    def format_triple(subject, predicate, object, options = {})
-      "%s %s %s ." % [subject, predicate, object].map { |value| format_term(value, options) }
+    def format_triple(subject, predicate, object, **options)
+      "%s %s %s ." % [subject, predicate, object].map { |value| format_term(value, **options) }
     end
 
     ##
     # Returns the N-Triples representation of a blank node.
     #
     # @param  [RDF::Node] node
-    # @param  [Hash{Symbol => Object}] options = ({})
-    # @option options [Boolean] :unique_bnodes (false)
+    # @param [Boolean] unique_bnodes (false)
     #   Serialize node using unique identifier, rather than any used to create the node.
+    # @param  [Hash{Symbol => Object}] options ({})
     # @return [String]
-    def format_node(node, options = {})
-      options[:unique_bnodes] ? node.to_unique_base : node.to_s
+    def format_node(node, unique_bnodes: false, **options)
+      unique_bnodes ? node.to_unique_base : node.to_s
     end
 
     ##
     # Returns the N-Triples representation of a URI reference using write encoding.
     #
     # @param  [RDF::URI] uri
-    # @param  [Hash{Symbol => Object}] options = ({})
+    # @param  [Hash{Symbol => Object}] options ({})
     # @return [String]
-    def format_uri(uri, options = {})
+    def format_uri(uri, **options)
       string = uri.to_s
       iriref = case
         when string =~ ESCAPE_PLAIN_U # a shortcut for the simple case
@@ -296,9 +295,9 @@ module RDF::NTriples
     # Returns the N-Triples representation of a literal.
     #
     # @param  [RDF::Literal, String, #to_s] literal
-    # @param  [Hash{Symbol => Object}] options = ({})
+    # @param  [Hash{Symbol => Object}] options ({})
     # @return [String]
-    def format_literal(literal, options = {})
+    def format_literal(literal, **options)
       case literal
         when RDF::Literal
           # Note, escaping here is more robust than in Term

data/lib/rdf/query.rb

@@ -109,7 +109,7 @@ module RDF
     #   @param [Array<Solution>] args
     #   @return [Solutions] returns new solutions including the arguments, which must each be a {Solution}
     def self.Solutions(*args)
-       if args.length == 1
+      if args.length == 1
         return args[0] if args[0].is_a?(Solutions)
         args = args[0] if args[0].is_a?(Array)
       end
@@ -143,7 +143,7 @@ module RDF
     ##
     # Initializes a new basic graph pattern query.
     #
-    # @overload initialize(patterns = [], options = {})
+    # @overload initialize(patterns = [], **options)
     #   @param  [Array<RDF::Query::Pattern>] patterns
     #     ...
     #   @param  [Hash{Symbol => Object}] options
@@ -162,32 +162,31 @@ module RDF
     #   @yieldparam  [RDF::Query] query
     #   @yieldreturn [void] ignored
     #
-    # @overload initialize(patterns, options = {})
+    # @overload initialize(patterns, **options)
     #   @param  [Hash{Object => Object}] patterns
     #     ...
-    #   @param  [Hash{Symbol => Object}] options
-    #     any additional keyword options
-    #   @option options [RDF::Query::Solutions] :solutions (Solutions.new)
-    #   @option options [RDF::Resource, RDF::Query::Variable, false] :graph_name (nil)
+    #   @param [RDF::Query::Solutions] solutions (Solutions.new)
+    #   @param [RDF::Resource, RDF::Query::Variable, false] graph_name (false)
     #     Default graph name for matching against queryable.
     #     Named queries either match against a specifically named
     #     graphs if the name is an {RDF::Resource} or bound {RDF::Query::Variable}.
     #     Names that are against unbound variables match either default
     #     or named graphs.
     #     The name of `false` will only match against the default graph.
-    #   @option options [RDF::Resource, RDF::Query::Variable, false] :name (nil)
+    #   @param [RDF::Resource, RDF::Query::Variable, false] name (false)
     #     Alias for `:graph_name`.
+    #   @param  [Hash{Symbol => Object}] options
+    #     any additional keyword options
     #   @yield  [query]
     #   @yieldparam  [RDF::Query] query
     #   @yieldreturn [void] ignored
-    def initialize(*patterns, &block)
-      @options  = patterns.last.is_a?(Hash) ? patterns.pop.dup : {}
-      patterns << @options if patterns.empty?
+    def initialize(*patterns, solutions: nil, graph_name: nil, name: nil, **options, &block)
+      @options = options.dup
       @variables = {}
-      @solutions = Query::Solutions(@options.delete(:solutions))
-      graph_name = @options.fetch(:graph_name, @options.fetch(:name, nil))
-      @options.delete(:graph_name)
-      @options.delete(:name)
+      @solutions = Query::Solutions(solutions)
+      graph_name = name if graph_name.nil?
+
+      patterns << @options if patterns.empty?
 
       @patterns  = case patterns.first
         when Hash  then compile_hash_patterns(HashPatternNormalizer.normalize!(patterns.first.dup, @options))
@@ -226,7 +225,7 @@ module RDF
     # @option options [Boolean] :optional (false)
     #   whether this is an optional pattern
     # @return [void] self
-    def pattern(pattern, options = {})
+    def pattern(pattern, **options)
       @patterns << Pattern.from(pattern, options)
       self
     end
@@ -238,7 +237,7 @@ module RDF
     #   any additional options for optimization
     # @return [RDF::Query] a copy of `self`
     # @since  0.3.0
-    def optimize(options = {})
+    def optimize(**options)
       self.dup.optimize!(options)
     end
 
@@ -251,7 +250,7 @@ module RDF
     # @return [self]
     # @see    RDF::Query::Pattern#cost
     # @since  0.3.0
-    def optimize!(options = {})
+    def optimize!(**options)
       @patterns.sort! do |a, b|
         (a.cost || 0) <=> (b.cost || 0)
       end
@@ -274,15 +273,20 @@ module RDF
     #
     # @param  [RDF::Queryable] queryable
     #   the graph or repository to query
+    # @param [RDF::Query::Solutions] solutions (Solutions.new)
+    # @param [RDF::Resource, RDF::Query::Variable, false] graph_name (nil)
+    #   Default graph name for matching against queryable.
+    #   Named queries either match against a specifically named
+    #   graphs if the name is an {RDF::Resource} or bound {RDF::Query::Variable}.
+    #   Names that are against unbound variables match either default
+    #   or named graphs.
+    #   The name of `false` will only match against the default graph.
+    # @param [RDF::Resource, RDF::Query::Variable, false] name (nil)
+    #   Alias for `:graph_name`.
     # @param  [Hash{Symbol => Object}] options
     #   any additional keyword options
     # @option options [Hash{Symbol => RDF::Term}] bindings
     #   optional variable bindings to use
-    # @option options [RDF::Resource, RDF::Query::Variable, false] graph_name (nil)
-    #   Specific graph name for matching against queryable;
-    #   overrides default graph defined on query.
-    # @option options [RDF::Resource, RDF::Query::Variable, false] name (nil)
-    #   Alias for `:graph_name`.
     # @option options [RDF::Query::Solutions] solutions
     #   optional initial solutions for chained queries
     # @yield  [solution]
@@ -293,17 +297,14 @@ module RDF
     #   the resulting solution sequence
     # @see    http://www.holygoat.co.uk/blog/entry/2005-10-25-1
     # @see    http://www.w3.org/TR/sparql11-query/#emptyGroupPattern
-    def execute(queryable, options = {}, &block)
+    def execute(queryable, solutions: Solution.new, graph_name: nil, name: nil, **options, &block)
       validate!
-      options = options.dup
-
-      # just so we can call #keys below without worrying
-      options[:bindings] ||= {}
+      options = {bindings: {}}.merge(options)
 
       # Use provided solutions to allow for query chaining
       # Otherwise, a quick empty solution simplifies the logic below; no special case for
       # the first pattern
-      @solutions = Query::Solutions(options[:solutions] || Solution.new)
+      @solutions = Query::Solutions(solutions)
 
       # If there are no patterns, just return the empty solution
       if empty?
@@ -312,7 +313,9 @@ module RDF
       end
 
       patterns = @patterns
-      graph_name = options.fetch(:graph_name, options.fetch(:name, self.graph_name))
+      graph_name = name if graph_name.nil?
+      graph_name = self.graph_name if graph_name.nil?
+      options[:graph_name] = graph_name unless graph_name.nil?
 
       # Add graph_name to pattern, if necessary
       unless graph_name.nil?

data/lib/rdf/query/hash_pattern_normalizer.rb

@@ -173,7 +173,7 @@ module RDF; class Query
     #   any additional normalization options.
     # @option options [String] :anonymous_subject_format ("__%s__")
     #   the string format for anonymous subjects.
-    def initialize(options = {})
+    def initialize(**options)
       @options = options.dup
     end
     
@@ -184,7 +184,7 @@ module RDF; class Query
     #   the query pattern as a hash.
     # @return [Hash{Symbol => Object}]
     #   the resulting query pattern as a normalized hash.
-    def normalize!(hash_pattern = {})
+    def normalize!(**hash_pattern)
       self.class.normalize!(hash_pattern, @options)
     end
   end # RDF::Query::HashPatternNormalizer

data/lib/rdf/query/pattern.rb

@@ -5,18 +5,19 @@ module RDF; class Query
     ##
     # @private
     # @since 0.2.2
-    def self.from(pattern, options = {})
+    def self.from(pattern, graph_name: nil, **options)
       case pattern
         when Pattern then pattern
         when Array, Statement
-          self.new(pattern[0], pattern[1], pattern[2], options.merge(graph_name: pattern[3]))
+          graph_name ||= pattern[3]
+          self.new(pattern[0], pattern[1], pattern[2], graph_name: graph_name, **options)
         when Hash    then self.new(options.merge(pattern))
         else raise ArgumentError, "expected RDF::Query::Pattern, RDF::Statement, Hash, or Array, but got #{pattern.inspect}"
       end
     end
 
     ##
-    # @overload initialize(options = {})
+    # @overload initialize(**options)
     #   @param  [Hash{Symbol => Object}]     options
     #   @option options [Variable, Resource, Symbol, nil] :subject   (nil)
     #   @option options [Variable, URI, Symbol, nil]      :predicate (nil)
@@ -25,7 +26,7 @@ module RDF; class Query
     #     A graph_name of nil matches any graph, a graph_name of false, matches only the default graph.
     #   @option options [Boolean]            :optional  (false)
     #
-    # @overload initialize(subject, predicate, object, options = {})
+    # @overload initialize(subject, predicate, object, **options)
     #   @param  [Variable, Resource, Symbol, nil]         subject
     #   @param  [Variable, URI, Symbol, nil]              predicate
     #   @param  [Variable, Termm, Symbol, nil]            object

data/lib/rdf/query/solution.rb

@@ -18,7 +18,7 @@ class RDF::Query
   #   solution.mbox
   #
   # @example Retrieving all bindings in the solution as a `Hash`
-  #   solution.to_hash       #=> {mbox: "jrhacker@example.org", ...}
+  #   solution.to_h       #=> {mbox: "jrhacker@example.org", ...}
   #
   class Solution
     # Undefine all superfluous instance methods:
@@ -152,12 +152,12 @@ class RDF::Query
     # Merges the bindings from the given `other` query solution into this
     # one, overwriting any existing ones having the same name.
     #
-    # @param  [RDF::Query::Solution, #to_hash] other
+    # @param  [RDF::Query::Solution, #to_h] other
     #   another query solution or hash bindings
     # @return [void] self
     # @since  0.3.0
     def merge!(other)
-      @bindings.merge!(other.to_hash)
+      @bindings.merge!(other.to_h)
       self
     end
 
@@ -165,7 +165,7 @@ class RDF::Query
     # Merges the bindings from the given `other` query solution with a copy
     # of this one.
     #
-    # @param  [RDF::Query::Solution, #to_hash] other
+    # @param  [RDF::Query::Solution, #to_h] other
     #   another query solution or hash bindings
     # @return [RDF::Query::Solution]
     # @since  0.3.0
@@ -185,13 +185,13 @@ class RDF::Query
     #
     # Two solution mappings u1 and u2 are compatible if, for every variable v in dom(u1) and in dom(u2), u1(v) = u2(v).
     #
-    # @param [RDF::Query::Solution, #to_hash] other
+    # @param [RDF::Query::Solution, #to_h] other
     #   another query solution or hash bindings
     # @return [Boolean]
     # @see http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#defn_algCompatibleMapping
     def compatible?(other)
       @bindings.all? do |k, v|
-        !other.to_hash.has_key?(k) || other[k].eql?(v)
+        !other.to_h.has_key?(k) || other[k].eql?(v)
       end
     end
 
@@ -205,7 +205,7 @@ class RDF::Query
     # @see http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#defn_algMinus
     def disjoint?(other)
       @bindings.none? do |k, v|
-        v && other.to_hash.has_key?(k) && other[k].eql?(v)
+        v && other.to_h.has_key?(k) && other[k].eql?(v)
       end
     end
 
@@ -214,12 +214,12 @@ class RDF::Query
     # Two solution mappings u1 and u2 are isomorphic if,
     # for every variable v in dom(u1) and in dom(u2), u1(v) = u2(v).
     #
-    # @param [RDF::Query::Solution, #to_hash] other
+    # @param [RDF::Query::Solution, #to_h] other
     #   another query solution or hash bindings
     # @return [Boolean]
     def isomorphic_with?(other)
       @bindings.all? do |k, v|
-        !other.to_hash.has_key?(k) || other[k].eql?(v)
+        !other.to_h.has_key?(k) || other[k].eql?(v)
       end
     end
     
@@ -231,7 +231,7 @@ class RDF::Query
 
     ##
     # @return [Hash{Symbol => RDF::Term}}
-    def to_hash
+    def to_h
       @bindings.dup
     end
     
@@ -264,10 +264,22 @@ class RDF::Query
   protected
 
     ##
-    # @param  [Symbol] name
-    # @return [RDF::Term]
+    # @overload #to_hash
+    #   Returns object representation of this URI, broken into components
+    #
+    #   @return (see #to_h)
+    #   @deprecated Use {#to_h} instead.
+    #
+    # @overload binding(name)
+    #   Return the binding for this name
+    #
+    #   @param  [Symbol] name
+    #   @return [RDF::Term]
     def method_missing(name, *args, &block)
-      if args.empty? && @bindings.has_key?(name.to_sym)
+      if name == :to_hash
+        warn "[DEPRECATION] Solution#to_hash is deprecated, use Solution#to_h instead. Called from #{Gem.location_of_caller.join(':')}"
+        self.to_h
+      elsif args.empty? && @bindings.has_key?(name.to_sym)
         @bindings[name.to_sym]
       else
         super # raises NoMethodError

data/lib/rdf/query/variable.rb

@@ -151,7 +151,7 @@ class RDF::Query
     def variables
       {name => self}
     end
-    alias_method :to_hash, :variables
+    alias_method :to_h, :variables
 
     ##
     # Returns this variable's bindings (if any) as a `Hash`.
@@ -164,7 +164,7 @@ class RDF::Query
     ##
     # Returns a hash code for this variable.
     #
-    # @return [Fixnum]
+    # @return [Integer]
     # @since  0.3.0
     def hash
       @name.hash
@@ -219,5 +219,23 @@ class RDF::Query
       prefix = distinguished? ? '?' : "??"
       unbound? ? "#{prefix}#{name}" : "#{prefix}#{name}=#{value}"
     end
+
+  protected
+    ##
+    # @overload #to_hash
+    #   Returns object representation of this URI, broken into components
+    #
+    #   @return (see #object)
+    #   @deprecated Use {#to_h} instead.
+    def method_missing(name, *args, &block)
+      if name == :to_hash
+        warn "[DEPRECATION] Variable#to_hash is deprecated, use Variable#to_h instead. Called from #{Gem.location_of_caller.join(':')}"
+        self.to_h
+      elsif args.empty? && @bindings.has_key?(name.to_sym)
+        @bindings[name.to_sym]
+      else
+        super # raises NoMethodError
+      end
+    end
   end # Variable
 end # RDF::Query

data/lib/rdf/reader.rb

@@ -219,31 +219,43 @@ module RDF
     #
     # @param  [IO, File, String] input
     #   the input stream to read
-    # @param  [Hash{Symbol => Object}] options
-    #   any additional options
-    # @option options [Encoding] :encoding     (Encoding::UTF_8)
+    # @param [Encoding] encoding     (Encoding::UTF_8)
     #   the encoding of the input stream
-    # @option options [Boolean]  :validate     (false)
+    # @param [Boolean]  validate     (false)
     #   whether to validate the parsed statements and values
-    # @option options [Boolean]  :canonicalize (false)
+    # @param [Boolean]  canonicalize (false)
     #   whether to canonicalize parsed literals
-    # @option options [Boolean]  :intern       (true)
+    # @param [Boolean]  intern       (true)
     #   whether to intern all parsed URIs
-    # @option options [Hash]     :prefixes     (Hash.new)
+    # @param [Hash]     prefixes     (Hash.new)
     #   the prefix mappings to use (not supported by all readers)
-    # @option options [#to_s]    :base_uri     (nil)
+    # @param [#to_s]    base_uri     (nil)
     #   the base URI to use when resolving relative URIs (not supported by
     #   all readers)
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
     # @yield  [reader] `self`
     # @yieldparam  [RDF::Reader] reader
     # @yieldreturn [void] ignored
-    def initialize(input = $stdin, options = {}, &block)
-      @options = options.dup
-      @options[:validate]     ||= false
-      @options[:canonicalize] ||= false
-      @options[:intern]       ||= true
-      @options[:prefixes]     ||= Hash.new
-      @options[:base_uri]     ||= input.base_uri if input.respond_to?(:base_uri)
+    def initialize(input = $stdin,
+                   encoding:      Encoding::UTF_8,
+                   validate:      false,
+                   canonicalize:  false,
+                   intern:        true,
+                   prefixes:      Hash.new,
+                   base_uri:      nil,
+                   **options,
+                   &block)
+
+      base_uri     ||= input.base_uri if input.respond_to?(:base_uri)
+      @options = options.merge({
+        encoding:       encoding,
+        validate:       validate,
+        canonicalize:   canonicalize,
+        intern:         intern,
+        prefixes:       prefixes,
+        base_uri:       base_uri
+      })
 
       @input = case input
         when String then StringIO.new(input)
@@ -619,13 +631,12 @@ module RDF
     ##
     # Initializes a new lexer error instance.
     #
-    # @param  [String, #to_s]          message
-    # @param  [Hash{Symbol => Object}] options
-    # @option options [String]         :token  (nil)
-    # @option options [Integer]        :lineno (nil)
-    def initialize(message, options = {})
-      @token      = options[:token]
-      @lineno     = options[:lineno] || (@token.lineno if @token.respond_to?(:lineno))
+    # @param  [String, #to_s]  message
+    # @param  [String]         token  (nil)
+    # @param  [Integer]        lineno (nil)
+    def initialize(message, token: nil, lineno: nil)
+      @token      = token
+      @lineno     = lineno || (token.lineno if token.respond_to?(:lineno))
       super(message.to_s)
     end
   end # ReaderError