Class: ActiveTriples::Relation

Inherits:
Object
  • Object
show all
Includes:
Comparable, Enumerable
Defined in:
lib/active_triples/relation.rb

Overview

A ‘Relation` represents the values of a specific property/predicate on an RDFSource. Each relation is a set (Array) of RDF::Terms that are objects in the of source’s triples of the form:

<{#parent}> <{#predicate}> [term] .

Relations express a set of binary relationships (on a predicate) between the parent node and a term.

When the term is a URI or Blank Node, it is represented in the results Array as an RDFSource with a graph selected as a subgraph of the parent’s. The triples in this subgraph are: (a) those whose subject is the term; (b) …

See Also:

  • RDF::Term

Defined Under Namespace

Classes: ValueError

Constant Summary collapse

TYPE_PROPERTY = 
{ predicate: RDF.type, cast: false }.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(parent_source, value_arguments) ⇒ Relation

Returns a new instance of Relation.

Parameters:

  • parent_source (ActiveTriples::RDFSource)
  • value_arguments (Array<Symbol, Hash>) —

    if a Hash is passed as the final element, it is removed and set to ‘@rel_args`.



45
46
47
48
49
50
51
52
53
 
# File 'lib/active_triples/relation.rb', line 45

def initialize(parent_source, value_arguments)
  self.parent = parent_source
  @reflections = parent_source.reflections
  self.rel_args ||= {}
  self.rel_args = value_arguments.pop if
    value_arguments.is_a?(Array) && value_arguments.last.is_a?(Hash)

  self.value_arguments = value_arguments
end

Instance Attribute Details

#parent ⇒ RDFSource

Returns the resource that is the domain of this relation.

Returns:

  • (RDFSource) —

    the resource that is the domain of this relation



36
37
38
 
# File 'lib/active_triples/relation.rb', line 36

def parent
  @parent
end

#reflections ⇒ Class (readonly)

Returns:

  • (Class) 


36
 
# File 'lib/active_triples/relation.rb', line 36

attr_accessor :parent, :value_arguments, :rel_args

#rel_args ⇒ Hash

Returns:

  • (Hash) 


36
 
# File 'lib/active_triples/relation.rb', line 36

attr_accessor :parent, :value_arguments, :rel_args

#value_arguments ⇒ Array<Object>

Returns:

  • (Array<Object>) 


36
 
# File 'lib/active_triples/relation.rb', line 36

attr_accessor :parent, :value_arguments, :rel_args

Instance Method Details

#&(array) ⇒ Array

Note:

simply passes to ‘Array#&` unless argument is a `Relation`

Parameters:

Returns:

  • (Array)

See Also:

  • Array#&


62
63
64
65
66
67
 
# File 'lib/active_triples/relation.rb', line 62

def &(array)
  return to_a & array unless array.is_a? Relation

  (objects.to_a & array.objects.to_a)
    .map { |object| convert_object(object) }
end

#+(array) ⇒ Array

Note:

simply passes to ‘Array#+` unless argument is a `Relation`

Parameters:

Returns:

  • (Array)

See Also:

  • Array#+


90
91
92
93
94
95
 
# File 'lib/active_triples/relation.rb', line 90

def +(array)
  return to_a + array unless array.is_a? Relation

  (objects.to_a + array.objects.to_a)
    .map { |object| convert_object(object) }
end

#<<(values) ⇒ Relation Also known as: push

Adds values to the result set

Parameters:

  • values (Object, Array<Object>) —

    values to add

Returns:

  • (Relation) —

    a relation containing the set values; i.e. ‘self`



139
140
141
142
 
# File 'lib/active_triples/relation.rb', line 139

def <<(values)
  values = prepare_relation(values) if values.is_a?(Relation)
  self.set(objects.to_a | Array.wrap(values))
end

#<=>(other) ⇒ Object

Mimics ‘Set#<=>`, returning `0` when set membership is equivalent, and `nil` (as non-comparable) otherwise. Unlike `Set#<=>`, uses `#==` for member comparisons.

Parameters:

  • other (Object)

See Also:

  • Set#<=>


105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/active_triples/relation.rb', line 105

def <=>(other)
  return nil unless other.respond_to?(:each)

  if empty?
    return 0 if other.each.first.nil?
    return nil
  end

  # We'll need to traverse `other` repeatedly, so we get a stable `Array`
  # representation. This avoids any repeated query cost if `other` is a
  # `Relation`.
  length = 0
  other  = other.to_a
  this   = each

  loop do
    begin
      cur = this.next
    rescue StopIteration
      return other.length == length ? 0 : nil
    end

    length += 1

    return nil if other.length < length || !other.include?(cur)
  end
end

#build(attributes = {}) ⇒ Object

Builds a node with the given attributes, adding it to the relation.

Nodes are built using the configured ‘class_name` for the relation. Attributes passed in the Hash argument are set on the new node through `RDFSource#attributes=`. If the attribute keys are not valid properties on the built node, we raise an error.

@todo: clarify class behavior; it is actually tied to type, in some cases.

Examples:

building an empty generic node

resource = ActiveTriples::Resource.new
resource.resource.get_values(RDF::Vocab::DC.relation).build
# => #<ActiveTriples::Resource:0x2b0(#<ActiveTriples::Resource:0x005>)>)

resource.dump :ttl
# => "\n [ <http://purl.org/dc/terms/relation> []] .\n"

building a node with attributes

class WithRelation
  include ActiveTriples::RDFSource
  property :relation, predicate:  RDF::Vocab::DC.relation,
    class_name: 'WithTitle'
end

class WithTitle
  include ActiveTriples::RDFSource
  property :title, predicate: RDF::Vocab::DC.title
end

resource = WithRelation.new
attributes = { id: 'http://ex.org/moomin', title: 'moomin' }

resource.get_values(:relation).build(attributes)
# => #<ActiveTriples::Resource:0x2b0(#<ActiveTriples::Resource:0x005>)>)

resource.dump :ttl
# => "\n<http://ex.org/moomin> <http://purl.org/dc/terms/title> \"moomin\" .\n\n [ <http://purl.org/dc/terms/relation> <http://ex.org/moomin>] .\n"

Parameters:

  • attributes (Hash) (defaults to: {}) —

    a hash of attribute names and values for the built node.

See Also:



190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/active_triples/relation.rb', line 190

def build(attributes={})
  new_subject = attributes.fetch('id') { RDF::Node.new }

  make_node(new_subject).tap do |node|
    node.attributes = attributes.except('id')
    if parent.kind_of? List::ListResource
      parent.list << node
    elsif node.kind_of? RDF::List
      self.push node.rdf_subject
    else
      self.push node
    end
  end
end

#clear ⇒ Relation

Empties the ‘Relation`, deleting any associated triples from `parent`.

Returns:

  • (Relation) —

    self; a now empty relation



209
210
211
212
213
 
# File 'lib/active_triples/relation.rb', line 209

def clear
  parent.delete([rdf_subject, predicate, nil])

  self
end

#delete(value) ⇒ ActiveTriples::Relation

Note:

this method behaves somewhat differently from ‘Array#delete`. It succeeds on deletion of non-existing values, always returning `self` unless an error is raised. There is no option to pass a block to evaluate if the value is not present. This is because access for `value` depends on query time. i.e. the `Relation` set does not have an underlying efficient data structure allowing a reliably cheap existence check.

Note:

symbols are treated as RDF::Nodes by default in ‘RDF::Mutable#delete`, but may also represent tokens in statements. This casts symbols to a literals, which gets us symmetric behavior between `#set(:sym)` and `#delete(:sym)`.

Returns self.

Examples:

deleting a value

resource = MySource.new
resource.title = ['moomin', 'valley']
resource.title.delete('moomin') # => ["valley"]
resource.title # => ['valley']

note the behavior of unmatched values

resource = MySource.new
resource.title = 'moomin'
resource.title.delete('valley') # => ["moomin"]
resource.title # => ['moomin']

Parameters:

  • value (Object) —

    the value to delete from the relation

Returns:



243
244
245
246
247
248
 
# File 'lib/active_triples/relation.rb', line 243

def delete(value)
  value = RDF::Literal(value) if value.is_a? Symbol
  parent.delete([rdf_subject, predicate, value])

  self
end

#delete?(value) ⇒ Object?

A variation on ‘#delete`. This queries the relation for matching values before running the deletion, returning `nil` if it does not exist.

Parameters:

  • value (Object) —

    the value to delete from the relation

Returns:

  • (Object, nil) —

    ‘nil` if the value doesn’t exist; the value otherwise

See Also:



259
260
261
262
263
264
265
266
 
# File 'lib/active_triples/relation.rb', line 259

def delete?(value)
  value = RDF::Literal(value) if value.is_a? Symbol

  return nil if parent.query([rdf_subject, predicate, value]).nil?

  delete(value)
  value
end

#each ⇒ Enumerator<Object>

Gives a result set for the ‘Relation`.

By default, ‘RDF::URI` and `RDF::Node` results are cast to `RDFSource`. When `cast?` is `false`, `RDF::Resource` values are left in their raw form.

‘Literal` results are cast as follows:

- Simple string literals are returned as `String`
- `rdf:langString` literals are always returned as raw `Literal` objects, 
   retaining their language tags.
- Typed literals are cast to their Ruby `#object` when their datatype 
  is associated with a `Literal` subclass.

Examples:

results with default casting

datatype = RDF::URI("http://example.com/custom_type")

parent << [parent.rdf_subject, predicate, 'my value']
parent << [parent.rdf_subject, predicate, RDF::Literal('my_value',
                                            datatype: datatype)]
parent << [parent.rdf_subject, predicate, Date.today]
parent << [parent.rdf_subject, predicate, RDF::URI('http://ex.org/#me')]
parent << [parent.rdf_subject, predicate, RDF::Node.new]

relation.to_a
# => ["my_value",
#     "my_value" R:L:(Literal),
#     Fri, 25 Sep 2015,
#     #<ActiveTriples::Resource:0x3f8...>,
#     #<ActiveTriples::Resource:0x3f8...>]

results with ‘cast?` set to `false`

relation.to_a
# => ["my_value",
#     "my_value" R:L:(Literal),
#     Fri, 25 Sep 2015,
#     #<RDF::URI:0x3f8... URI:http://ex.org/#me>,
#     #<RDF::Node:0x3f8...(_:g69843536054680)>]

Returns:

  • (Enumerator<Object>) —

    the result set



309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/active_triples/relation.rb', line 309

def each
  return [].to_enum if predicate.nil?

  if block_given?
    objects do |object|
      converted_object = convert_object(object)
      yield converted_object unless converted_object.nil?
    end
  end

  to_enum
end

#empty? ⇒ Boolean

Returns true if the results are empty.

Returns:

  • (Boolean) —

    true if the results are empty.



324
325
326
 
# File 'lib/active_triples/relation.rb', line 324

def empty?
  objects.empty?
end

#first_or_create(attributes = {}) ⇒ Object

Deprecated.

for removal in 1.0.0. Use ‘first || build({})`, `build({}) if empty?` or similar logic.

Returns the first result, if present; else a newly built node.

Returns:

  • (Object) —

    the first result, if present; else a newly built node

See Also:



335
336
337
338
 
# File 'lib/active_triples/relation.rb', line 335

def first_or_create(attributes={})
  warn 'DEPRECATION: #first_or_create is deprecated for removal in 1.0.0.'
  first || build(attributes)
end

#length ⇒ Integer

Returns:

  • (Integer) 


342
343
344
 
# File 'lib/active_triples/relation.rb', line 342

def length
  objects.to_a.length
end

#predicate ⇒ RDF::Term?

Gives the predicate used by the Relation. Values of this object are those that match the pattern ‘<rdf_subject> <predicate> [value] .`

Returns:

  • (RDF::Term, nil) —

    the predicate for this relation; nil if no predicate can be found

See Also:



354
355
356
357
 
# File 'lib/active_triples/relation.rb', line 354

def predicate
  return property if property.is_a?(RDF::Term)
  property_config[:predicate] if is_property?
end

#property ⇒ Symbol, RDF::URI

Returns the property for the Relation. This may be a registered property key or an RDF::URI.

Returns:

  • (Symbol, RDF::URI) —

    the property for this Relation.

See Also:



365
366
367
 
# File 'lib/active_triples/relation.rb', line 365

def property
  value_arguments.last
end

#set(values) ⇒ Relation

Adds values to the relation

Parameters:

  • values (Array<RDF::Resource>, RDF::Resource) —

    an array of values or a single value. If not an RDF::Resource, the values will be coerced to an RDF::Literal or RDF::Node by RDF::Statement

Returns:

  • (Relation) —

    a relation containing the set values; i.e. ‘self`

Raises:

See Also:



384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/active_triples/relation.rb', line 384

def set(values)
  raise UndefinedPropertyError.new(property, reflections) if predicate.nil?

  values = prepare_relation(values) if values.is_a?(Relation)
  values = [values].compact unless values.kind_of?(Array)

  clear
  values.each { |val| set_value(val) }

  parent.persist! if parent.persistence_strategy.is_a? ParentStrategy
  self
end

#subtract(enum) ⇒ Relation #subtract(*values) ⇒ Relation

Note:

This casts symbols to a literals, which gets us symmetric behavior with ‘#set(:sym)`.

Returns self.

Overloads:

  • #subtract(enum) ⇒ Relation

    Deletes objects in the enumerable from the relation

    Parameters:

    • values (Enumerable) —

      an enumerable of objects to delete

  • #subtract(*values) ⇒ Relation

    Deletes each argument value from the relation

    Parameters:

    • *values (Array<Object>) —

      the objects to delete

Returns:

See Also:



410
411
412
413
414
415
416
417
418
419
 
# File 'lib/active_triples/relation.rb', line 410

def subtract(*values)
  values = values.first if values.first.is_a? Enumerable
  statements = values.map do |value|
    value = RDF::Literal(value) if value.is_a? Symbol
    [rdf_subject, predicate, value]
  end

  parent.delete(*statements)
  self
end

#swap(swap_out, swap_in) ⇒ Relation

Replaces the first argument with the second as a value within the relation.

Parameters:

  • swap_out (Object) —

    the value to delete

  • swap_in (Object) —

    the replacement value

Returns:



429
430
431
 
# File 'lib/active_triples/relation.rb', line 429

def swap(swap_out, swap_in)
  self.<<(swap_in) if delete?(swap_out)
end

#|(array) ⇒ Array

Note:

simply passes to ‘Array#|` unless argument is a `Relation`

Parameters:

Returns:

  • (Array)

See Also:

  • Array#|


76
77
78
79
80
81
 
# File 'lib/active_triples/relation.rb', line 76

def |(array)
  return to_a | array unless array.is_a? Relation
  
  (objects.to_a | array.objects.to_a)
    .map { |object| convert_object(object) }
end