sparql 3.1.0 → 3.1.6

data/lib/sparql/grammar/parser11.rb

@@ -6,8 +6,8 @@ module SPARQL::Grammar
   ##
   # A parser for the SPARQL 1.1 grammar.
   #
-  # @see http://www.w3.org/TR/sparql11-query/#grammar
-  # @see http://en.wikipedia.org/wiki/LR_parser
+  # @see https://www.w3.org/TR/sparql11-query/#grammar
+  # @see https://en.wikipedia.org/wiki/LR_parser
   class Parser
     include SPARQL::Grammar::Meta
     include SPARQL::Grammar::Terminals
@@ -23,6 +23,7 @@ module SPARQL::Grammar
       STRAFTER STRBEFORE STRDT STRENDS STRLANG STRLEN STRSTARTS STRUUID STR
       TIMEZONE TZ UCASE URI UUID YEAR
       isBLANK isIRI isURI isLITERAL isNUMERIC sameTerm
+      isTRIPLE TRIPLE SUBJECT PREDICATE OBJECT
     }.map {|s| s.downcase.to_sym}.freeze
 
     BUILTIN_RULES = [:aggregate, :regex, :substr, :replace, :exists, :notexists].freeze
@@ -184,6 +185,7 @@ module SPARQL::Grammar
          |STRAFTER|STRBEFORE|STRDT|STRENDS|STRLANG|STRLEN|STRSTARTS|STRUUID|SUBSTR|STR|SUM
          |TIMEZONE|TZ|UCASE|UNDEF|URI|UUID|YEAR
          |isBLANK|isIRI|isURI|isLITERAL|isNUMERIC|sameTerm
+         |isTRIPLE|TRIPLE|SUBJECT|PREDICATE|OBJECT
         }x
         add_prod_datum(token.value.downcase.to_sym, token.value.downcase.to_sym)
       else
@@ -586,7 +588,7 @@ module SPARQL::Grammar
     production(:GroupGraphPatternSub) do |input, data, callback|
       debug("GroupGraphPatternSub") {"q #{data[:query].inspect}"}
 
-      res = case data[:query].length
+      res = case Array(data[:query]).length
       when 0 then SPARQL::Algebra::Operator::BGP.new
       when 1 then data[:query].first
       when 2
@@ -647,7 +649,7 @@ module SPARQL::Grammar
       data[:input_query] = input.delete(:query) || [SPARQL::Algebra::Operator::BGP.new]
     end
     production(:GraphPatternNotTriples) do |input, data, callback|
-      lhs = data[:input_query].first
+      lhs = Array(data[:input_query]).first
 
       # Filter trickls up to GroupGraphPatternSub
       add_prod_datum(:filter, data[:filter])
@@ -752,7 +754,7 @@ module SPARQL::Grammar
       end
     end
 
-    # [65]  DataBlockValue	        ::= iri | RDFLiteral | NumericLiteral | BooleanLiteral | 'UNDEF'
+    # [65]  DataBlockValue	        ::= EmbTD | iri | RDFLiteral | NumericLiteral | BooleanLiteral | 'UNDEF'
     production(:DataBlockValue) do |input, data, callback|
       add_prod_datum :DataBlockValue, data.values.first
     end
@@ -831,7 +833,7 @@ module SPARQL::Grammar
       add_prod_datum(:ConstructTemplate, data[:ConstructTemplate])
     end
 
-    # [75]  	TriplesSameSubject	  ::=  	VarOrTerm PropertyListNotEmpty
+    # [75]  	TriplesSameSubject	  ::=  	VarOrTermOrEmbTP PropertyListNotEmpty
     #                                 |	TriplesNode PropertyList
     production(:TriplesSameSubject) do |input, data, callback|
       add_prod_datum(:pattern, data[:pattern])
@@ -840,8 +842,8 @@ module SPARQL::Grammar
     # [77]  	PropertyListNotEmpty	  ::=  	Verb ObjectList
     #                                       ( ';' ( Verb ObjectList )? )*
     start_production(:PropertyListNotEmpty) do |input, data, callback|
-      subject = input[:VarOrTerm] || input[:TriplesNode] || input[:GraphNode]
-      error(nil, "Expected VarOrTerm or TriplesNode or GraphNode", production: :PropertyListNotEmpty) if validate? && !subject
+      subject = input[:VarOrTermOrEmbTP] || input[:TriplesNode] || input[:GraphNode]
+      error(nil, "Expected VarOrTermOrEmbTP or TriplesNode or GraphNode", production: :PropertyListNotEmpty) if validate? && !subject
       data[:Subject] = subject
     end
     production(:PropertyListNotEmpty) do |input, data, callback|
@@ -867,13 +869,17 @@ module SPARQL::Grammar
       add_prod_datum(:path, data[:path])
     end
 
-    # [80]  	Object	  ::=  	GraphNode
+    # [80]  	Object	  ::=  	GraphNode AnnotationPattern?
+    start_production(:Object) do |input, data, callback|
+      data[:Subject] = Array(input[:Subject]).first
+      data[:Verb] = Array(input[:Verb]).first
+    end
     production(:Object) do |input, data, callback|
-      object = data[:VarOrTerm] || data[:TriplesNode] || data[:GraphNode]
+      object = data[:GraphNode]
+      add_prod_datum(:pattern, data[:pattern])
       if object
         if prod_data[:Verb]
           add_pattern(:Object, subject: prod_data[:Subject], predicate: prod_data[:Verb], object: object)
-          add_prod_datum(:pattern, data[:pattern])
         elsif prod_data[:VerbPath]
           add_prod_datum(:path,
             SPARQL::Algebra::Expression(:path,
@@ -883,8 +889,17 @@ module SPARQL::Grammar
         end
       end
     end
+    start_production(:_Object_1) do |input, data, callback|
+      pattern = RDF::Query::Pattern.new(input[:Subject], input[:Verb], input[:GraphNode].first)
+      error("ObjectPath", "Expected Verb",
+        production: :_Object_1) unless input[:Verb]
+      data[:TriplesNode] = [pattern]
+    end
+    production(:_Object_1) do |input, data, callback|
+      add_prod_datum(:pattern, data[:pattern])
+    end
 
-    # [81]	TriplesSameSubjectPath	::=	VarOrTerm PropertyListPathNotEmpty | TriplesNode PropertyListPath
+    # [81]	TriplesSameSubjectPath	::=	VarOrTermOrEmbTP PropertyListPathNotEmpty | TriplesNode PropertyListPath
     production(:TriplesSameSubjectPath) do |input, data, callback|
       add_prod_datum(:pattern, data[:pattern])
       add_prod_datum(:path, data[:path])
@@ -892,8 +907,8 @@ module SPARQL::Grammar
 
     # [83]  	PropertyListPathNotEmpty	  ::=  	( VerbPath | VerbSimple ) ObjectList ( ';' ( ( VerbPath | VerbSimple ) ObjectList )? )*
     start_production(:PropertyListPathNotEmpty) do |input, data, callback|
-      subject = input[:VarOrTerm] || input[:TriplesNode] || input[:GraphNode]
-      error(nil, "Expected VarOrTerm, got nothing", production: :PropertyListPathNotEmpty) if validate? && !subject
+      subject = input[:VarOrTermOrEmbTP] || input[:TriplesNode] || input[:GraphNode]
+      error(nil, "Expected VarOrTermOrEmbTP, got nothing", production: :PropertyListPathNotEmpty) if validate? && !subject
       data[:Subject] = subject
     end
     production(:PropertyListPathNotEmpty) do |input, data, callback|
@@ -933,9 +948,13 @@ module SPARQL::Grammar
       add_prod_datum(:path, data[:path])
     end
 
-    # [87]  	ObjectPath	  ::=  	GraphNodePath
+    # [87]  	ObjectPath	  ::=  	GraphNodePath AnnotationPatternPath?
+    start_production(:ObjectPath) do |input, data, callback|
+      data[:Subject] = Array(input[:Subject]).first
+      data[:Verb] = Array(input[:Verb]).first
+    end
     production(:ObjectPath) do |input, data, callback|
-      object = data[:VarOrTerm] || data[:TriplesNode] || data[:GraphNode]
+      object = data[:VarOrTermOrEmbTP] || data[:TriplesNode] || data[:GraphNode]
       if object
         if prod_data[:Verb]
           if data[:pattern] && data[:path]
@@ -943,6 +962,9 @@ module SPARQL::Grammar
             data[:pattern].unshift(RDF::Query::Pattern.new(prod_data[:Subject].first, prod_data[:Verb], object.first))
             bgp = SPARQL::Algebra::Expression[:bgp, data[:pattern]]
             add_prod_datum(:path, SPARQL::Algebra::Expression[:sequence, bgp, *data[:path]])
+          elsif data[:path]
+            # AnnotationPatternPath case
+            add_prod_datum(:path, data[:path])
           else
             add_pattern(:Object, subject: prod_data[:Subject], predicate: prod_data[:Verb], object: object)
             add_prod_datum(:pattern, data[:pattern])
@@ -956,6 +978,16 @@ module SPARQL::Grammar
         end
       end
     end
+    start_production(:_ObjectPath_1) do |input, data, callback|
+      pattern = RDF::Query::Pattern.new(input[:Subject], input[:Verb], input[:GraphNode].first)
+      error("ObjectPath", "Expected Verb",
+        production: :_ObjectPath_1) unless input[:Verb]
+      data[:TriplesNode] = [pattern]
+    end
+    production(:_ObjectPath_1) do |input, data, callback|
+      add_prod_datum(:pattern, data[:pattern])
+    end
+
     # [88]  	Path	  ::=  	PathAlternative
     # output is a :Path or :iri
     production(:Path) do |input, data, callback|
@@ -1084,24 +1116,24 @@ module SPARQL::Grammar
       add_prod_datum(:path, data[:path])
     end
 
-    # [104]  	GraphNode	  ::=  	VarOrTerm |	TriplesNode
+    # [104]  	GraphNode	  ::=  	VarOrTermOrEmbTP |	TriplesNode
     production(:GraphNode) do |input, data, callback|
-      term = data[:VarOrTerm] || data[:TriplesNode]
+      term = data[:VarOrTermOrEmbTP] || data[:TriplesNode]
       add_prod_datum(:pattern, data[:pattern])
       add_prod_datum(:GraphNode, term)
     end
 
-    # [105]	GraphNodePath	::=	VarOrTerm | TriplesNodePath
+    # [105]	GraphNodePath	::=	VarOrTermOrEmbTP | TriplesNodePath
     production(:GraphNodePath) do |input, data, callback|
-      term = data[:VarOrTerm] || data[:TriplesNode]
+      term = data[:VarOrTermOrEmbTP] || data[:TriplesNode]
       add_prod_datum(:pattern, data[:pattern])
       add_prod_datum(:path, data[:path])
       add_prod_datum(:GraphNode, term)
     end
 
-    # [106]  	VarOrTerm	  ::=  	Var | GraphTerm
-    production(:VarOrTerm) do |input, data, callback|
-      data.values.each {|v| add_prod_datum(:VarOrTerm, v)}
+    # [106s]  	VarOrTermOrEmbTP        ::= Var | GraphTerm | EmbTP
+    production(:VarOrTermOrEmbTP) do |input, data, callback|
+      data.values.each {|v| add_prod_datum(:VarOrTermOrEmbTP, v)}
     end
 
     # [107]  	VarOrIri	  ::=  	Var | iri
@@ -1119,6 +1151,22 @@ module SPARQL::Grammar
                       data[:NIL])
     end
 
+    # [174] EmbTP ::= '<<' EmbSubjectOrObject Verb EmbSubjectOrObject '>>'
+    production(:EmbTP) do |input, data, callback|
+      subject, object = data[:EmbSubjectOrObject]
+      predicate = data[:Verb]
+      add_pattern(:EmbTP,
+                  subject: subject,
+                  predicate: predicate,
+                  object: object)
+    end
+
+    # [175] EmbSubjectOrObject ::=	Var | BlankNode | iri | RDFLiteral
+    #                            | NumericLiteral | BooleanLiteral | EmbTP
+    production(:EmbSubjectOrObject) do |input, data, callback|
+      data.values.each {|v| add_prod_datum(:EmbSubjectOrObject, v)}
+    end
+
     # [110]  	Expression	  ::=  	ConditionalOrExpression
     production(:Expression) do |input, data, callback|
       add_prod_datum(:Expression, data[:Expression])
@@ -1258,6 +1306,7 @@ module SPARQL::Grammar
     #                                 | iriOrFunction | RDFLiteral
     #                                 | NumericLiteral | BooleanLiteral
     #                                 | Var
+    #                                 | EmbTP
     production(:PrimaryExpression) do |input, data, callback|
       if data[:Expression]
         add_prod_datum(:Expression, data[:Expression])
@@ -1271,6 +1320,8 @@ module SPARQL::Grammar
         add_prod_datum(:Expression, data[:literal])
       elsif data[:Var]
         add_prod_datum(:Expression, data[:Var])
+      elsif data[:pattern]
+        add_prod_datum(:Expression, data[:pattern])
       end
 
       # Keep track of this for parent UnaryExpression production
@@ -1441,6 +1492,43 @@ module SPARQL::Grammar
       add_prod_datum(:UnaryExpression, data[:UnaryExpression])
     end
 
+    # [177]	AnnotationPattern	      ::=	'{|' PropertyListNotEmpty '|}'
+    #start_production(:AnnotationPattern) do |input, data, callback|
+    #  data[:TriplesNode] = prod_data[:TriplesNode].first
+    #end
+    #production(:AnnotationPattern) do |input, data, callback|
+    #  add_prod_datum(:pattern, data[:pattern])
+    #end
+
+    # [178]	AnnotationPatternPath	      ::=	'{|' PropertyListPathNotEmpty '|}'
+    start_production(:AnnotationPatternPath) do |input, data, callback|
+      data[:TriplesNode] = input[:TriplesNode]
+    end
+    production(:AnnotationPatternPath) do |input, data, callback|
+      if data[:pattern]
+        add_prod_datum(:pattern, data[:pattern])
+      elsif data[:path]
+        # Replace the subject in the path with the node being annotated.
+        data[:path].first.operands[0] = data[:TriplesNode]
+        add_prod_datum(:path, data[:path])
+      end
+    end
+
+    # [179] EmbTD                   ::= '<<' DataValueTerm ( iri | 'a' ) DataValueTerm '>>'
+    production(:EmbTD) do |input, data, callback|
+      subject, object = data[:DataValueTerm]
+      predicate = data[:iri]
+      add_pattern(:EmbTD,
+                  subject: subject,
+                  predicate: predicate,
+                  object: object)
+    end
+
+    # [180] DataValueTerm           ::= EmbTD | iri | RDFLiteral | NumericLiteral | BooleanLiteral
+    production(:DataValueTerm) do |input, data, callback|
+      add_prod_datum :DataValueTerm, data.values.first
+    end
+    
     ##
     # Initializes a new parser instance.
     #
@@ -1458,10 +1546,8 @@ module SPARQL::Grammar
     #   definitions.
     # @option options [Boolean]  :validate     (false)
     #   whether to validate the parsed statements and values
-    # @option options [Boolean] :progress
-    #   Show progress of parser productions
-    # @option options [Boolean] :debug
-    #   Detailed debug output
+    # @option options [Logger, #write, #<<] :logger
+    #   Record error/info/debug output
     # @yield  [parser] `self`
     # @yieldparam  [SPARQL::Grammar::Parser] parser
     # @yieldreturn [void] ignored
@@ -1473,10 +1559,6 @@ module SPARQL::Grammar
       end
       @input.encode!(Encoding::UTF_8) if @input.respond_to?(:encode!)
       @options = {anon_base: "b0", validate: false}.merge(options)
-      @options[:debug] ||= case
-      when options[:progress] then 2
-      when options[:validate] then 1
-      end
 
       debug("base IRI") {base_uri.inspect}
       debug("validate") {validate?.inspect}
@@ -1527,8 +1609,8 @@ module SPARQL::Grammar
     # @param [Symbol, #to_s] prod The starting production for the parser.
     #   It may be a URI from the grammar, or a symbol representing the local_name portion of the grammar URI.
     # @return [Array]
-    # @see http://www.w3.org/TR/sparql11-query/#sparqlAlgebra
-    # @see http://axel.deri.ie/sparqltutorial/ESWC2007_SPARQL_Tutorial_unit2b.pdf
+    # @see https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
+    # @see https://axel.deri.ie/sparqltutorial/ESWC2007_SPARQL_Tutorial_unit2b.pdf
     def parse(prod = START)
       ll1_parse(@input,
         prod.to_sym,
@@ -1537,23 +1619,7 @@ module SPARQL::Grammar
         follow: FOLLOW,
         whitespace: WS,
         **@options
-      ) do |context, *data|
-        case context
-        when :trace
-          level, lineno, depth, *args = data
-          message = args.to_sse
-          d_str = depth > 100 ? ' ' * 100 + '+' : ' ' * depth
-          str = "[#{lineno}](#{level})#{d_str}#{message}".chop
-          case @options[:debug]
-          when Array
-            @options[:debug] << str unless level > 2
-          when TrueClass
-            $stderr.puts str
-          when Integer
-            $stderr.puts(str) if level <= @options[:debug]
-          end
-        end
-      end
+      )
 
       # The last thing on the @prod_data stack is the result
       @result = case

data/lib/sparql/grammar/terminals11.rb

@@ -108,8 +108,11 @@ module SPARQL::Grammar
                  |TIMEZONE|TO|TZ|UCASE|UNDEF|UNION|URI|USING|UUID|VALUES
                  |WHERE|WITH|YEAR
                  |isBLANK|isIRI|isURI|isLITERAL|isNUMERIC|sameTerm
+                 |isTRIPLE|TRIPLE|SUBJECT|PREDICATE|OBJECT
                  |true
                  |false
+                 |<<|>>
+                 |\{\||\|\}
                  |&&|!=|!|<=|>=|\^\^|\|\||[\(\),.;\[\]\{\}\+\-=<>\?\^\|\*\/a]
               )xim.freeze
 
@@ -131,6 +134,7 @@ module SPARQL::Grammar
       TIMEZONE TO TZ UCASE UNDEF UNION URI USING UUID
       VALUES WHERE WITH YEAR
       isBLANK isIRI isURI isLITERAL isNUMERIC sameTerm
+      isTRIPLE TRIPLE SUBJECT PREDICATE OBJECT
       true false
     } + [
       "DELETE DATA",

data/lib/sparql/results.rb

@@ -14,28 +14,38 @@ module SPARQL
     ##
     # Generate Solutions as JSON
     # @return [String]
-    # @see http://www.w3.org/TR/rdf-sparql-json-res/
+    # @see https://www.w3.org/TR/rdf-sparql-json-res/
     def to_json
       require 'json' unless defined?(::JSON)
-      
-      bindings = self.map do |solution|
-        variable_names.inject({}) do |memo, n|
-          memo.merge case s = solution[n]
-          when RDF::URI
-            {n => {type: "uri", value: s.to_s }}
-          when RDF::Node
-            {n => {type: "bnode", value: s.id }}
-          when RDF::Literal
-            if s.datatype?
-              {n => {type: "typed-literal", datatype: s.datatype.to_s, value: s.to_s }}
-            elsif s.language
-              {n => {type: "literal", "xml:lang" => s.language.to_s, value: s.to_s }}
-            else
-              {n => {type: "literal", value: s.to_s }}
-            end
+
+      format = ->(value) do
+        case value
+        when RDF::URI then {type: "uri", value: value.to_s }
+        when RDF::Node then {type: "bnode", value: value.id }
+        when RDF::Literal
+          if value.datatype?
+            {type: "typed-literal", datatype: value.datatype.to_s, value: value.to_s }
+          elsif value.language?
+            {type: "literal", "xml:lang" => value.language.to_s, value: value.to_s }
           else
-            {}
+            {type: "literal", value: value.to_s }
           end
+        when RDF::Statement
+          {
+            type: 'triple',
+            value: {
+              subject: format.call(value.subject),
+              predicate: format.call(value.predicate),
+              object: format.call(value.object)
+            }
+          }
+        end
+      end
+
+      bindings = self.map do |solution|
+        variable_names.inject({}) do |memo, n|
+          rep = format.call(solution[n])
+          rep ? memo.merge(n => rep) : memo
         end
       end
 
@@ -48,12 +58,36 @@ module SPARQL
     ##
     # Generate Solutions as XML
     # @return [String]
-    # @see http://www.w3.org/TR/rdf-sparql-XMLres/
+    # @see https://www.w3.org/TR/rdf-sparql-XMLres/
     def to_xml
       require 'builder' unless defined?(::Builder)
       
       xml = ::Builder::XmlMarkup.new(indent: 2)
       xml.instruct!
+
+      format = ->(s) do
+        case s
+        when RDF::URI
+          xml.uri(s.to_s)
+        when RDF::Node
+          xml.bnode(s.id)
+        when RDF::Literal
+          if s.datatype?
+            xml.literal(s.to_s, "datatype" => s.datatype.to_s)
+          elsif s.language
+            xml.literal(s.to_s, "xml:lang" => s.language.to_s)
+          else
+            xml.literal(s.to_s)
+          end
+        when RDF::Statement
+          xml.triple do
+            xml.subject {format.call(s.subject)}
+            xml.predicate {format.call(s.predicate)}
+            xml.object {format.call(s.object)}
+          end
+        end
+      end
+
       xml.sparql(xmlns: "http://www.w3.org/2005/sparql-results#") do
         xml.head do
           variable_names.each do |n|
@@ -67,20 +101,7 @@ module SPARQL
                 s = solution[n]
                 next unless s
                 xml.binding(name: n) do
-                  case s
-                  when RDF::URI
-                    xml.uri(s.to_s)
-                  when RDF::Node
-                    xml.bnode(s.id)
-                  when RDF::Literal
-                    if s.datatype?
-                      xml.literal(s.to_s, "datatype" => s.datatype.to_s)
-                    elsif s.language
-                      xml.literal(s.to_s, "xml:lang" => s.language.to_s)
-                    else
-                      xml.literal(s.to_s)
-                    end
-                  end
+                  format.call(s)
                 end
               end
             end
@@ -118,10 +139,9 @@ module SPARQL
     ##
     # Generate Solutions as CSV
     # @return [String]
-    # @see http://www.w3.org/TR/rdf-sparql-json-res/#results
-    def to_csv
+    # @see https://www.w3.org/TR/2013/REC-sparql11-results-csv-tsv-20130321/
+    def to_csv(bnode_map: {})
       require 'csv' unless defined?(::CSV)
-      bnode_map = {}
       bnode_gen = "_:a"
       CSV.generate(row_sep: "\r\n") do |csv|
         csv << variable_names.to_a
@@ -134,8 +154,12 @@ module SPARQL
                 bnode_gen = bnode_gen.succ
                 this
               end
+            when RDF::Statement
+              RDF::Query::Solutions(
+                RDF::Query::Solution.new(subject: term.subject, predicate: term.predicate, object: term.object)
+              ).to_csv(bnode_map: bnode_map).split.last.strip
             else
-              solution[n].to_s
+              solution[n].to_s.strip
             end
           end
         end
@@ -144,11 +168,9 @@ module SPARQL
     ##
     # Generate Solutions as TSV
     # @return [String]
-    # @see http://www.w3.org/TR/rdf-sparql-json-res/#results
+    # @see https://www.w3.org/TR/2013/REC-sparql11-results-csv-tsv-20130321/
     def to_tsv
       require 'csv' unless defined?(::CSV)
-      bnode_map = {}
-      bnode_gen = "_:a"
       results = [
         variable_names.map {|v| "?#{v}"}.join("\t")
       ] + self.map do |solution|
@@ -156,10 +178,15 @@ module SPARQL
           case term = solution[n]
           when RDF::Literal::Integer, RDF::Literal::Decimal, RDF::Literal::Double
             term.canonicalize.to_s
+          when RDF::Statement
+            emb_stmt = RDF::Query::Solutions(
+              RDF::Query::Solution.new(subject: term.subject, predicate: term.predicate, object: term.object)
+            ).to_tsv.split("\n").last.strip
+            emb_stmt.gsub(/[\t\n\r]/, "\t" => '\t', "\n" => '\n', "\r" => '\r')
           when nil
             ""
           else
-            RDF::NTriples.serialize(term)
+            RDF::NTriples.serialize(term).strip.gsub(/[\t\n\r]/, "\t" => '\t', "\n" => '\n', "\r" => '\r')
           end
         end.join("\t")
       end
@@ -226,7 +253,7 @@ module SPARQL
     when RDF::Queryable
       begin
         require 'linkeddata'
-      rescue LoadError => e
+      rescue LoadError
         require 'rdf/ntriples'
       end
       fmt = RDF::Format.for(format ? format.to_sym : {content_type: content_type})
@@ -280,7 +307,7 @@ module SPARQL
   # @param [Array<String>] available
   # @return [String]
   #
-  # @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+  # @see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
   def first_content_type(acceptable, available)
     return acceptable.first if available.empty?
     available.flatten!