Class: RDF::N3::Writer

Inherits:
Writer
  • Object
show all
Includes:
Terminals, Util::Logger
Defined in:
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

Constants included from Terminals

Terminals::ANON, Terminals::BASE, Terminals::BLANK_NODE_LABEL, Terminals::DECIMAL, Terminals::DOUBLE, Terminals::ECHAR, Terminals::ESCAPE_CHAR4, Terminals::ESCAPE_CHAR8, Terminals::EXPONENT, Terminals::INTEGER, Terminals::IPLSTART, Terminals::IRIREF, Terminals::IRI_RANGE, Terminals::LANGTAG, Terminals::PERCENT, Terminals::PLX, Terminals::PNAME_LN, Terminals::PNAME_NS, Terminals::PN_CHARS, Terminals::PN_CHARS_BASE, Terminals::PN_CHARS_BODY, Terminals::PN_CHARS_U, Terminals::PN_LOCAL, Terminals::PN_LOCAL_BODY, Terminals::PN_LOCAL_ESC, Terminals::PN_PREFIX, Terminals::PREFIX, Terminals::QUICK_VAR_NAME, Terminals::STRING_LITERAL_LONG_QUOTE, Terminals::STRING_LITERAL_LONG_SINGLE_QUOTE, Terminals::STRING_LITERAL_QUOTE, Terminals::STRING_LITERAL_SINGLE_QUOTE, Terminals::UCHAR, Terminals::U_CHARS1, Terminals::U_CHARS2, Terminals::WS

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Initializes the N3 writer instance.

Parameters:

  • (defaults to: $stdout)

    the output stream

  • 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

  • :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:

  • writer (RDF::Writer)
  • writer (RDF::Writer)

Yield Returns:

  • (void) 


110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/rdf/n3/writer.rb', line 110

def initialize(output = $stdout, **options, &block)
  @repo = RDF::N3::Repository.new
  @uri_to_pname = {}
  @uri_to_prefix = {}
  super do
    if base_uri
      @uri_to_prefix[base_uri.to_s.end_with?('#', '/') ? base_uri : RDF::URI("#{base_uri}#")] = nil
    end
    reset
    if block_given?
      case block.arity
        when 0 then instance_eval(&block)
        else block.call(self)
      end
    end
  end
end

Instance Attribute Details

#formula_names ⇒ Array<RDF::Node>

Returns formulae names.

Returns:

  • formulae names



62
63
64
 
# File 'lib/rdf/n3/writer.rb', line 62

def formula_names
  @formula_names
end

#graph ⇒ RDF::Graph

Returns Graph being serialized.

Returns:

  • Graph being serialized



59
60
61
 
# File 'lib/rdf/n3/writer.rb', line 59

def graph
  @graph
end

#repo ⇒ RDF::Repository

Returns Repository of statements serialized.

Returns:

  • Repository of statements serialized



56
57
58
 
# File 'lib/rdf/n3/writer.rb', line 56

def repo
  @repo
end

Class Method Details

.options ⇒ Object

N3 Writer options

See Also:



67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/rdf/n3/writer.rb', line 67

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:



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/rdf/n3/writer.rb', line 271

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
      %w(true false).include?(literal.value) ? literal.value : literal.canonicalize.to_s
    when RDF::XSD.integer
      literal.value.match?(/^[\+\-]?\d+$/) && !canonicalize? ? literal.value : literal.canonicalize.to_s
    when RDF::XSD.decimal
      literal.value.match?(/^[\+\-]?\d+\.\d+?$/) && !canonicalize? ?
        literal.value :
        literal.canonicalize.to_s
    when RDF::XSD.double
      if literal.nan? || literal.infinite?
        quoted(literal.value) + "^^#{format_uri(literal.datatype)}"
      else
        in_form = case literal.value
        when /[\+\-]?\d+\.\d*E[\+\-]?\d+$/i then true
        when /[\+\-]?\.\d+E[\+\-]?\d+$/i    then true
        when /[\+\-]?\d+E[\+\-]?\d+$/i      then true
        else false
        end && !canonicalize?

        in_form ? literal.value : literal.canonicalize.to_s.sub('E', 'e')
      end
    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:



326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/rdf/n3/writer.rb', line 326

def format_node(node, **options)
  if node.id.match(/^([^_]+)_[^_]+_([^_]+)$/)
    sn, seq = $1, $2.to_i
    seq = nil if seq == 0
    "_:#{sn}#{seq}"
  elsif options[:unique_bnodes]
    node.to_unique_base
  else
    node.to_base
  end
end

#format_uri(uri, **options) ⇒ String

Returns the N3 representation of a URI reference.

Parameters:

Returns:



314
315
316
317
318
 
# File 'lib/rdf/n3/writer.rb', line 314

def format_uri(uri, **options)
  md = uri == base_uri ? '' : 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:

  • value to use to identify URI



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
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/rdf/n3/writer.rb', line 203

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.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 = PNAME_LN.match(pname) || PNAME_NS.match(pname)
    pname = nil unless md.to_s.length == pname.length
  end

  @uri_to_pname[uri] = pname
end

#sort_properties(properties) ⇒ Array<RDF::Term>

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

Parameters:

  • A hash of Property to Resource mappings

Returns:

  • ] Ordered list of properties. Uses predicate_order.



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/rdf/n3/writer.rb', line 248

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

  predicate_order.each do |prop|
    next unless properties.key?(prop)
    prop_list << prop
  end

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

  prop_list
end

#write_epilogue ⇒ void

This method returns an undefined value.

Outputs the N3 representation of all stored triples.

See Also:



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
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/rdf/n3/writer.rb', line 157

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

  self.reset

  log_debug("\nserialize: repo:") {repo.size}

  preprocess

  start_document

  @formula_names = repo.graph_names(unique: true)

  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
    formula_names.each do |graph_name|
      next if graph_done?(graph_name)

      # Add graph_name to @formulae
      @formulae[graph_name] = true

      log_debug {"formula(#{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) ⇒ void

This method returns an undefined value.

Adds a quad to be serialized

Parameters:



147
148
149
150
 
# File 'lib/rdf/n3/writer.rb', line 147

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) ⇒ void

This method is abstract.

This method returns an undefined value.

Addes a triple to be serialized

Parameters:

Raises:

  • unless implemented in subclass



136
137
138
 
# File 'lib/rdf/n3/writer.rb', line 136

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