RTM - Ruby Topic Maps

News

2008-04-16
Some more details about referencing topics and creating topics by reference have been added below.

2008-04-08
Finally, RTM is available now using the default RubyGems installation procedure:

gem install rtm

And, I forgot to say, the type-instance and supertype-subtype-stuff mentioned below, also works like this:

require 'rtm'
RTM.connect
tm = RTM.create "urn:/bla"
tm.get!("a1").add_type("A")
tm.get!("b2").add_type("B")
tm.get!("c3").add_type("C")
tm.get("A").add_subtype("B")
tm.get("B").add_subtype("C")

2008-04-02
Greetings from Oslo, Norway! After a 3 hour tutorial at the Topic Maps 2008 conference this morning some bugs were ironed out and RTM is now considered Beta. Try the new gem, it's in the Download section and will soon be in the official gem repository.

2007-12-13
A new preview release is available.
It includes many bugfixes and 2 enhancements:

• The import has full XML namespace support now thanks to Alexander Mikhailian from Space Applications Services and supports reifier properties (which were disregarded before).
• Type-instance and supertype-subtype associations can be accessed in one single step now. The following example shows how it works. You can run the following code directly in irb, please note ca and cr are the short hand commands for create_association and create_role:

  require 'rtm'
  RTM.connect
  tm = RTM.create "urn:/bla"
  a = tm.ca RTM::PSI[:type_instance]
  a.cr "a1", RTM::PSI[:instance]
  a.cr "A", RTM::PSI[:type]
  a2 = tm.ca RTM::PSI[:type_instance]
  a2.cr "b2", RTM::PSI[:instance]
  a2.cr "B", RTM::PSI[:type]
  a3 = tm.ca RTM::PSI[:type_instance]
  a3.cr "c3", RTM::PSI[:instance]
  a3.cr "C", RTM::PSI[:type]
  
  a4 = tm.ca RTM::PSI[:supertype_subtype]
  a4.cr "A", RTM::PSI[:supertype]
  a4.cr "B", RTM::PSI[:subtype]
  a5 = tm.ca RTM::PSI[:supertype_subtype]
  a5.cr "B", RTM::PSI[:supertype]
  a5.cr "C", RTM::PSI[:subtype]
  
  tm.get("A").direct_instances # returns topic a1
  tm.get("A").instances # returns topics a1, b2, c3
  tm.get("b2").direct_types # returns topic B
  tm.get("c3").types # returns topics A, B, C
            

  The code for that is automatically created from the model, so it's possible to add own special associations. Documentation will follow later, be consoled for now: source code never lies (-;
  Please be aware that the current implementation is recursive and fails if there are loops.

2007-10-26
I thought it is a good idea to also upload the slides from TMRA, so here they are: RTM presentation slides.

The day before TMRA, I gave a 3 hour tutorial on programming Ruby and using RTM.
It covered standalone Ruby and basic usage of RTM in the first part. In the second part we created a Ruby on Rails web application and integrated RTM into it.
The slides were mostly a guideline through the tutorial and a reference for explaining things. Without these explanations and the demonstrations I did, it is a load of theory. I removed a bunch of organizational slides to not clutter it up too much.

2007-10-18
This is the preliminary web site for Ruby Topic Maps which has been presented at TMRA 2007.

Mailing List

The Mailinglist interface can be found here: Mailing List

Download

You can install the latest gem from the central rubyforge gem repository by typing

gem install rtm

Of course, don't forget to read the disclaimer below!

Rubyforge Project Page

Instructions

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.x.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[0] # 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 item with type tm.get!('firstname')"
• t["-"] # returns a list of all topic name items with default name type
• t["age"] = 17 # create new occurrence with type tm.get!("age")
• t["age"] # get a list of all age-occurrences

Import/Export

• RTM.from_xtm2(io_object, "base locator")
• map.to_xtm2
• ...

Feedback, Comments, Questions, Bug Reports, Patches

Please send any of the above to bb--rtm-web at bockb dot de (yes, that's bb dash dash rtm dash web...)

Disclaimer

Copyright (c) 2007,2008 Benjamin Bock.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Redistributions in any form must be accompanied by information on
   how to obtain complete source code for the software and any
   accompanying software that uses the software. The source code
   must either be included in the distribution or be available for no
   more than the cost of distribution plus a nominal fee, and must be
   freely redistributable under reasonable conditions. For an
   executable file, complete source code means the source code for all
   modules it contains.  It does not include source code for modules or
   files that typically accompany the major components of the operating
   system on which the executable file runs.

THIS SOFTWARE IS PROVIDED BY BENJAMIN BOCK ``AS IS'' AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT, ARE DISCLAIMED.  IN NO EVENT SHALL BENJAMIN BOCK
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.