words 0.3.1 → 0.4.0

data/.gitignore

@@ -18,9 +18,8 @@ coverage
 rdoc
 pkg
 
-## ECLIPSE
-.loadpath
-.project
-.document
+## Netbeans
+nbproject
 
 ## PROJECT::SPECIFIC
+data

data/README.markdown

@@ -6,6 +6,7 @@ Words implements a fast interface to [Wordnet®](http://wordnet.princeton.edu) w
 
 * Version 0.2 Introduced Pure Ruby Backend
 * Version 0.3 Introduced Evocation Support (see examples & below) as developed by the [Wordnet® Evocation Project](http://wordnet.cs.princeton.edu/downloads/evocation/release-0.4/README.TXT) 
+* Version 0.4 Substantial performance increase in pure mode (now faster at some things than the tokyo backend) and simplification of use! Full refactoring. Move to RSpec for testing.
 
 ## Pre-Installation ##
 
@@ -31,12 +32,20 @@ or (Windows)
 	Download http://wordnetcode.princeton.edu/3.0/WNdb-3.0.tar.gz
 	Unzip
 
+        # due to the way windows tends not to have a folder for things you will
+        # have to specify the location of the wordnet files when using the gem
+
 ## For Tokyo Backend Only ##
 
-Unless you want to use the tokyo backend you are now ready to install Words && build the data, otherwise if you want to use the tokyo backend (FAST!) you will also need [Tokyo Cabinet](http://1978th.net/tokyocabinet/) installed. It should be nice and easy... something like:
+Unless you want to use the tokyo backend you are now ready to install Words (and build the data if you want extras), otherwise if you want to use the tokyo backend (FAST!) you will also need [Tokyo Cabinet](http://1978th.net/tokyocabinet/) installed. It should be nice and easy... something like:
+
+    # osx users should, if ports is installed, simply do
+    sudo ports install tokyocabinet
 
+    # otherwise the best route is from source
     wget http://1978th.net/tokyocabinet/tokyocabinet-1.4.41.tar.gz
-    cd tokyo-cabinet/
+    tar -xzf tokyocabinet-1.4.41.tar.gz
+    cd tokyocabinet-1.4.41/
     ./configure
     make
     sudo make install
@@ -56,18 +65,24 @@ Then your ready to rock and roll. :)
 
 ## Build Data ##
 
-To build the wordnet dataset (or index for pure) file yourself, from the original wordnet files, you can use the bundled "build_wordnet" command
+If all you want to do is use wordnet in it's standard form you don't have to do any databuilding and can skip this section. If however you either
+want to take advantage of evocations ([Wordnet® Evocation Project](http://wordnet.cs.princeton.edu/downloads/evocation/release-0.4/README.TXT)) or want to use the tokyo backend, read on!
+
+To build the wordnet dataset file yourself, from the original wordnet files, you can use the bundled "build_wordnet" command
 
 	build_wordnet -h # this will give you the usage information & additional options/features
 	
-	# this would attempt to build the tokyo backend data locating the original wordnet files through a search...
-	sudo build_wordnet -v --build-tokyo
+	# this would attempt to build the tokyo backend data locating the original wordnet
+        # files through a search...
+	sudo build_wordnet --build-tokyo
 	
-	# this would attempt to build the pure backend index locating the original wordnet files through a search...
-	sudo build_wordnet -v --build-pure
+	# this would attempt to build the tokyo backend locating the original wordnet files
+        # through a search with the addition of evocation support...
+	sudo build_wordnet --build-tokyo-with-evocations
 	
-	# this would attempt to build the tokyo backend index as above but also builds the evocations information into the dataset
-	sudo build_wordnet -v --build-pure --build-evocations
+	# this would attempt to build evocation support for the pure backend
+        # (remember no dataset needs to be built to use wordnet with the pure backend)
+	sudo build_wordnet --build-pure-evocations
 
 ## Usage ##
 
@@ -76,8 +91,19 @@ Heres a few little examples of using words within your programs.
     require 'rubygems'
     require 'words'
     
-    data = Words::Words.new # or: data = Words::Words.new(:pure) for the pure ruby backend
-    
+    data = Words::Wordnet.new # or: data = Words::Words.new(:tokyo) for the tokyo backend
+
+    # to specify a wordnet path Words::Words.new(:pure, '/path/to/wordnet')
+    # to specify the tokyo dataset Words::Words.new(:pure, :search, '/path/to/data.tct')
+
+    # play with connections
+    data.connected? # => true
+    data.close!
+    data.connected? # => false
+    data.open!
+    data.connected? # => true
+    data.connection_type # => :pure or :tokyo depending...
+
     # locate a word
     lemma = data.find("bat")
     
@@ -112,9 +138,14 @@ Heres a few little examples of using words within your programs.
     sense.derivationally_related_forms.first.source_word # => "bat"
     sense.derivationally_related_forms.first.destination_word # => "bat"
     sense.derivationally_related_forms.first.destination # => the synset of v01413191
-    
-    data.find("broadcast").senses.first.evocations # => sense relevant evocations
-    data.find("broadcast").senses.first.evocations[1] # => the evocation at index 1
+
+    if data.evocations? # check for evocation support
+       data.find("broadcast").senses.first.evocations # => sense relevant evocations
+       data.find("broadcast").senses.first.evocations[1] # => the evocation at index 1
+       data.find("broadcast").senses.first.evocations[1][:destination].words # => synset
+    end
+
+    data.close!
     
 These and more examples are available from within the examples.rb file!        
 

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0

data/bin/build_wordnet

@@ -5,34 +5,31 @@ require 'pathname'
 
 # gem includes
 require 'rubygems'
+
+# standard library includes
 require 'trollop'
 require 'zlib'
 require 'net/http'
 
+# local includes
+require File.join(File.dirname(__FILE__), '..', 'lib', 'words.rb')
+
 POS_FILE_TYPES = %w{ adj adv noun verb }
 POS_FILE_TYPE_TO_SHORT = { 'adj' => 'a', 'adv' => 'r', 'noun' => 'n', 'verb' => 'v' }
 
-def locate_wordnet(base_dir)
-  puts "Checking #{base_dir} & spcific children for wordnet files..." if VERBOSE
-  path = Pathname.new base_dir
-  return nil unless path.exist?
-  return path if (path + "data.noun").exist?
-  return path + "dict" if (path + "dict/data.noun").exist?
-end
-
 puts "Words Dataset Constructor 2010 (c) Roja Buck"
 
 opts = Trollop::options do
-  opt :verbose, "Output verbose program detail.", :default => false
-  opt :wordnet, "Location of the wordnet dictionary directory", :default => "Search..."
-  opt :build_tokyo, "Build the tokyo dataset?", :default => false
-  opt :build_pure, "Build the pure ruby dataset?", :default => false
-  opt :build_evocations, "Build the similarity dataset based on the wordnet evocation project (requires internet connection)", :default => false
+    opt :quiet, "Don't output verbose program detail.", :default => false
+    opt :wordnet, "Location of the wordnet dictionary directory", :default => "Search..."
+    opt :build_tokyo, "Build the tokyo wordnet dataset?", :default => false
+    opt :build_tokyo_with_evocations, "Build the tokyo dataset with the similarity dataset based on the wordnet evocation project (requires internet connection)?", :default => false
+    opt :build_pure_evocations, "Build the similarity dataset based on the wordnet evocation project for use with the pure words mode (requires internet connection)", :default => false
 end
-Trollop::die :build_tokyo, "You need to specify whether tokyo dataset or pure ruby index building is required" if !opts[:build_tokyo] && !opts[:build_pure]
-puts "Verbose mode enabled" if (VERBOSE = opts[:verbose])
+Trollop::die :build_tokyo, "You need to specify which dataset you want to build." if !opts[:build_tokyo] && !opts[:build_tokyo_with_evocations] && !opts[:build_pure_evocations]
+puts "Verbose mode enabled" if (VERBOSE = !opts[:quiet])
 
-require 'rufus-tokyo' if opts[:build_tokyo]
+require 'rufus-tokyo' if opts[:build_tokyo] || opts[:build_tokyo_with_evocations]
 
 gem_path = Pathname.new "#{File.dirname(__FILE__)}/.."
 abort "Ensure you run the command using sudo or as a Superuser / Administrator" unless gem_path.writable?
@@ -41,13 +38,11 @@ data_path.mkpath
 
 wordnet_dir = nil
 if opts[:wordnet] == "Search..."
-  ['/usr/share/wordnet', '/usr/local/share/wordnet', '/usr/local/WordNet-3.0'].each do |potential_dir|
-    break unless (wordnet_dir = locate_wordnet potential_dir).nil?
-  end
-  abort( "Unable to locate wordnet dictionary. To specify check --help." ) if wordnet_dir.nil?
+    wordnet_dir = Words::Wordnet.locate_wordnet :search
+    abort( "Unable to locate wordnet dictionary. To specify check --help." ) if wordnet_dir.nil?
 else
-  wordnet_dir = locate_wordnet opts[:wordnet]
-  abort( "Unable to locate wordnet dictionary in directory #{opts[:wordnet]}. Please check and try again." ) if wordnet_dir.nil?
+    wordnet_dir = Words::Wordnet.locate_wordnet opts[:wordnet]
+    abort( "Unable to locate wordnet dictionary in directory #{opts[:wordnet]}. Please check and try again." ) if wordnet_dir.nil?
 end
 
 # At this point we know we should have a wordnet directory within wordnet_dir
@@ -56,9 +51,9 @@ puts "Found wordnet files in #{wordnet_dir}..." if VERBOSE
 index_files = POS_FILE_TYPES.map { |pos| wordnet_dir + "index.#{pos}" }
 data_files = POS_FILE_TYPES.map { |pos| wordnet_dir + "data.#{pos}" }
 
- (index_files + data_files).each do |required_file|
-  abort( "Unable to locate #{required_file} within the wordnet dictionary. Please check your wordnet copy is valid and try again." ) unless required_file.exist?
-  abort( "Cannot get readable permissions to #{required_file} within the wordnet dictionary. Please check the file permissions and try again." ) unless required_file.readable?
+(index_files + data_files).each do |required_file|
+    abort( "Unable to locate #{required_file} within the wordnet dictionary. Please check your wordnet copy is valid and try again." ) unless required_file.exist?
+    abort( "Cannot get readable permissions to #{required_file} within the wordnet dictionary. Please check the file permissions and try again." ) unless required_file.readable?
 end
 
 # At this point we know we have the correct files, though we don't know there validity
@@ -70,88 +65,82 @@ index_hash = Hash.new
 data_hash = Hash.new
 POS_FILE_TYPES.each do |file_pos|
   
-  puts "Building #{file_pos} indexes..." if VERBOSE
+    puts "Building #{file_pos} indexes..." if VERBOSE
   
-  # add indexes
-   (wordnet_dir + "index.#{file_pos}").each_line do |index_line|
-    next if index_line[0, 2] == "  "
-    index_parts = index_line.split(" ")
+    # add indexes
+    (wordnet_dir + "index.#{file_pos}").each_line do |index_line|
+	next if index_line[0, 2] == "  "
+	index_parts = index_line.split(" ")
     
-    lemma, pos, synset_count, pointer_count = index_parts.shift, index_parts.shift, index_parts.shift.to_i, index_parts.shift.to_i
-    pointer_symbols = Array.new(pointer_count).map { POS_FILE_TYPE_TO_SHORT[file_pos] + index_parts.shift }
-    sense_count = index_parts.shift
-    tagsense_count = pos + index_parts.shift
-    synset_ids = Array.new(synset_count).map { POS_FILE_TYPE_TO_SHORT[file_pos] + index_parts.shift }
+	lemma, pos, synset_count, pointer_count = index_parts.shift, index_parts.shift, index_parts.shift.to_i, index_parts.shift.to_i
+	pointer_symbols = Array.new(pointer_count).map { POS_FILE_TYPE_TO_SHORT[file_pos] + index_parts.shift }
+	sense_count = index_parts.shift
+	tagsense_count = pos + index_parts.shift
+	synset_ids = Array.new(synset_count).map { POS_FILE_TYPE_TO_SHORT[file_pos] + index_parts.shift }
     
-    index_hash[lemma] = { "synset_ids" => [], "tagsense_counts" => [] } if index_hash[lemma].nil?
-    index_hash[lemma] = { "lemma" => lemma, "synset_ids" => index_hash[lemma]["synset_ids"] + synset_ids, "tagsense_counts" => index_hash[lemma]["tagsense_counts"] + [tagsense_count] }
+	index_hash[lemma] = { "synset_ids" => [], "tagsense_counts" => [] } if index_hash[lemma].nil?
+	index_hash[lemma] = { "lemma" => lemma, "synset_ids" => index_hash[lemma]["synset_ids"] + synset_ids, "tagsense_counts" => index_hash[lemma]["tagsense_counts"] + [tagsense_count] }
     
-  end
+    end
   
-  if opts[:build_tokyo]
-    puts "Building #{file_pos} data..." if VERBOSE
+    if opts[:build_tokyo] || opts[:build_tokyo_with_evocations]
+	puts "Building #{file_pos} data..." if VERBOSE
     
-    # add data
-     (wordnet_dir + "data.#{file_pos}").each_line do |data_line|
-      next if data_line[0, 2] == "  "
-      data_line, gloss = data_line.split(" | ")
-      data_parts = data_line.split(" ")
+	# add data
+	(wordnet_dir + "data.#{file_pos}").each_line do |data_line|
+	    next if data_line[0, 2] == "  "
+	    data_line, gloss = data_line.split(" | ")
+	    data_parts = data_line.split(" ")
       
-      synset_id, lexical_filenum, synset_type, word_count = POS_FILE_TYPE_TO_SHORT[file_pos] + data_parts.shift, data_parts.shift, data_parts.shift, data_parts.shift.to_i(16)
-      words = Array.new(word_count).map { "#{data_parts.shift}.#{data_parts.shift}" }
-      relations = Array.new(data_parts.shift.to_i).map { "#{data_parts.shift}.#{data_parts.shift}.#{data_parts.shift}.#{data_parts.shift}" }
+	    synset_id, lexical_filenum, synset_type, word_count = POS_FILE_TYPE_TO_SHORT[file_pos] + data_parts.shift, data_parts.shift, data_parts.shift, data_parts.shift.to_i(16)
+	    words = Array.new(word_count).map { "#{data_parts.shift}.#{data_parts.shift}" }
+	    relations = Array.new(data_parts.shift.to_i).map { "#{data_parts.shift}.#{data_parts.shift}.#{data_parts.shift}.#{data_parts.shift}" }
       
-      data_hash[synset_id] = { "synset_id" => synset_id, "lexical_filenum" => lexical_filenum, "synset_type" => synset_type, 
-                          "words" => words.join('|'), "relations" => relations.join('|'), "gloss" => gloss.strip }
+	    data_hash[synset_id] = { "synset_id" => synset_id, "lexical_filenum" => lexical_filenum, "synset_type" => synset_type,
+		"words" => words.join('|'), "relations" => relations.join('|'), "gloss" => gloss.strip }
+	end
     end
-  end
   
 end
 
 score_hash = Hash.new
-if opts[:build_evocations]
-  puts "Downlaoding score data..." if VERBOSE
-  scores_file = data_path + "scores.txt.gz"
-  scores_file.delete if scores_file.exist?
-  File.open(scores_file,'w') do |file|
-    file.write Net::HTTP.get(URI.parse('http://cloud.github.com/downloads/roja/words/scores.txt.gz'))
-  end
-  abort( "Unable to gather similarities information from http://cloud.github.com/downloads/roja/words/scores.txt.gz... Try again later." ) unless scores_file.exist?
+if opts[:build_tokyo_with_evocations] || opts[:build_pure_evocations]
+    puts "Downloading score data..." if VERBOSE
+    scores_file = data_path + "scores.txt.gz"
+    scores_file.delete if scores_file.exist?
+    File.open(scores_file,'w') do |file|
+	file.write Net::HTTP.get(URI.parse('http://cloud.github.com/downloads/roja/words/scores.txt.gz'))
+    end
+    abort( "Unable to gather similarities information from http://cloud.github.com/downloads/roja/words/scores.txt.gz... Try again later." ) unless scores_file.exist?
   
-  puts "Compiling score data..." if VERBOSE
-  Zlib::GzipReader.open(scores_file) do |gz|
-    gz.each_line do |line|
-      mean, median, sense1, sense2 = line.split(',')
-      senses = [sense1, sense2].map! { |sense| sense.strip.split('.') }.map! { |sense| index_hash[sense[0]]["synset_ids"].select { |synset_id| synset_id[0,1] == sense[1].gsub("s", "a") }[sense[2].to_i-1] }
-      senses.each do |sense|
-        relation = (senses - [sense]).first.nil? ? sense : (senses - [sense]).first
-        score_name = sense + "s"
-        score_hash[score_name] = { "relations" => [], "means" => [], "medians" => [] } if score_hash[score_name].nil?
-        score_hash[score_name] = { "relations" => score_hash[score_name]["relations"] << relation, "means" => score_hash[score_name]["means"] << mean, "medians" => score_hash[score_name]["medians"] << median }
-      end unless senses.include? nil
+    puts "Compiling score data..." if VERBOSE
+    Zlib::GzipReader.open(scores_file) do |gz|
+	gz.each_line do |line|
+	    mean, median, sense1, sense2 = line.split(',')
+	    senses = [sense1, sense2].map! { |sense| sense.strip.split('.') }.map! { |sense| index_hash[sense[0]]["synset_ids"].select { |synset_id| synset_id[0,1] == sense[1].gsub("s", "a") }[sense[2].to_i-1] }
+	    senses.each do |sense|
+		relation = (senses - [sense]).first.nil? ? sense : (senses - [sense]).first
+		score_name = sense + "s"
+		score_hash[score_name] = { "relations" => [], "means" => [], "medians" => [] } if score_hash[score_name].nil?
+		score_hash[score_name] = { "relations" => score_hash[score_name]["relations"] << relation, "means" => score_hash[score_name]["means"] << mean, "medians" => score_hash[score_name]["medians"] << median }
+	    end unless senses.include? nil
+	end
     end
-  end
 end
 
-if opts[:build_tokyo]
-  tokyo_hash = Rufus::Tokyo::Table.new((data_path + "wordnet.tct").to_s)
-  index_hash.each { |k,v| tokyo_hash[k] = { "lemma" => v["lemma"], "synset_ids" => v["synset_ids"].join('|'), "tagsense_counts" => v["tagsense_counts"].join('|') } }
-  data_hash.each { |k,v| tokyo_hash[k] = v }
-  score_hash.each { |k,v| tokyo_hash[k] = { "relations" => v["relations"].join('|'), "means" => v["means"].join('|'), "medians" => v["medians"].join('|') } } if opts[:build_evocations]
-  tokyo_hash.close
+if opts[:build_tokyo] || opts[:build_tokyo_with_evocations]
+    tokyo_hash = Rufus::Tokyo::Table.new((data_path + "wordnet.tct").to_s)
+    index_hash.each { |k,v| tokyo_hash[k] = { "lemma" => v["lemma"], "synset_ids" => v["synset_ids"].join('|'), "tagsense_counts" => v["tagsense_counts"].join('|') } }
+    data_hash.each { |k,v| tokyo_hash[k] = v }
+    score_hash.each { |k,v| tokyo_hash[k] = { "relations" => v["relations"].join('|'), "means" => v["means"].join('|'), "medians" => v["medians"].join('|') } } if opts[:build_tokyo_with_evocations]
+    tokyo_hash.close
 end
 
-if opts[:build_pure]
-  index = Hash.new
-  index_hash.each { |k,v| index[k] = [v["lemma"], v["tagsense_counts"].join('|'), v["synset_ids"].join('|')] }
-  File.open(data_path + "index.dmp",'w') do |file|
-    file.write Marshal.dump(index)
-  end
-  if opts[:build_evocations]
+if opts[:build_pure_evocations]
     score = Hash.new
     score_hash.each { |k,v| score[k] = [v["relations"].join('|'), v["means"].join('|'), v["medians"].join('|')] }
     File.open(data_path + "evocations.dmp",'w') do |file|
-      file.write Marshal.dump(score)
+	file.write Marshal.dump(score)
     end
-  end
 end
+

data/examples.rb

@@ -2,40 +2,53 @@
 
 require 'rubygems'
 require 'words'
+#require 'lib/words.rb'
 
 if __FILE__ == $0
   
-  wordnet = Words::Words.new  :pure
-  
-  puts wordnet
-  
-  puts wordnet.find('bat')
-  puts wordnet.find('bat').available_pos.inspect
-  puts wordnet.find('bat').lemma
-  puts wordnet.find('bat').nouns?
-  puts wordnet.find('bat').synsets('noun')
-  puts wordnet.find('bat').noun_ids
-  puts wordnet.find('bat').synsets(:noun).last.words.inspect
-  puts wordnet.find('bat').nouns.last.relations
-  wordnet.find('bat').synsets('noun').last.relations.each { |relation| puts relation.inspect }
-  puts wordnet.find('bat').synsets('noun').last.hyponyms?
-  puts wordnet.find('bat').synsets('noun').last.participle_of_verbs?
-  
-  puts wordnet.find('bat').synsets('noun').last.relations(:hyponym)
-  puts wordnet.find('bat').synsets('noun').last.hyponyms?
-  puts wordnet.find('bat').synsets('noun').last.relations("~")
-  puts wordnet.find('bat').synsets('verb').last.inspect
-  puts wordnet.find('bat').synsets('verb').last.words
-  puts wordnet.find('bat').synsets('verb').last.words_with_lexical_ids.inspect
-  
-  puts wordnet.find('bat').synsets('verb').first.lexical.inspect
-  puts wordnet.find('bat').synsets('verb').first.lexical_description
-  
-  puts wordnet.find('jkashdfajkshfksjdhf')
-  
-  puts wordnet.find("broadcast").senses.first.evocations
-  puts wordnet.find("broadcast").senses.first.evocations[1].inspect
+    wordnet = Words::Wordnet.new :tokyo
+
+    puts wordnet.connected? 
+    wordnet.close!
+    puts wordnet.connected?
+    wordnet.open!
+    puts wordnet.connected?
   
-  wordnet.close
+    puts wordnet
+
+    puts wordnet.find('squash racquet')
+
+    puts wordnet.find('bat')
+    puts wordnet.find('bat').available_pos.inspect
+    puts wordnet.find('bat').lemma
+    puts wordnet.find('bat').nouns?
+    puts wordnet.find('bat').synsets('noun')
+    puts wordnet.find('bat').noun_ids
+    puts wordnet.find('bat').synsets(:noun)[2].words.inspect
+    puts wordnet.find('bat').nouns.last.relations
+    wordnet.find('bat').synsets('noun').last.relations.each { |relation| puts relation.inspect }
+    puts wordnet.find('bat').synsets('noun').last.hyponyms?
+    puts wordnet.find('bat').synsets('noun').last.participle_of_verbs?
+  
+    puts wordnet.find('bat').synsets('noun').last.relations(:hyponym)
+    puts wordnet.find('bat').synsets('noun').last.hyponyms?
+    puts wordnet.find('bat').synsets('noun').last.relations("~")
+    puts wordnet.find('bat').synsets('verb').last.inspect
+    puts wordnet.find('bat').synsets('verb').last.words.inspect
+    puts wordnet.find('bat').synsets('verb').last.words_with_lexical_ids.inspect
+  
+    puts wordnet.find('bat').synsets('verb').first.lexical.inspect
+    puts wordnet.find('bat').synsets('verb').first.lexical_description
+  
+    puts wordnet.find('jkashdfajkshfksjdhf')
+
+    if wordnet.evocations?
+	puts wordnet.find("broadcast").senses.first.evocations
+	puts wordnet.find("broadcast").senses.first.evocations.means
+	puts wordnet.find("broadcast").senses.first.evocations[1].inspect
+	puts wordnet.find("broadcast").senses.first.evocations[20][:destination].words
+    end
+
+    wordnet.close!
   
 end

data/lib/evocations.rb

@@ -0,0 +1,85 @@
+# local includes
+require File.join(File.dirname(__FILE__), 'synset.rb')
+
+module Words
+
+    class Evocations
+
+	def initialize(evocation_construct, source_synset, wordnet_connection)
+
+	    @wordnet_connection = wordnet_connection
+	    @source = source_synset
+	    @evocation_construct = evocation_construct
+
+	end
+
+	def means
+
+	    @means ||= @evocation_construct["means"].split('|')
+
+	    @means
+
+	end
+
+	def medians
+
+	    @medians ||= @evocation_construct["medians"].split('|')
+
+	    @medians
+
+	end
+
+	def size
+
+	    means.size
+
+	end
+
+	def first
+
+	    self[0]
+
+	end
+
+	def last
+
+	    self[size-1]
+
+	end
+
+	def [] (index)
+
+	    { :destination => Synset.new(destination_ids[index], @wordnet_connection, @source.homographs), :mean => means[index], :median => medians[index] }
+
+	end
+
+	def destinations(pos = :all)
+
+	    destination_ids(pos).map { |synset_id| Synset.new synset_id, @wordnet_connection, @source.homographs }
+
+	end
+
+	def destination_ids(pos = :all)
+
+	    @destination_ids ||= @evocation_construct["relations"].split('|')
+
+	    case
+	    when Homographs::SYMBOL_TO_POS.include?(pos.to_sym)
+		@destination_ids.select { |synset_id| synset_id[0,1] == Homographs::SYMBOL_TO_POS[pos.to_sym] }
+	    when Homographs::POS_TO_SYMBOL.include?(pos.to_s)
+		@destination_ids.select { |synset_id| synset_id[0,1] == pos.to_s }
+	    else
+		@destination_ids
+	    end
+
+	end
+
+	def to_s
+
+	    "#{size} evocations from the #{@source}"
+      
+	end
+
+    end
+
+end

data/lib/homographs.rb

@@ -0,0 +1,106 @@
+# local includes
+require File.join(File.dirname(__FILE__), 'synset.rb')
+
+module Words
+
+  class Homographs
+
+    POS_TO_SYMBOL = {"n" => :noun, "v" => :verb, "a" => :adjective, "r" => :adverb}
+    SYMBOL_TO_POS = POS_TO_SYMBOL.invert
+
+    def initialize(raw_homographs, wordnet_connection)
+
+      @wordnet_connection = wordnet_connection
+      @raw_homographs = raw_homographs
+
+      # construct some conveniance menthods for relation type access
+      SYMBOL_TO_POS.keys.each do |pos|
+        self.class.send(:define_method, "#{pos}s?") do
+          size(pos) > 0
+        end
+        self.class.send(:define_method, "#{pos}s") do
+          synsets(pos)
+        end
+        self.class.send(:define_method, "#{pos}_count") do
+          size(pos)
+        end
+        self.class.send(:define_method, "#{pos}_ids") do
+          synset_ids(pos)
+        end
+      end
+      
+    end
+
+    def tagsense_counts
+
+      @tagsense_counts ||= @raw_homographs["tagsense_counts"].split('|').map { |count| { POS_TO_SYMBOL[count[0,1]] => count[1..-1].to_i }  }
+
+      @tagsense_counts
+
+    end
+
+    def lemma
+
+      @lemma ||= @raw_homographs["lemma"].gsub('_', ' ')
+
+      @lemma
+
+    end
+
+    def available_pos
+
+      @available_pos ||= synset_ids.map { |synset_id| POS_TO_SYMBOL[synset_id[0,1]] }.uniq
+
+      @available_pos
+
+    end
+
+    def to_s
+
+      @to_s ||= [lemma, " " + available_pos.join("/")].join(",")
+
+      @to_s
+
+    end
+
+    def size(pos = :all)
+
+      synset_ids(pos).size
+
+    end
+
+    def synsets(pos = :all)
+
+      synset_ids(pos).map { |synset_id| Synset.new synset_id, @wordnet_connection, self }
+
+    end
+
+    def synset_ids(pos = :all)
+
+      @synset_ids ||= @raw_homographs["synset_ids"].split('|')
+
+      case
+      when SYMBOL_TO_POS.include?(pos.to_sym)
+        @synset_ids.select { |synset_id| synset_id[0,1] == SYMBOL_TO_POS[pos.to_sym] }
+      when POS_TO_SYMBOL.include?(pos.to_s)
+        @synset_ids.select { |synset_id| synset_id[0,1] == pos.to_s }
+      else
+        @synset_ids
+      end
+
+    end
+
+    def inspect
+
+      @raw_homographs.inspect
+
+    end
+
+    alias word lemma
+    alias pos available_pos
+    alias senses synsets
+    alias sense_ids synset_ids
+
+  end
+
+end