Installation

You need activesupport, activerecord and json gems installed for RTM to work.
To use the memory backend, you also need SQLite3.

• gem install activesupport
• gem install activerecord
• gem install json
• gem install sqlite3-ruby

Then install RTM:

• gem install rtm

If you’re installing locally, use the exact gem name: gem install rtm-0.1.×.gem

Next, fire up irb and load RTM. On the command line do

• irb
• require ‘rtm’
• RTM.connect # for memory back end

To use another back end:

• RTM.connect_mysql(“database”, “user”, “pass”, “host”) # for mysql
• RTM.connect( connection_hash ) # see Active Record documentation.
• RTM.generate_database # to create the database tables for first time use (not needed for memory back end).

Usage

• require ‘rtm’
• RTM.connect # or memory or other backends
• map1 = RTM.create “http://a/b/c/base_locator” # create or get topic map
• map2 = RTM⁰ # first topic map
• map3 = RTM[“http://a/b/c/base_locator”] # map by base locator

Creating items

• t = map.create_topic
• a = map.create_association
• r = a.create_role
• t = map.create_topic

Browsing items

• map.topics # list of topics
• map.associations # list of associations
• …
• All property names align to the TMDM, just use the names from the property lists or from the UML diagrams

Referencing topics

Within RTM, topics can be referenced using their identifiers. Which specific type of identifier is used for querying is explained in the section “Querying topics” below. For any write operations, i.e. setting a type, creating an occurrence, internally, the method get! is used. For any read operations, internally, the method get is used.

Querying topics

• Getting topics: get
  

  # get a topic using its identifiers:
  
  # item identifier:
  
  t1 = tm.get(“item-identifier”)
  
  # subject identifier:
  
  t2 = tm.get(“http://psi.example.org/t2”)
  
  # subject locator:
  
  t3 = tm.get(“=http://rtm.rubyforge.org”)
  

• get by item identifier
  

  
  
  t1 = tm.get(“item-identifier”)
  
  # * use relative IRIs
  
  # * returns nil if not found
  
  # for using absolute IRI:
  
  t1 = tm.by_item_identifier( “absolute:item-identifier”)
  
  # * the latter might be TopicMapsConstruct, too
  

• get by subject identifier
  

  
  
  
  
  t1 = tm.get(“absolute:identifier”)
  
  # * use absolute IRIs
  
  # * returns nil if not found
  
  # or use the direct method:
  
  t1 = tm.topic_by_subject_identifier( “absolute:subject-identifier”)
  

• get by subject locator
  

  
  
  t1 = tm.get(“=http://rtm.rubyforge.org”)
  
  # * similar to subject identifier
  
  # * prefix with “=”
  
  # or use the direct method:
  
  t1 = tm.topic_by_subject_locator( “http://rtm.rubyforge.org”)
  
  # * no prefix needed here
  

• Creating Topics: get!
  

  
  
  # similar to getting, add ! to method
  
  # item identifier:
  
  t1 = tm.get!(“item-identifier”)
  
  # subject identifier:
  
  t2 = tm.get!(“http://psi.example.org/t2”)
  
  # subject locator:
  
  t3 = tm.get!(“=http://rtm.rubyforge.org”)
  

• Creating topics (continued)
  

  
  
  # similar to getting, add ! to method
  
  # item identifier:
  
  t1 = tm.topic_by_item_identifier!( “item_identifier”)
  
  #        => always returns a Topic
  
  # subject identifier:
  
  t2 = tm.topic_by_subject_identifier!( “http://psi.example.org/t2”)
  
  # subject locator:
  
  t3 = tm.topic_subject_locator( “http://rtm.rubyforge.org”) # no =
  

Change characteristics of topics

(using an example topic t from a topic map tm)

• t[“-”] = “a new name item with the default name type for topic t”
• t[“-firstname”] = “a new name i
  
• t[”-"] # returns a list of all
  
  
• t[“age”] = 17 # create new occurrenc
  
• t[“age”] # get a lis

Import/Export

• RTM.from_xtm2(io_object, “base locator”)
• map.to_xtm2
• …