Class: RDF::N3::Writer

Inherits:
Writer show all
Includes:
Util::Logger
Defined in:
vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb

Overview

A Notation-3 serialiser in Ruby

Note that the natural interface is to write a whole graph at a time. Writing statements or Triples will create a graph to add them to and then serialize the graph.

The writer will add prefix definitions, and use them for creating @prefix definitions, and minting pnames

Examples:

Obtaining a N3 writer class

RDF::Writer.for(:n3)         #=> RDF::N3::Writer
RDF::Writer.for("etc/test.n3")
RDF::Writer.for(file_name:      "etc/test.n3")
RDF::Writer.for(file_extension: "n3")
RDF::Writer.for(content_type:   "text/n3")

Serializing RDF graph into an N3 file

RDF::N3::Writer.open("etc/test.n3") do |writer|
  writer << graph
end

Serializing RDF statements into an N3 file

RDF::N3::Writer.open("etc/test.n3") do |writer|
  graph.each_statement do |statement|
    writer << statement
  end
end

Serializing RDF statements into an N3 string

RDF::N3::Writer.buffer do |writer|
  graph.each_statement do |statement|
    writer << statement
  end
end

Creating @base and @prefix definitions in output

RDF::N3::Writer.buffer(base_uri: "http://example.com/", prefixes: {
    nil => "http://example.com/ns#",
    foaf: "http://xmlns.com/foaf/0.1/"}
) do |writer|
  graph.each_statement do |statement|
    writer << statement
  end
end

Author:

Constant Summary collapse

QNAME =
Meta::REGEXPS[:"http://www.w3.org/2000/10/swap/grammar/n3#qname"]

Constants included from Util::Logger

Util::Logger::IOWrapper

Instance Attribute Summary collapse

Attributes inherited from Writer

#options

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Logger

#log_debug, #log_depth, #log_error, #log_fatal, #log_info, #log_recover, #log_recovering?, #log_statistics, #log_warn, #logger

Methods inherited from Writer

accept?, #base_uri, buffer, #canonicalize?, dump, each, #encoding, #escaped, #flush, for, format, #format_list, #format_term, #node_id, open, #prefix, #prefixes, #prefixes=, #puts, to_sym, #to_sym, #uri_for, #validate?, #write_comment, #write_prologue, #write_statement, #write_triples

Methods included from Util::Aliasing::LateBound

#alias_method

Methods included from Writable

#<<, #insert, #insert_graph, #insert_reader, #insert_statement, #insert_statements, #writable?

Constructor Details

#initialize(output = $stdout, options = {}) {|writer| ... } ⇒ Writer

Initializes the N3 writer instance.

Parameters:

  • output (IO, File) (defaults to: $stdout)

    the output stream

  • options (Hash{Symbol => Object}) (defaults to: {})

    any additional options

Options Hash (options):

  • :encoding (Encoding) — default: Encoding::UTF_8

    the encoding to use on the output stream (Ruby 1.9+)

  • :canonicalize (Boolean) — default: false

    whether to canonicalize literals when serializing

  • :prefixes (Hash) — default: Hash.new

    the prefix mappings to use (not supported by all writers)

  • :base_uri (#to_s) — default: nil

    the base URI to use when constructing relative URIs

  • :max_depth (Integer) — default: 3

    Maximum depth for recursively defining resources, defaults to 3

  • :standard_prefixes (Boolean) — default: false

    Add standard prefixes to @prefixes, if necessary.

  • :default_namespace (String) — default: nil

    URI to use as default namespace, same as prefixes[nil]

  • :unique_bnodes (Boolean) — default: false

    Use unique node identifiers, defaults to using the identifier which the node was originall initialized with (if any).

Yields:

  • (writer)

    self

  • (writer)

Yield Parameters:

Yield Returns:

  • (void)


106
107
108
109
110
111
112
113
114
115
116
117
118
119
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 106

def initialize(output = $stdout, options = {}, &block)
  @repo = RDF::Repository.new
  @uri_to_pname = {}
  @uri_to_prefix = {}
  super do
    reset
    if block_given?
      case block.arity
        when 0 then instance_eval(&block)
        else block.call(self)
      end
    end
  end
end

Instance Attribute Details

#graphRDF::Graph

Returns Graph being serialized

Returns:



58
59
60
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 58

def graph
  @graph
end

#repoRDF::Repository

Returns Repository of statements serialized

Returns:



55
56
57
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 55

def repo
  @repo
end

Class Method Details

.optionsObject

N3 Writer options



63
64
65
66
67
68
69
70
71
72
73
74
75
76
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 63

def self.options
  super + [
    RDF::CLI::Option.new(
      symbol: :max_depth,
      datatype: Integer,
      on: ["--max-depth"],
      description: "Maximum depth for recursively defining resources, defaults to 3.") {|arg| arg.to_i},
    RDF::CLI::Option.new(
      symbol: :default_namespace,
      datatype: RDF::URI,
      on: ["--default-namespace URI", :REQUIRED],
      description: "URI to use as default namespace, same as prefixes.") {|arg| RDF::URI(arg)},
  ]
end

Instance Method Details

#format_literal(literal, options = {}) ⇒ String

Returns the N-Triples representation of a literal.

Parameters:

Returns:



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 262

def format_literal(literal, options = {})
  literal = literal.dup.canonicalize! if @options[:canonicalize]
  case literal
  when RDF::Literal
    case literal.valid? ? literal.datatype : false
    when RDF::XSD.boolean, RDF::XSD.integer, RDF::XSD.decimal
      literal.canonicalize.to_s
    when RDF::XSD.double
      literal.canonicalize.to_s.sub('E', 'e')  # Favor lower case exponent
    else
      text = quoted(literal.value)
      text << "@#{literal.language}" if literal.has_language?
      text << "^^#{format_uri(literal.datatype)}" if literal.has_datatype?
      text
    end
  else
    quoted(literal.to_s)
  end
end

#format_node(node, options = {}) ⇒ String

Returns the N3 representation of a blank node.

Parameters:

Returns:



300
301
302
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 300

def format_node(node, options = {})
  options[:unique_bnodes] ? node.to_unique_base : node.to_base
end

#format_uri(uri, options = {}) ⇒ String

Returns the N3 representation of a URI reference.

Parameters:

Returns:



288
289
290
291
292
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 288

def format_uri(uri, options = {})
  md = uri.relativize(base_uri)
  log_debug("relativize") {"#{uri.to_sxp} => #{md.inspect}"} if md != uri.to_s
  md != uri.to_s ? "<#{md}>" : (get_pname(uri) || "<#{uri}>")
end

#get_pname(resource) ⇒ String?

Return a pname for the URI, or nil. Adds namespace of pname to defined prefixes

Parameters:

Returns:

  • (String, nil)

    value to use to identify URI



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 191

def get_pname(resource)
  case resource
  when RDF::Node
    return options[:unique_bnodes] ? resource.to_unique_base : resource.to_base
  when RDF::URI
    uri = resource.to_s
  else
    return nil
  end

  #log_debug {"get_pname(#{resource}), std?}"}
  pname = case
  when @uri_to_pname.has_key?(uri)
    return @uri_to_pname[uri]
  when u = @uri_to_prefix.keys.detect {|u| uri.index(u.to_s) == 0}
    # Use a defined prefix
    prefix = @uri_to_prefix[u]
    unless u.to_s.empty?
      prefix(prefix, u) unless u.to_s.empty?
      #log_debug("get_pname") {"add prefix #{prefix.inspect} => #{u}"}
      uri.sub(u.to_s, "#{prefix}:")
    end
  when @options[:standard_prefixes] && vocab = RDF::Vocabulary.each.to_a.detect {|v| uri.index(v.to_uri.to_s) == 0}
    prefix = vocab.__name__.to_s.split('::').last.downcase
    @uri_to_prefix[vocab.to_uri.to_s] = prefix
    prefix(prefix, vocab.to_uri) # Define for output
    #log_debug {"get_pname: add standard prefix #{prefix.inspect} => #{vocab.to_uri}"}
    uri.sub(vocab.to_uri.to_s, "#{prefix}:")
  else
    nil
  end

  # Make sure pname is a valid pname
  if pname
    md = QNAME.match(pname)
    pname = nil unless md.to_s.length == pname.length
  end

  @uri_to_pname[uri] = pname
rescue Addressable::URI::InvalidURIError => e
  raise RDF::WriterError, "Invalid URI #{resource.inspect}: #{e.message}"
end

#indent(modifier = 0) ⇒ String (protected)

Returns indent string multiplied by the depth

Parameters:

  • modifier (Integer) (defaults to: 0)

    Increase depth by specified amount

Returns:

  • (String)

    A number of spaces, depending on current depth



436
437
438
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 436

def indent(modifier = 0)
  " " * (@options.fetch(:log_depth, log_depth) * 2 + modifier)
end

#order_subjectsArray<Resource> (protected)

Order subjects for output. Override this to output subjects in another order.

Uses #top_classes and #base_uri.

Returns:



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 340

def order_subjects
  seen = {}
  subjects = []

  # Start with base_uri
  if base_uri && @subjects.keys.include?(base_uri)
    subjects << base_uri
    seen[base_uri] = true
  end

  # Add distinguished classes
  top_classes.each do |class_uri|
    graph.query(predicate: RDF.type, object: class_uri).
      map {|st| st.subject}.
      sort.
      uniq.
      each do |subject|
      log_debug("order_subjects") {subject.to_sxp}
      subjects << subject
      seen[subject] = true
    end
  end

  # Mark as seen lists that are part of another list
  @lists.values.map(&:statements).
    flatten.each do |st|
      seen[st.object] = true if @lists.has_key?(st.object)
    end

  # List elements which are bnodes should not be targets for top-level serialization
  list_elements = @lists.values.map(&:to_a).flatten.select(&:node?).compact

  # Sort subjects by resources over bnodes, ref_counts and the subject URI itself
  recursable = (@subjects.keys - list_elements).
    select {|s| !seen.include?(s)}.
    map {|r| [r.node? ? 1 : 0, ref_count(r), r]}.
    sort

  subjects += recursable.map{|r| r.last}
end

#predicate_orderArray<URI> (protected)

Defines order of predicates to to emit at begninning of a resource description. Defaults to [rdf:type, rdfs:label, dc:title]

Returns:



334
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 334

def predicate_order; [RDF.type, RDF::RDFS.label, RDF::URI("http://purl.org/dc/terms/title")]; end

#preprocessObject (protected)

Perform any preprocessing of statements required



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 382

def preprocess
  # Load defined prefixes
  (@options[:prefixes] || {}).each_pair do |k, v|
    @uri_to_prefix[v.to_s] = k
  end
  @options[:prefixes] = {}  # Will define actual used when matched

  prefix(nil, @options[:default_namespace]) if @options[:default_namespace]

  @options[:prefixes] = {}  # Will define actual used when matched
  repo.each {|statement| preprocess_statement(statement)}

  vars = repo.enum_term.to_a.uniq.select {|r| r.is_a?(RDF::Query::Variable)}
  @universals = vars.reject(&:existential?)
  @existentials = vars - @universals
end

#preprocess_graph_statement(statement) ⇒ Object (protected)

Perform graph-specific preprocessing

Parameters:



414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 414

def preprocess_graph_statement(statement)
  bump_reference(statement.object)
  # Count properties of this subject
  @subjects[statement.subject] ||= {}
  @subjects[statement.subject][statement.predicate] ||= 0
  @subjects[statement.subject][statement.predicate] += 1

  # Collect lists
  if statement.predicate == RDF.first
    l = RDF::List.new(subject: statement.subject, graph: graph)
    @lists[statement.subject] = l if l.valid?
  end

  if statement.object == RDF.nil || statement.subject == RDF.nil
    # Add an entry for the list tail
    @lists[RDF.nil] ||= RDF::List[]
  end
end

#preprocess_statement(statement) ⇒ Object (protected)

Perform any statement preprocessing required. This is used to perform reference counts and determine required prefixes.

Parameters:



402
403
404
405
406
407
408
409
410
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 402

def preprocess_statement(statement)
  #log_debug {"preprocess: #{statement.inspect}"}

  # Pre-fetch pnames, to fill prefixes
  get_pname(statement.subject)
  get_pname(statement.predicate)
  get_pname(statement.object)
  get_pname(statement.object.datatype) if statement.object.literal? && statement.object.datatype
end

#quoted(string) ⇒ String (protected)

Use single- or multi-line quotes. If literal contains \t, \n, or \r, use a multiline quote, otherwise, use a single-line

Parameters:

Returns:



455
456
457
458
459
460
461
462
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 455

def quoted(string)
  if string.to_s.match(/[\t\n\r]/)
    string = string.gsub('\\', '\\\\\\\\').gsub('"""', '\\"\\"\\"')
    %("""#{string}""")
  else
    "\"#{escaped(string)}\""
  end
end

#resetObject (protected)

Reset internal helper instance variables



441
442
443
444
445
446
447
448
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 441

def reset
  @universals, @existentials = [], []
  @lists = {}
  @references = {}
  @serialized = {}
  @graphs = {}
  @subjects = {}
end

#sort_properties(properties) ⇒ Array<String>

Take a hash from predicate uris to lists of values. Sort the lists of values. Return a sorted list of properties.

Parameters:

Returns:

  • (Array<String>)

    ] Ordered list of properties. Uses predicate_order.



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 238

def sort_properties(properties)
  # Make sorted list of properties
  prop_list = []

  predicate_order.each do |prop|
    next unless properties[prop.to_s]
    prop_list << prop.to_s
  end

  properties.keys.sort.each do |prop|
    next if prop_list.include?(prop.to_s)
    prop_list << prop.to_s
  end

  log_debug {"sort_properties: #{prop_list.join(', ')}"}
  prop_list
end

#start_documentObject (protected)

Output @base and @prefix definitions



306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 306

def start_document
  @output.write("@base <#{base_uri}> .\n") unless base_uri.to_s.empty?

  log_debug {"start_document: prefixes #{prefixes.inspect}"}
  prefixes.keys.sort_by(&:to_s).each do |prefix|
    @output.write("@prefix #{prefix}: <#{prefixes[prefix]}> .\n")
  end

  unless @universals.empty?
    log_debug {"start_document: universals #{@universals.inspect}"}
    terms = @universals.map {|v| format_uri(RDF::URI(v.name.to_s))}
    @output.write("@forAll #{terms.join(', ')} .\n") 
  end

  unless @existentials.empty?
    log_debug {"start_document: universals #{@existentials.inspect}"}
    terms = @existentials.map {|v| format_uri(RDF::URI(v.name.to_s))}
    @output.write("@forSome #{terms.join(', ')} .\n") 
  end
end

#top_classesArray<URI> (protected)

Defines rdf:type of subjects to be emitted at the beginning of the graph. Defaults to rdfs:Class

Returns:



329
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 329

def top_classes; [RDF::RDFS.Class]; end

#write_epilogue

This method returns an undefined value.

Outputs the N3 representation of all stored triples.

See Also:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 150

def write_epilogue
  @max_depth = @options[:max_depth] || 3

  self.reset

  log_debug {"\nserialize: repo: #{repo.size}"}

  preprocess

  start_document

  with_graph(nil) do
    count = 0
    order_subjects.each do |subject|
      unless is_done?(subject)
        statement(subject, count)
        count += 1
      end
    end

    # Output any formulae not already serialized using owl:sameAs
    repo.graph_names.each do |graph_name|
      next if graph_done?(graph_name)

      log_debug {"named graph(#{graph_name})"}
      @output.write("\n#{indent}")
      p_term(graph_name, :subject)
      @output.write(" ")
      predicate(RDF::OWL.sameAs)
      @output.write(" ")
      formula(graph_name, :graph_name)
      @output.write(" .\n")
    end
  end

  super
end

#write_quad(subject, predicate, object, graph_name)

This method returns an undefined value.

Adds a quad to be serialized

Parameters:



140
141
142
143
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 140

def write_quad(subject, predicate, object, graph_name)
  statement = RDF::Statement.new(subject, predicate, object, graph_name: graph_name)
  repo.insert(statement)
end

#write_triple(subject, predicate, object)

This method is abstract.

This method returns an undefined value.

Addes a triple to be serialized

Parameters:

Raises:

  • (NotImplementedError)

    unless implemented in subclass



129
130
131
# File 'vendor/bundler/ruby/2.6.0/bundler/gems/rdf-n3-015ce184efe3/lib/rdf/n3/writer.rb', line 129

def write_triple(subject, predicate, object)
  repo.insert(RDF::Statement(subject, predicate, object))
end