Module: RTM::Navigation::Topic

Defined in:
rtm/lib/rtm/navigation/topic/items.rb,
rtm/lib/rtm/navigation/topic/types.rb,
rtm/spec/rtm/navigation/topic_spec.rb,
rtm/lib/rtm/navigation/topic/players.rb,
rtm/lib/rtm/navigation/topic/locators.rb,
rtm/lib/rtm/navigation/topic/traverse.rb,
rtm/lib/rtm/navigation/topic/indicators.rb,
rtm/lib/rtm/navigation/topic/supertypes.rb,
rtm/spec/rtm/navigation/topic/scope_spec.rb,
rtm/spec/rtm/navigation/topic/types_spec.rb,
rtm/spec/rtm/navigation/topic/items_spec.rb,
rtm/spec/rtm/navigation/topic/players_spec.rb,
rtm/spec/rtm/navigation/topic/locators_spec.rb,
rtm/spec/rtm/navigation/topic/traverse_spec.rb,
rtm/lib/rtm/navigation/topic/characteristics.rb,
rtm/spec/rtm/navigation/topic/indicators_spec.rb,
rtm/spec/rtm/navigation/topic/supertypes_spec.rb,
rtm/spec/rtm/navigation/topic/characteristics_spec.rb

Instance Method Summary

Instance Method Details

- (Object) add_subtype(new_subtype)

Creates a binary supertype-subtype-Association where identifier defines the player of the subtype-Role. The current Topic will play the supertype-Role. Returns the created Association.

Identifier may be topic reference.

:call-seq:

  add_subtype(identifier) -> Association


107
108
109
110
111
112
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 107

def add_subtype(new_subtype)
  asso = topic_map.create_association(RTM::PSI[:supertype_subtype])
  asso.create_role(RTM::PSI[:supertype],self)
  asso.create_role(RTM::PSI[:subtype],new_subtype)
  asso
end

- (Object) add_subtypes(*args)

Creates one or several binary supertype-subtype-Associations where each identifier defines the player of a subtype-Role. The current topic will play the supertype-Role in each association. Returns the associations.

The identifiers may be topic references.

:call-seq:

  add_subtypes(identifier1, identifier2, ...) -> Array of Associtions


124
125
126
127
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 124

def add_subtypes(*args)
  args.flatten!
  args.map{|identifier| add_subtype(identifier)}
end

- (Object) add_supertype(new_supertype)

Creates a binary supertype-subtype-Association where identifier defines the player of the supertype-Role. The current Topic will play the subtype-Role. Returns the created Association.

Identifier may be a topic reference.

:call-seq:

  add_supertype(identifier) -> Association


31
32
33
34
35
36
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 31

def add_supertype(new_supertype)
  asso = topic_map.create_association(RTM::PSI[:supertype_subtype])
  asso.create_role(RTM::PSI[:subtype],self)
  asso.create_role(RTM::PSI[:supertype],new_supertype)
  asso
end

- (Object) add_supertypes(*args)

Creates one or several binary supertype-subtype-Associations where each identifier defines the player of a supertype-Role. The current topic will play the subtype-Role in each association. Returns the associations.

The identifiers may be topic references.

:call-seq:

  add_supertypes(identifier1, identifier2, ...) -> Array of Associtions


48
49
50
51
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 48

def add_supertypes(*args)
  args.flatten!
  args.map{|identifier| add_supertype(identifier)}
end

- (Object) characteristics(type = :any)

Returns all Names and Occurrences of this Topic. If an identifier is given, only those Names and Occurrences are returned, whose type or supertypes include the identifier.

Identifier may be a topic reference.

The result may be empty.

:call-seq:

  characteristics -> Array of Names and Occurrences
  characteristics(identifier) -> Array of Names and Occurrences


20
21
22
23
24
25
26
27
28
29
# File 'rtm/lib/rtm/navigation/topic/characteristics.rb', line 20

def characteristics(type=:any)
  # FIXME which version of the code?
  return names.to_a + occurrences.to_a if type == :any
  _topic = topic_map.get(type)
  return [] unless _topic
  #names.select{|n| n.type.include?(_topic) || n.type.supertypes.include?(_topic)}.to_a +
  #occurrences.select{|o| o.type.include?(_topic) || o.type.supertypes.include?(_topic)}.to_a
  names.select{|n| n.type.supertypes.include?(_topic)}.to_a +
  occurrences.select{|o| o.type.supertypes.include?(_topic)}.to_a
end

- (Object) direct_subtypes

Returns all Topics that exist in binary supertype-subtype Associations where this Topic playes the supertype-Role.

The result may be an empty Array.

:call-seq:

  direct-subtypes -> Array of Topics


92
93
94
95
96
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 92

def direct_subtypes
  roles(topic_map.get(RTM::PSI[:supertype]),topic_map.get(RTM::PSI[:supertype_subtype])).
    reject{|r| r.getParent.getRoles.size!=2}.
    map {|r| r.getParent[RTM::PSI[:subtype]].first.player}.flatten.uniq
end

- (Object) direct_supertypes

Returns all Topic players that exist in binary supertype-subtype Associations where this Topic playes the subtype-Role.

The result may be an empty Array.

:call-seq:

  direct-supertypes -> Array of Topics


16
17
18
19
20
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 16

def direct_supertypes
  roles_played(topic_map.get(RTM::PSI[:subtype]),topic_map.get(RTM::PSI[:supertype_subtype])).
    reject{|r| r.getParent.getRoles.size!=2}.
    map{|r| r.parent[RTM::PSI[:supertype]].first.player}.flatten.uniq
end

- (Object) indicator

Returns one indicator (subject identifier) of this Topic or nil if this Topic has no indicator.

:call-seq:

  indicator -> String or nil


25
26
27
# File 'rtm/lib/rtm/navigation/topic/indicators.rb', line 25

def indicator
  return indicators.empty? ? nil : indicators.sort.first # TODO Which sorting algorithm?
end

- (Object) indicators

Returns all indicators (subject identifiers) of this Topic.

The result may be empty.

:call-seq:

  indicators -> Array of Strings


15
16
17
# File 'rtm/lib/rtm/navigation/topic/indicators.rb', line 15

def indicators
  getSubjectIdentifiers.map{|locator| locator.value}
end

- (Object) instance

Returns the instance of this Topic. It must have exactly one instance, else an error is raised.

Returns nil if this Topic has no instance.

:call-seq:

  instance -> Topic


55
56
57
58
59
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 55

def instance
  _instances = instances
  raise "Topic must have exactly one instance to call the instance-method. Use the instances-method instead." unless _instances.size < 2
  _instances.size == 1 ?  _instances.to_a.first : nil
end

- (Object) instances Also known as: reverse_types

Returns the topics which are instances of this topic. This method uses the TMAPI TypeInstanceIndex.

The result may be empty.

:call-seq:

  instances -> Set of Topics


43
44
45
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 43

def instances
  topic_map.type_instance_index.getTopics(self)
end

- (Object) item

Returns one item identifier of this Topic or nil if this Topic has no item identifier.

:call-seq:

  item -> String or nil


25
26
27
# File 'rtm/lib/rtm/navigation/topic/items.rb', line 25

def item
  return items.empty? ?  nil : items.sort.first # TODO Which sorting algorithm?
end

- (Object) items

Returns all item identifier of this Topic.

The result may be empty.

:call-seq:

  items -> Array of Strings


15
16
17
# File 'rtm/lib/rtm/navigation/topic/items.rb', line 15

def items
  getItemIdentifiers.map{|locator| locator.value}
end

- (Object) locator

Returns one subject locator of this Topic or nil if this Topic has no subject locator.

:call-seq:

  locator -> String or nil


25
26
27
# File 'rtm/lib/rtm/navigation/topic/locators.rb', line 25

def locator
  return locators.empty? ? nil : locators.sort.first # TODO Which sorting algorithm?
end

- (Object) locators

Returns all subject locators of this Topic.

The result may be empty.

:call-seq:

  locators -> Array of Strings


15
16
17
# File 'rtm/lib/rtm/navigation/topic/locators.rb', line 15

def locators
  getSubjectLocators.map{|locator| locator.value}
end

- (Object) reverse_instances

Returns the types this topic is an instance of. Calls the TMAPI getTypes method.

The result may be empty.

:call-seq:

  reverse_instances -> Set of Topics


71
72
73
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 71

def reverse_instances
  types
end

- (Object) reverse_players(type = :any)

Returns all Associations in which this Topic plays a Role.

The optional identifier specifies the type of the Roles to be considered. The identifier may be a topic reference.

Multiple instances of the same Association are possible. The result may be empty.

:call-seq:

  reverse_players -> Array of Associations
  reverse_players(identifier) -> Array of Associations


21
22
23
# File 'rtm/lib/rtm/navigation/topic/players.rb', line 21

def reverse_players(type = :any)
  roles_played(type).map{|r| r.parent}
end

- (Object) reverse_traverse

Always returns an empty Array

:call-seq:

  reverse_traverse -> Array


45
46
47
# File 'rtm/lib/rtm/navigation/topic/traverse.rb', line 45

def reverse_traverse 
  Array.new
end

- (Object) transitive_instances

Returns instances and the instances of all transitive subtypes of this topic. No duplicates are returned.

The result may be empty.

:call-seq:

  transitive_instances -> Array of Topics


99
100
101
102
103
104
105
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 99

def transitive_instances
  trans_instances = instances.to_a #may be empty
  transitive_subtypes.each do |subtype|
    trans_instances.concat(subtype.instances.to_a)
  end
  trans_instances = trans_instances.uniq #no duplicates outside of tmql mode
end

- (Object) transitive_subtypes Also known as: subtypes

Returns all subtypes of this Topic. The result includes the direct subtypes and the subtypes of these direct subtypes.

The result may be an empty Array.

:call-seq:

  transitive_subtypes -> Array of Topics


137
138
139
140
141
142
143
144
145
146
147
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 137

def transitive_subtypes
  topic_map.cached self, :transitive_subtypes do
    result_types = new_s_t = direct_subtypes
    until new_s_t.empty?
      new_s_t = new_s_t.map{|s| s.direct_subtypes}.flatten.uniq
      new_s_t = new_s_t.reject{|s| result_types.include?(s)}
      result_types = result_types + new_s_t
    end
    result_types
  end
end

- (Object) transitive_subtypes_with_self

Returns all subtypes of this Topic. The result includes the direct_subtypes and the subtypes of these direct_subtypes of this Topic as well as the Topic itself.

:call-seq:

  transitive_subtypes_with_self -> Array of Topics


155
156
157
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 155

def transitive_subtypes_with_self
  transitive_subtypes + [self]
end

- (Object) transitive_supertypes Also known as: supertypes

Returns all supertypes of this Topic. The result includes all direct supertypes and the supertypes of these direct supertypes.

The result may be an empty Array.

:call-seq:

  transitive_supertypes -> Array of Topics


62
63
64
65
66
67
68
69
70
71
72
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 62

def transitive_supertypes
#       topic_map.cached self, :transitive_supertypes do
    result_types = new_s_t = direct_supertypes
    until new_s_t.empty?
      new_s_t = new_s_t.map{|s| s.direct_supertypes}.flatten.uniq
      new_s_t = new_s_t.reject{|s| result_types.include?(s)}
      result_types = result_types + new_s_t
    end
    result_types
#       end
end

- (Object) transitive_supertypes_with_self

Returns all supertypes of this Topic. The result includes the direct_supertypes and the supertypes of these direct_supertypes of this Topic as well as the Topic itself.

:call-seq:

  transitive_supertypes_with_self -> Array of Topics


80
81
82
# File 'rtm/lib/rtm/navigation/topic/supertypes.rb', line 80

def transitive_supertypes_with_self
  transitive_supertypes + [self]
end

- (Object) transitive_types

Returns the types and all transitive supertypes of the types of this topic. No duplicates are returned.

The result may be empty.

:call-seq:

  transitive_types -> Array of Topics


83
84
85
86
87
88
89
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 83

def transitive_types
  trans_types = types.to_a #may be empty
  types.each do |type|
    trans_types.concat(type.transitive_supertypes)
  end
  trans_types = trans_types.uniq #no duplicates outside of tmql mode
end

- (Object) traverse(type = :any)

First computes all Associations where this Topic playes a Role. There, the optional identifier filters the Associations for their type.

Returns all Players of all Roles in these Associations. The current Topic is not included in the result. The result may be empty.

The identifier may be a topic reference.

:call-seq:

  traverse(identifier) -> Array of Topics


20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# File 'rtm/lib/rtm/navigation/topic/traverse.rb', line 20

def traverse(type = :any)
  unless type == :any
    _topic = topic_map.get(type)
    return [] unless _topic
  end
  _res = roles_played.map{|r| r.parent} #associations
  _res = _res.select{|a| a.type == _topic} unless type == :any
  _res = _res.map{|a| a.roles.map{ |r| r.player}}.flatten #players of all roles in these associations
  #            unless _res.empty?
  #              _res.each_with_index do |x,i|
  #                if x == self
  #                  _res.delete_at(i)
  #                  break
  #                end
  #              end
  #            end
  _res =_res.reject{|p| p == self}
  return _res
end

- (Object) type

Returns the topic this topic is an instance of. It must have exactly one type, else an error is raised.

Returns nil if this Topic has no type.

:call-seq:

  type -> Topic or nil


29
30
31
32
33
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 29

def type
  _types = types
  raise "Topic must have exactly one type to call the type-method. Use the types-method instead." unless _types.size < 2
  _types.size == 1 ? _types.to_a.first : nil
end

- (Object) types

Returns the topics this topic is an instance of.

The result may be empty.

:call-seq:

  types -> Set of Topics


15
16
17
18
19
# File 'rtm/lib/rtm/navigation/topic/types.rb', line 15

def types
  # NO SUPERISE IN Axes/NAVIGATION
  raise "This method (types) should never be executed because the corresponding TMAPI function should be called"
  getTypes
end