rdf_context 0.5.6 → 0.5.7

Sign up to get free protection for your applications and to get access to all the features.
Files changed (44) hide show
  1. data/.yardopts +10 -0
  2. data/{History.txt → History.rdoc} +8 -1
  3. data/Rakefile +9 -2
  4. data/VERSION +1 -1
  5. data/bin/rdf_context +5 -2
  6. data/lib/rdf_context/aggregate_graph.rb +31 -2
  7. data/lib/rdf_context/array_hacks.rb +3 -3
  8. data/lib/rdf_context/bnode.rb +3 -3
  9. data/lib/rdf_context/conjunctive_graph.rb +8 -8
  10. data/lib/rdf_context/duration.rb +17 -4
  11. data/lib/rdf_context/graph.rb +84 -46
  12. data/lib/rdf_context/literal.rb +36 -3
  13. data/lib/rdf_context/n3parser.rb +4 -4
  14. data/lib/rdf_context/namespace.rb +21 -8
  15. data/lib/rdf_context/parser.rb +31 -16
  16. data/lib/rdf_context/quoted_graph.rb +5 -4
  17. data/lib/rdf_context/rdfaparser.rb +176 -91
  18. data/lib/rdf_context/rdfxmlparser.rb +50 -13
  19. data/lib/rdf_context/serializer/abstract_serializer.rb +14 -4
  20. data/lib/rdf_context/serializer/nt_serializer.rb +5 -0
  21. data/lib/rdf_context/serializer/recursive_serializer.rb +4 -0
  22. data/lib/rdf_context/serializer/turtle_serializer.rb +28 -27
  23. data/lib/rdf_context/serializer/xml_serializer.rb +11 -9
  24. data/lib/rdf_context/store/abstract_sql_store.rb +47 -4
  25. data/lib/rdf_context/store/abstract_store.rb +73 -1
  26. data/lib/rdf_context/store/list_store.rb +25 -6
  27. data/lib/rdf_context/store/memory_store.rb +33 -1
  28. data/lib/rdf_context/store/sqlite3_store.rb +7 -4
  29. data/lib/rdf_context/term_utils.rb +6 -0
  30. data/lib/rdf_context/triple.rb +17 -6
  31. data/lib/rdf_context/uriref.rb +19 -3
  32. data/spec/html4-manifest.yml +176 -176
  33. data/spec/html5-manifest.yml +176 -176
  34. data/spec/rdfa_helper.rb +8 -2
  35. data/spec/rdfa_parser_spec.rb +1 -1
  36. data/spec/rdfcore/Manifest.yml +1561 -2626
  37. data/spec/swap_test/n3parser.yml +134 -279
  38. data/spec/swap_test/regression.yml +140 -305
  39. data/spec/turtle/manifest-bad.yml +155 -310
  40. data/spec/turtle/manifest.yml +155 -310
  41. data/spec/xhtml-manifest.yml +139 -587
  42. data/spec/xhtml11-manifest.yml +4405 -0
  43. metadata +21 -7
  44. data/.gitmodules +0 -3
data/.yardopts ADDED
@@ -0,0 +1,10 @@
1
+ --title "RDF::RDFa - XHTML+RDFa Support for RDF.rb"
2
+ --output-dir doc/yard
3
+ --protected
4
+ --no-private
5
+ --hide-void-return
6
+ --markup rdoc
7
+ --readme README.rdoc
8
+ -
9
+ History.rdoc
10
+ VERSION
data/{History.txt → History.rdoc} RENAMED
@@ -1,3 +1,10 @@
1
+ === 0.5.7
2
+ * Add back support for RDFa 1.0 as well as RDFa 1.1. Parser checks @version to determine which
3
+ * Remove specs for html4 and html5 until sorted out.
4
+ * Don't allow _ as a prefix name.
5
+ * Don't emit non-URI predicate values
6
+ * Use sqlite3-ruby version 1.2.5, as 1.3.1 breaks multiple argument execs.
7
+
1
8
  === 0.5.6
2
9
  * Remove trailing ' in #encoding for treetop grammer, which caused problems installing rdoc in ruby 1.9.
3
10
  * Fixed corner case in RDFa parser where document doesn't exist, which was raising an error.
@@ -45,7 +52,7 @@
45
52
  === 0.5.0
46
53
  * Support for Ruby 1.9, 1.8.7 and 1.8.6.
47
54
  * Unicode escapes and URIRefs only work properly in Ruby 1.9
48
- * Replaced some (&:meth) spells with {|c| c.meth} for Ruby 1.8.6 compatibility
55
+ * Replaced some <code>(&:meth)</code> spells with <code>{|c| c.meth}</code> for Ruby 1.8.6 compatibility
49
56
  * Fully compliant N3 parser (n3-rdf level) with extnensive tests, including SWAP, CWM and Turtle test suites.
50
57
  * Supports paths, keywords, all semantic expressions.
51
58
  * No support yet for Formulae, variables, rules or automatic reification
data/Rakefile CHANGED
@@ -1,4 +1,6 @@
1
1
  require 'rubygems'
2
+ require 'yard'
3
+
2
4
  begin
3
5
  gem 'jeweler'
4
6
  require 'jeweler'
@@ -28,6 +30,7 @@ begin
28
30
  gemspec.add_dependency('patron', '>= 0.4.6')
29
31
  gemspec.add_development_dependency('rspec')
30
32
  gemspec.add_development_dependency('activesupport', '>= 2.3.0')
33
+ gemspec.add_development_dependency('yard')
31
34
  gemspec.extra_rdoc_files = %w(README.rdoc History.txt)
32
35
  end
33
36
  Jeweler::GemcutterTasks.new
@@ -78,10 +81,14 @@ Rake::RDocTask.new("doc:rdoc") do |rdoc|
78
81
 
79
82
  rdoc.rdoc_dir = 'doc/rdoc'
80
83
  rdoc.title = "rdf_context #{version}"
81
- rdoc.rdoc_files.include('README*', "History.txt")
84
+ rdoc.rdoc_files.include('README*', "History.rdoc")
82
85
  rdoc.rdoc_files.include('lib/**/*.rb')
83
86
  end
84
87
 
88
+ YARD::Rake::YardocTask.new do |t|
89
+ t.files = %w(lib/**/*.rb README.rdoc History.rdoc) # optional
90
+ end
91
+
85
92
  desc "Generate RDF Core Manifest.yml"
86
93
  namespace :spec do
87
94
  task :prepare do
@@ -91,7 +98,7 @@ namespace :spec do
91
98
  require 'spec/rdf_helper'
92
99
  require 'fileutils'
93
100
 
94
- %w(xhtml html4 html5).each do |suite|
101
+ %w(xhtml xhtml11 html4 html5).each do |suite|
95
102
  yaml = manifest_file = File.join(File.dirname(__FILE__), "spec", "#{suite}-manifest.yml")
96
103
  FileUtils.rm_f(yaml)
97
104
  RdfaHelper::TestCase.to_yaml(suite, yaml)
data/VERSION CHANGED
@@ -1 +1 @@
1
- 0.5.6
1
+ 0.5.7
data/bin/rdf_context CHANGED
@@ -50,7 +50,7 @@ def rdfa_tc(number, parse, store)
50
50
  head = "" +
51
51
  %(<?xml version="1.0" encoding="UTF-8"?>\n) +
52
52
  %(<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">\n) +
53
- %(<html xmlns="http://www.w3.org/1999/xhtml" version="XHTML+RDFa 1.1"\n)
53
+ %(<html xmlns="http://www.w3.org/1999/xhtml" version="XHTML+RDFa #{$rdfa_version}"\n)
54
54
  tc = head + "#{namespaces}>\n#{body.gsub(/\$TCPATH/, tcpath)}\n</html>"
55
55
 
56
56
  puts "Input file: #{tc}" if $DEBUG || $verbose
@@ -62,6 +62,7 @@ raise "Mode must be one of 'parse'" unless mode == "parse"
62
62
 
63
63
  $verbose = false
64
64
  $format = "ttl"
65
+ $rdfa_version = "1.1"
65
66
  base_uri = "http://example.com"
66
67
  store = :list_store
67
68
  opts = GetoptLong.new(
@@ -71,7 +72,8 @@ opts = GetoptLong.new(
71
72
  ["--format", GetoptLong::REQUIRED_ARGUMENT],
72
73
  ["--store", GetoptLong::REQUIRED_ARGUMENT],
73
74
  ["--uri", GetoptLong::REQUIRED_ARGUMENT],
74
- ["--rdfa", GetoptLong::NO_ARGUMENT]
75
+ ["--rdfa", GetoptLong::NO_ARGUMENT],
76
+ ["--1_0", GetoptLong::NO_ARGUMENT]
75
77
  )
76
78
  opts.each do |opt, arg|
77
79
  case opt
@@ -81,6 +83,7 @@ opts.each do |opt, arg|
81
83
  when '--format' then $format = arg
82
84
  when '--uri' then base_uri = arg
83
85
  when '--rdfa' then $rdfa = true
86
+ when '--1_0' then $rdfa_version = "1.0"
84
87
  when '--store'
85
88
  case arg
86
89
  when /list/
data/lib/rdf_context/aggregate_graph.rb CHANGED
@@ -5,48 +5,68 @@ module RdfContext
5
5
  #
6
6
  # Essentially a ConjunctiveGraph over an explicit subset of the entire store.
7
7
  class AggregateGraph < Graph
8
+ # List of constituent graphs
9
+ # @return [Array<Graph>]
8
10
  attr_reader :graphs
9
11
 
10
12
  # List of graphs to aggregate
13
+ # @param [Array<Graph>] graph List of constituent graphs
11
14
  def initialize(*graph)
12
15
  @graphs = graph
13
16
  end
14
17
 
18
+ # @raise [ReadOnlyGraphException]
15
19
  def destroy(configuration = nil); raise ReadOnlyGraphException; end
20
+ # @raise [ReadOnlyGraphException]
16
21
  def commit; raise ReadOnlyGraphException; end
22
+ # @raise [ReadOnlyGraphException]
17
23
  def rollback; raise ReadOnlyGraphException; end
24
+ # @raise [ReadOnlyGraphException]
18
25
  def add; raise ReadOnlyGraphException; end
26
+ # @raise [ReadOnlyGraphException]
19
27
  def remove; raise ReadOnlyGraphException; end
28
+ # @param [Namespace] namespace
29
+ # @raise [ReadOnlyGraphException]
20
30
  def bind(namespace); raise ReadOnlyGraphException; end
31
+ # @param [#read, #to_s] stream
32
+ # @param [URIRef, String] uri
33
+ # @raise [ReadOnlyGraphException]
21
34
  def parse(stream, uri, options = {}); raise ReadOnlyGraphException; end
35
+ # @raise [ReadOnlyGraphException]
22
36
  def n3; raise ReadOnlyGraphException; end
23
37
 
24
38
  # Open the graphs
39
+ # @return [void]
25
40
  def open(configuration = {})
26
41
  @graphs.each {|g| g.open(configuration)}
27
42
  end
28
43
 
29
44
  # Close the graphs
45
+ # @return [void]
30
46
  def close(configuration = {})
31
47
  @graphs.each {|g| g.close(configuration)}
32
48
  end
33
49
 
34
50
  # Number of Triples in the graph
51
+ # @return [Integer]
35
52
  def size
36
53
  @graphs.inject(0) {|memo, g| memo += g.size}
37
54
  end
38
55
 
39
56
  # List of distinct subjects in graph
57
+ # @return [Array<Resource>]
40
58
  def subjects
41
59
  @graphs.inject([]) {|memo, g| memo += g.subjects}
42
60
  end
43
61
 
44
62
  # List of distinct predicates in graph
63
+ # @return [Array<Resource>]
45
64
  def predicates
46
65
  @graphs.inject([]) {|memo, g| memo += g.predicates}
47
66
  end
48
67
 
49
68
  # List of distinct objects in graph
69
+ # @return [Array<Resource>]
50
70
  def objects
51
71
  @graphs.inject([]) {|memo, g| memo += g.objects}
52
72
  end
@@ -54,31 +74,40 @@ module RdfContext
54
74
  # Triples from graph, optionally matching subject, predicate, or object.
55
75
  # Delegates to Store#triples.
56
76
  #
57
- # @param [Triple, nil] triple:: Triple to match, may be a pattern triple or nil
58
- # @return [Array]:: List of matched triples
77
+ # @param [Triple] triple (Triple.new) Triple to match, may be a pattern triple or nil
78
+ # @yield [triple, context]
79
+ # @yieldparam [Triple] triple
80
+ # @yieldparam [Resource] context
81
+ # @return [Array<Triple>] List of matched triples
59
82
  def triples(triple = Triple.new(nil, nil, nil), &block) # :yields: triple, context
60
83
  @graphs.inject([]) {|memo, g| memo += g.triples(triple, &block)}
61
84
  end
62
85
 
63
86
  # Check to see if this graph contains the specified triple
87
+ # @param [Triple] triple Triple to match, may be a pattern triple or nil
64
88
  def contains?(triple)
65
89
  @graphs.any? {|g| g.contains?(triple) }
66
90
  end
67
91
 
68
92
  # Get all BNodes with usage count used within graph
93
+ # @return [Array<BNode>]
69
94
  def bnodes
70
95
  @graphs.inject([]) {|memo, g| memo += g.bnodes}
71
96
  end
72
97
 
73
98
  # Only compares to another AggregateGraph. Compares each sub-graph
99
+ # @param [AggregateGraph, Object] other Graph to compare with
100
+ # @return [Boolean]
74
101
  def eql?(other)
75
102
  other.is_a?(AggregateGraph) ? super : false
76
103
  end
77
104
 
105
+ # @return [Hash{String => Namespace}]
78
106
  def nsbinding
79
107
  @graphs.inject({}) {|memo, g| memo.merge(g.nsbinding)}
80
108
  end
81
109
 
110
+ # @return [Hash{URIRef => Namespace}]
82
111
  def uri_binding
83
112
  @graphs.inject({}) {|memo, g| memo.merge(g.uri_binding)}
84
113
  end
data/lib/rdf_context/array_hacks.rb CHANGED
@@ -15,9 +15,9 @@ class Array
15
15
  end
16
16
 
17
17
  # Converts the array to a comma-separated sentence where the last element is joined by the connector word. Options:
18
- # * <tt>:words_connector</tt> - The sign or word used to join the elements in arrays with two or more elements (default: ", ")
19
- # * <tt>:two_words_connector</tt> - The sign or word used to join the elements in arrays with two elements (default: " and ")
20
- # * <tt>:last_word_connector</tt> - The sign or word used to join the last element in arrays with three or more elements (default: ", and ")
18
+ # @option [String] :words_connector (", ") The sign or word used to join the elements in arrays with two or more elements
19
+ # @option [String] :two_words_connector (" and ") The sign or word used to join the elements in arrays with two elements
20
+ # @option [String] :last_word_connector (", ") The sign or word used to join the elements in arrays with two or more elements
21
21
  def to_sentence(options = {})
22
22
  default_words_connector = ", "
23
23
  default_two_words_connector = " and "
data/lib/rdf_context/bnode.rb CHANGED
@@ -13,8 +13,8 @@ module RdfContext
13
13
  # to lookup previoiusly defined BNodes using the same identifier. Names are *not* preserved
14
14
  # within the underlying storage model.
15
15
  #
16
- # @param [String] identifier:: Legal NCName or nil for a named BNode
17
- # @param [Hash] context:: Context used to store named BNodes
16
+ # @param [String] identifier (nil) Legal NCName or nil for a named BNode
17
+ # @param [Hash] context ({}) Context used to store named BNodes
18
18
  def initialize(identifier = nil, context = {})
19
19
  if identifier.nil?
20
20
  @identifier = generate_bn_identifier
@@ -38,7 +38,7 @@ module RdfContext
38
38
  # ==== Example
39
39
  # b = BNode.new; b.to_n3 # => returns a string of the BNode in n3 form
40
40
  #
41
- # @return [String]:: The BNode in n3.
41
+ # @return [String] The BNode in n3.
42
42
  #
43
43
  # @author Tom Morris
44
44
  def to_n3
data/lib/rdf_context/conjunctive_graph.rb CHANGED
@@ -36,8 +36,8 @@ module RdfContext
36
36
  # Triples across all contexts in store, optionally matching subject, predicate, or object.
37
37
  # Delegates to Store#triples.
38
38
  #
39
- # @param [Triple, nil] triple:: Triple to match, may be a pattern triple or nil
40
- # @return [Array]:: List of matched triples
39
+ # @param [Triple] triple (nil) Triple to match, may be a pattern triple or nil
40
+ # @return [Array] List of matched triples
41
41
  def triples(triple = Triple.new(nil, nil, nil), &block) # :yields: triple, context
42
42
  @store.triples(triple, nil, &block) || []
43
43
  end
@@ -46,13 +46,13 @@ module RdfContext
46
46
  #
47
47
  # Create a new context (Graph) and parse into that.
48
48
  #
49
- # @param [IO, String] stream:: the RDF IO stream, string, Nokogiri::HTML::Document or Nokogiri::XML::Document
50
- # @param [String] uri:: the URI of the document
49
+ # @param [IO, String] stream the RDF IO stream, string, Nokogiri::HTML::Document or Nokogiri::XML::Document
50
+ # @param [URIRef, String] uri the URI of the document
51
51
  # @param [Hash] options:: Options from
52
- # <em>options[:debug]</em>:: Array to place debug messages
53
- # <em>options[:type]</em>:: One of _rdfxml_, _html_, or _n3_
54
- # <em>options[:strict]</em>:: Raise Error if true, continue with lax parsing, otherwise
55
- # @return [Graph]:: Returns the graph containing parsed triples
52
+ # @option options [Array] :debug (nil) Array to place debug messages
53
+ # @option options [:rdfxml, :html, :n3] :type (nil)
54
+ # @option options [Boolean] :strict (false) Raise Error if true, continue with lax parsing, otherwise
55
+ # @return [Graph] Returns the graph containing parsed triples
56
56
  def parse(stream, uri, options = {}, &block) # :yields: triple
57
57
  graph = Graph.new(:identifier => uri, :store => self.store)
58
58
  Parser.parse(stream, uri, options.merge(:graph => graph), &block)
data/lib/rdf_context/duration.rb CHANGED
@@ -7,6 +7,8 @@ module RdfContext
7
7
  # * Given a time, extract second
8
8
  # * Given a Flaat, use value direcly
9
9
  # * Given a String, parse as xsd:duration
10
+ # @param [Integer, Time, Float, String] value (#to_i)
11
+ # @return [Duration]
10
12
  def initialize(value)
11
13
  case value
12
14
  when Hash
@@ -28,11 +30,15 @@ module RdfContext
28
30
  self.normalize
29
31
  end
30
32
 
33
+
34
+ # Reverse convert from XSD version of duration
35
+ # XSD allows -P1111Y22M33DT44H55M66.666S with any combination in regular order
36
+ # We assume 1M == 30D, but are out of spec in this regard
37
+ # We only output up to hours
38
+ #
39
+ # @param [String] value XSD formatted duration
40
+ # @return [Duration]
31
41
  def self.parse(value)
32
- # Reverse convert from XSD version of duration
33
- # XSD allows -P1111Y22M33DT44H55M66.666S with any combination in regular order
34
- # We assume 1M == 30D, but are out of spec in this regard
35
- # We only output up to hours
36
42
  if value.to_s.match(/^(-?)P(\d+Y)?(\d+M)?(\d+D)?T?(\d+H)?(\d+M)?([\d\.]+S)?$/)
37
43
  hash = {}
38
44
  hash[:ne] = $1 == "-" ? -1 : 1
@@ -48,11 +54,16 @@ module RdfContext
48
54
  self.new(value)
49
55
  end
50
56
 
57
+ # @return [Float]
51
58
  def to_f
52
59
  (((((@yr.to_i * 12 + @mo.to_i) * 30 + @da.to_i) * 24 + @hr.to_i) * 60 + @mi.to_i) * 60 + @se.to_f) * (@ne || 1)
53
60
  end
54
61
 
62
+ # @return [Integer]
55
63
  def to_i; Integer(self.to_f); end
64
+
65
+ # @param [Duration, String, Numeric] something (false)
66
+ # @return [Boolean]
56
67
  def eql?(something)
57
68
  case something
58
69
  when Duration
@@ -67,6 +78,8 @@ module RdfContext
67
78
  end
68
79
  alias_method :==, :eql?
69
80
 
81
+ # @param [Symbol] format Output format, :xml outputs in xmlschema mode, otherwise in Human form
82
+ # @return [String]
70
83
  def to_s(format = nil)
71
84
  usec = (@se * 1000).to_i % 1000
72
85
  sec_str = usec > 0 ? "%2.3f" % @se : @se.to_i.to_s
data/lib/rdf_context/graph.rb CHANGED
@@ -31,10 +31,9 @@ module RdfContext
31
31
  # by name. If none is given, the graph is assigned a BNode for it's identifier.
32
32
  # For more on named graphs, see: http://en.wikipedia.org/wiki/RDFLib
33
33
  #
34
- # @param [Hash] options:: Options
35
- # <em>options[:store]</em>:: storage, defaults to a new ListStore instance. May be symbol :list_store or :memory_store
36
- # <em>options[:identifier]</em>:: Identifier for this graph, BNode or URIRef
37
- # <em>options[:allow_n3]</em>:: Allow N3-specific triples: Literals as subject, BNodes as predicate
34
+ # @option options [AbstractStore, Symbol] :store defaults to a new ListStore instance. May be symbol :list_store or :memory_store
35
+ # @option options[Resource] :identifier Identifier for this graph, BNode or URIRef
36
+ # @option options[Boolean] :allow_n3 Allow N3-specific triples: Literals as subject, BNodes as predicate
38
37
  def initialize(options = {})
39
38
  # Instantiate triple store
40
39
  @store = case options[:store]
@@ -54,14 +53,17 @@ module RdfContext
54
53
  end
55
54
 
56
55
  # Hash of graph, based on graph type and identifier
56
+ # @return [String]
57
57
  def hash
58
58
  [self.class.to_s, self.identifier].hash
59
59
  end
60
60
 
61
+ # @return [Boolean]
61
62
  def context_aware?; @store.context_aware?; end
62
63
 
63
64
  # Destroy the store identified by _configuration_ if supported
64
65
  # If configuration is nil, remove the graph context
66
+ # @return [void]
65
67
  def destroy(configuration = nil)
66
68
  if configuration
67
69
  @store.destroy(configuration)
@@ -73,15 +75,18 @@ module RdfContext
73
75
  end
74
76
 
75
77
  # Commit changes to graph
78
+ # @return [void]
76
79
  def commit; @store.commit; end
77
80
 
78
81
  # Rollback active transactions
82
+ # @return [void]
79
83
  def rollback; @store.rollback; end
80
84
 
81
85
  # Open the graph store
82
86
  #
83
87
  # Might be necessary for stores that require opening a connection to a
84
88
  # database or acquiring some resource.
89
+ # @return [void]
85
90
  def open(configuration = {})
86
91
  @store.open(configuration)
87
92
  end
@@ -90,20 +95,21 @@ module RdfContext
90
95
  #
91
96
  # Might be necessary for stores that require closing a connection to a
92
97
  # database or releasing some resource.
98
+ # @param [Boolean] commit_pending_transaction (false)
99
+ # @return [void]
93
100
  def close(commit_pending_transaction=false)
94
101
  @store.close(commit_pending_transaction)
95
102
  end
96
103
 
97
104
  # Serialize graph using specified serializer class.
98
105
  #
99
- # @param [Hash] options:: Options
100
- # <em>options[:format]</em>:: serializer, defaults to a new NTSerializer instance. Otherwise may be a symbol from :nt, :turtle, :xml
101
- # <em>options[:io]</em>:: IO (or StringIO) object, otherwise serializes to a string
102
- # <em>options[:base]</em>:: Base URI for output
106
+ # @option options [#to_sym] :format serializer, defaults to a new NTSerializer instance. Otherwise may be a symbol from :nt, :turtle, :xml
107
+ # @option options [#read, #to_s] :io IO (or StringIO) object, otherwise serializes to a string
108
+ # @option options [URIRef] :base serializer, defaults to a new NTSerializer instance. Otherwise may be a symbol from :nt, :turtle, :xml
103
109
  #
104
110
  # Other options are parser specific.
105
111
  #
106
- # @returns [IO, String]:: Passed IO/StringIO object or a string
112
+ # @return [IO, String]:: Passed IO/StringIO object or a string
107
113
  def serialize(options)
108
114
  serializer = case options[:format].to_sym
109
115
  when AbstractSerializer then options[:serializer]
@@ -122,10 +128,10 @@ module RdfContext
122
128
  ##
123
129
  # Exports the graph to RDF in N-Triples form.
124
130
  #
125
- # ==== Example
131
+ # @example
126
132
  # g = Graph.new; g.add_triple(BNode.new, URIRef.new("http://xmlns.com/foaf/0.1/knows"), BNode.new); g.to_ntriples # => returns a string of the graph in N-Triples form
127
133
  #
128
- # @return [String]:: The graph in N-Triples.
134
+ # @return [String] The serialized graph in N-Triples.
129
135
  #
130
136
  # @author Tom Morris
131
137
  def to_ntriples
@@ -133,12 +139,13 @@ module RdfContext
133
139
  end
134
140
 
135
141
  # Output graph using to_ntriples
142
+ # @return [String] The serialized graph in N-Triples.
136
143
  def to_s; self.to_ntriples; end
137
144
 
138
145
  ##
139
146
  # Exports the graph to RDF in RDF/XML form.
140
147
  #
141
- # @return [String]:: The RDF/XML graph
148
+ # @return [String] The serialized RDF/XML graph
142
149
  def to_rdfxml
143
150
  serialize(:format => :rdfxml)
144
151
  end
@@ -146,24 +153,26 @@ module RdfContext
146
153
  ##
147
154
  # Bind a namespace to the graph.
148
155
  #
149
- # ==== Example
156
+ # @example
150
157
  # g = Graph.new; g.bind(Namespace.new("http://xmlns.com/foaf/0.1/", "foaf")) # => binds the Foaf namespace to g
151
158
  #
152
- # @param [String] namespace:: the namespace to bind
153
- # @return [Namespace]:: The newly bound or pre-existing namespace.
159
+ # @param [Nameespace] namespace the namespace to bind
160
+ # @return [Namespace] The newly bound or pre-existing namespace.
154
161
  def bind(namespace)
155
162
  raise GraphException, "Can't bind #{namespace.inspect} as namespace" unless namespace.is_a?(Namespace)
156
163
  @store.bind(namespace)
157
164
  end
158
165
 
159
- # Hash of prefix => Namespace bindings
166
+ # @return [Hash{String => Namespace}]
160
167
  def nsbinding; @store.nsbinding; end
161
168
 
162
- # Hash of uri => Namespace bindings
169
+ # @return [Hash{URIRef => Namespace}]
163
170
  def uri_binding; @store.uri_binding; end
164
171
 
165
172
  # QName for a URI
166
173
  # Try bound namespaces, and if not found, try well-known namespaces
174
+ # @param [URIRef] uri
175
+ # @return [String]
167
176
  def qname(uri)
168
177
  uri.to_qname(self.uri_binding) || begin
169
178
  qn = uri.to_qname(WELLKNOWN_NAMESPACES)
@@ -173,36 +182,45 @@ module RdfContext
173
182
  end
174
183
 
175
184
  # Namespace for prefix
185
+ # @param [String] prefix
186
+ # @return [Namespace]
176
187
  def namespace(prefix); @store.namespace(prefix); end
177
188
 
178
189
  # Prefix for namespace
190
+ # @param [Namespace] namespcae
191
+ # @return [String]
179
192
  def prefix(namespace); @store.prefix(namespace); end
180
193
 
181
194
  # Number of Triples in the graph
195
+ # @return [Integer]
182
196
  def size; @store.size(self); end
183
197
 
184
198
  # List of distinct subjects in graph
199
+ # @return [Array<Resource>]
185
200
  def subjects; @store.subjects(self); end
186
201
 
187
202
  # List of distinct predicates in graph
203
+ # @return [Array<Resource>]
188
204
  def predicates; @store.predicates(self); end
189
205
 
190
206
  # List of distinct objects in graph
207
+ # @return [Array<Resource>]
191
208
  def objects; @store.objects(self); end
192
209
 
193
210
  # Indexed statement in serialized graph triples. Equivalent to graph.triples[item]
211
+ # @return [Triple]
194
212
  def [] (item); @store.item(item, self); end
195
213
 
196
214
  # Adds a triple to a graph directly from the intended subject, predicate, and object.
197
215
  #
198
- # ==== Example
216
+ # @example
199
217
  # g = Graph.new; g.add_triple(BNode.new, URIRef.new("http://xmlns.com/foaf/0.1/knows"), BNode.new) # => results in the triple being added to g; returns an array of g's triples
200
218
  #
201
- # @param [URIRef, BNode] subject:: the subject of the triple
202
- # @param [URIRef] predicate:: the predicate of the triple
203
- # @param [URIRef, BNode, Literal] object:: the object of the triple
204
- # @return [Graph]:: Returns the graph
205
- # @raise [Error]:: Checks parameter types and raises if they are incorrect.
219
+ # @param [URIRef, BNode] subject the subject of the triple
220
+ # @param [URIRef] predicate the predicate of the triple
221
+ # @param [URIRef, BNode, Literal] object the object of the triple
222
+ # @return [Graph] Returns the graph
223
+ # @raise [Error] Checks parameter types and raises if they are incorrect.
206
224
  def add_triple(subject, predicate, object)
207
225
  self.add(Triple.new(subject, predicate, object))
208
226
  self
@@ -211,13 +229,13 @@ module RdfContext
211
229
  ##
212
230
  # Adds an more extant triples to a graph. Delegates to Store.
213
231
  #
214
- # ==== Example
232
+ # @example
215
233
  # g = Graph.new;
216
234
  # t = Triple.new(BNode.new, URIRef.new("http://xmlns.com/foaf/0.1/knows"), BNode.new);
217
235
  # g << t
218
236
  #
219
- # @param [Triple] t:: the triple to be added to the graph
220
- # @return [Graph]:: Returns the graph
237
+ # @param [Triple] triple the triple to be added to the graph
238
+ # @return [Graph] Returns the graph
221
239
  def << (triple)
222
240
  triple.validate_rdf unless @allow_n3 # Only add triples if n3-mode is set
223
241
  @store.add(triple, self)
@@ -227,15 +245,15 @@ module RdfContext
227
245
  ##
228
246
  # Adds one or more extant triples to a graph. Delegates to Store.
229
247
  #
230
- # ==== Example
248
+ # @example
231
249
  # g = Graph.new;
232
250
  # t1 = Triple.new(BNode.new, URIRef.new("http://xmlns.com/foaf/0.1/knows"), BNode.new);
233
251
  # t2 = Triple.new(BNode.new, URIRef.new("http://xmlns.com/foaf/0.1/knows"), BNode.new);
234
252
  # g.add(t1, t2, ...)
235
253
  #
236
- # @param [Triple] triples:: one or more triples. Last element may be a hash for options
237
- # <em>options[:context]</em>:: Graph context in which to deposit triples, defaults to default_context or self
238
- # @return [Graph]:: Returns the graph
254
+ # @param [Array<Triple>] triples one or more triples. Last element may be a hash for options
255
+ # @option [Resource] :context Graph context in which to deposit triples, defaults to default_context or self
256
+ # @return [Graph] Returns the graph
239
257
  def add(*triples)
240
258
  options = triples.last.is_a?(Hash) ? triples.pop : {}
241
259
  ctx = options[:context] || @default_context || self
@@ -249,11 +267,11 @@ module RdfContext
249
267
 
250
268
  ##
251
269
  # Adds a list of resources as an RDF list by creating bnodes and first/rest triples
252
- # @param [URIRef, BNode] subject:: the subject of the triple
253
- # @param [URIRef] predicate:: the predicate of the triple
254
- # @param [Array] objects:: List of objects to serialize
255
- # @return [Graph]:: Returns the graph
256
- # @raise [Error]:: Checks parameter types and raises if they are incorrect.
270
+ # @param [URIRef, BNode] subject the subject of the triple
271
+ # @param [URIRef] predicate the predicate of the triple
272
+ # @param [Array] objects List of objects to serialize
273
+ # @return [Graph] Returns the graph
274
+ # @raise [Error] Checks parameter types and raises if they are incorrect.
257
275
  def add_seq(subject, predicate, objects)
258
276
  if objects.empty?
259
277
  add_triple(subject, predicate, RDF_NS.nil)
@@ -282,19 +300,23 @@ module RdfContext
282
300
 
283
301
  # Remove a triple from the graph. Delegates to store.
284
302
  # Nil matches all triples and thus empties the graph
303
+ # @param [Triple] triple
304
+ # @return [void]
285
305
  def remove(triple); @store.remove(triple, self); end
286
306
 
287
307
  # Triples from graph, optionally matching subject, predicate, or object.
288
308
  # Delegates to Store#triples.
289
309
  #
290
- # @param [Triple, nil] triple:: Triple to match, may be a pattern triple or nil
291
- # @return [Array]:: List of matched triples
310
+ # @param [Triple] triple (nil) Triple to match, may be a pattern triple or nil
311
+ # @return [Array<Triple>] List of matched triples
292
312
  def triples(triple = Triple.new(nil, nil, nil), &block) # :yields: triple, context
293
313
  @store.triples(triple, self, &block) || []
294
314
  end
295
315
  alias_method :find, :triples
296
316
 
297
317
  # Returns ordered rdf:_n objects or rdf:first, rdf:rest for a given subject
318
+ # @param [Resource] subject
319
+ # @return [Array<Resource>]
298
320
  def seq(subject)
299
321
  props = properties(subject)
300
322
  rdf_type = (props[RDF_TYPE.to_s] || []).map {|t| t.to_s}
@@ -328,13 +350,17 @@ module RdfContext
328
350
  #
329
351
  # Properties arranged as a hash with the predicate Term as index to an array of resources or literals
330
352
  #
331
- # Example:
353
+ # @example
332
354
  # graph.parse(':foo a :bar; rdfs:label "An example" .', "http://example.com/")
333
355
  # graph.resources("http://example.com/subject") =>
334
356
  # {
335
357
  # "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" => [<http://example.com/#bar>],
336
358
  # "http://example.com/#label" => ["An example"]
337
359
  # }
360
+ #
361
+ # @param [Resource] subject
362
+ # @param [Boolean] recalc Refresh cache of property values
363
+ # @return [Hash{String => Resource}]
338
364
  def properties(subject, recalc = false)
339
365
  @properties ||= {}
340
366
  @properties.delete(subject.to_s) if recalc
@@ -352,6 +378,8 @@ module RdfContext
352
378
 
353
379
 
354
380
  # Synchronize properties to graph
381
+ # @param [Resource] subject
382
+ # @return [void]
355
383
  def sync_properties(subject)
356
384
  props = properties(subject)
357
385
 
@@ -369,14 +397,15 @@ module RdfContext
369
397
  end
370
398
 
371
399
  # Return an n3 identifier for the Graph
400
+ # @return [String]
372
401
  def n3
373
402
  "[#{self.identifier.to_n3}]"
374
403
  end
375
404
 
376
405
  # Detect the presence of a BNode in the graph, either as a subject or an object
377
406
  #
378
- # @param [BNode] bn:: BNode to find
379
- #
407
+ # @param [BNode] bn BNode to find
408
+ # @return [Boolean]
380
409
  def has_bnode_identifier?(bn)
381
410
  self.triples do |triple, context|
382
411
  return true if triple.subject.eql?(bn) || triple.object.eql?(bn)
@@ -385,11 +414,14 @@ module RdfContext
385
414
  end
386
415
 
387
416
  # Check to see if this graph contains the specified triple
417
+ # @param [Triple] triple
418
+ # @return [Boolean]
388
419
  def contains?(triple)
389
420
  @store.contains?(triple, self)
390
421
  end
391
422
 
392
423
  # Get all BNodes with usage count used within graph
424
+ # @return [Array<BNode>]
393
425
  def bnodes
394
426
  @store.bnodes(self)
395
427
  end
@@ -397,16 +429,21 @@ module RdfContext
397
429
  # Get list of subjects having rdf:type == object
398
430
  #
399
431
  # @param [Resource, Regexp, String] object:: Type resource
432
+ # @return [Array<Triple>]
400
433
  def get_by_type(object)
401
434
  triples(Triple.new(nil, RDF_TYPE, object)).map {|t, ctx| t.subject}
402
435
  end
403
436
 
404
437
  # Get type(s) of subject, returns a list of symbols
438
+ # @param [Resource] subject
439
+ # @return [URIRef]
405
440
  def type_of(subject)
406
441
  triples(Triple.new(subject, RDF_TYPE, nil)).map {|t, ctx| t.object}
407
442
  end
408
443
 
409
444
  # Merge a graph into this graph
445
+ # @param [Graph] graph
446
+ # @return [void]
410
447
  def merge!(graph)
411
448
  raise GraphException.new("merge without a graph") unless graph.is_a?(Graph)
412
449
 
@@ -432,6 +469,8 @@ module RdfContext
432
469
  # after sorting each graph.
433
470
  #
434
471
  # We just follow Python RDFlib's lead and do a simple comparison
472
+ # @param [Graph] graph
473
+ # @return [Boolean]
435
474
  def eql?(other)
436
475
  #puts "eql? size #{self.size} vs #{other.size}" if $DEBUG
437
476
  return false if !other.is_a?(Graph) || self.size != other.size
@@ -486,12 +525,11 @@ module RdfContext
486
525
  #
487
526
  # @param [IO, String] stream:: the RDF IO stream, string, Nokogiri::HTML::Document or Nokogiri::XML::Document
488
527
  # @param [String] uri:: the URI of the document
489
- # @param [Hash] options:: Options from
490
- # <em>options[:debug]</em>:: Array to place debug messages
491
- # <em>options[:type]</em>:: One of _rdfxml_, _html_, or _n3_
492
- # <em>options[:strict]</em>:: Raise Error if true, continue with lax parsing, otherwise
493
- # <em>options[:allow_n3]</em>:: Allow N3-specific triples: Literals as subject, BNodes as predicate
494
- # @return [Graph]:: Returns the graph containing parsed triples
528
+ # @option options [Array] :debug (nil) Array to place debug messages
529
+ # @option options [:rdfxml, :html, :n3] :type (nil)
530
+ # @option options [Boolean] :strict (false) Raise Error if true, continue with lax parsing, otherwise
531
+ # @option options [Boolean] :allow_n3 (false) Allow N3-specific triples: Literals as subject, BNodes as predicate
532
+ # @return [Graph] Returns the graph containing parsed triples
495
533
  def parse(stream, uri = nil, options = {}, &block) # :yields: triple
496
534
  @allow_n3 ||= options[:allow_n3]
497
535
  Parser.parse(stream, uri, options.merge(:graph => self), &block)