rwordnet 0.1.0

data/examples/dictionary.rb

@@ -0,0 +1,21 @@
+# Use WordNet as a command-line dictionary.
+require 'rubygems'
+require 'wordnet'
+
+if ARGV.size != 1
+  puts "Usage: ruby dictionary.rb word"
+  exit(1)
+end
+
+word = ARGV[0]
+
+# Find all the lemmas for a word (i.e., whether it occurs as a noun, verb, etc.)
+lemmas = WordNet::WordNetDB.find(word)
+
+# Print out each lemma with a list of possible meanings.
+lemmas.each do |lemma| 
+  puts lemma
+  lemma.synsets.each_with_index do |synset,i|
+    puts "\t#{i+1}) #{synset.gloss}"
+  end
+end

data/examples/full_hypernym.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'wordnet'
+
+# Open the index file for nouns
+index = WordNet::NounIndex.new
+# Find the word 'fruit'
+lemma = index.find("fruit")
+# Find all the synsets for 'fruit', and pick the first one.
+synset = lemma.synsets[0]
+puts synset
+# Print the full hypernym derivation for the first sense of 'fruit'.
+synset.expanded_hypernym.each { |d| puts d }

data/lib/wordnet.rb

@@ -0,0 +1,7 @@
+require 'wordnet/pointer'
+require 'wordnet/wordnetdb'
+require 'wordnet/index'
+require 'wordnet/lemma'
+require 'wordnet/pointers'
+require 'wordnet/pos'
+require 'wordnet/synset'

data/lib/wordnet/index.rb

@@ -0,0 +1,65 @@
+module WordNet
+
+# Index is a WordNet lexicon. Note that Index is the base class; you probably want to be using the NounIndex, VerbIndex, etc. classes instead.
+class Index
+  # Create a new index for the given part of speech. +pos+ can be one of +noun+, +verb+, +adj+, or +adv+.
+  def initialize(pos)
+    @pos = pos
+    @db = {}
+  end
+  
+  # Find a lemma for a given word. Returns a Lemma which can then be used to access the synsets for the word.
+  def find(lemma_str)
+    # Look for the lemma in the part of the DB already read...
+    @db.each_key do |word|
+      return @db[word] if word == lemma_str
+    end
+    
+    # If we didn't find it, read in some more from the DB. Some optimisation is possible here. TODO.
+    index = WordNetDB.open(File.join(WordNetDB.path,"dict","index.#{@pos}"))
+    if not index.closed?
+      loop do
+        break if index.eof?
+        line = index.readline
+        lemma = Lemma.new(line)
+        @db[lemma.word] = lemma
+        if line =~ /^#{lemma_str} /
+          return lemma
+        end
+      end
+      index.close
+    end
+    
+    return nil
+  end
+end
+
+# An Index of nouns.
+class NounIndex < Index
+  def initialize
+    super("noun")
+  end
+end
+
+# An Index of verbs.
+class VerbIndex < Index
+  def initialize
+    super("verb")
+  end
+end
+
+# An Index of adjectives.
+class AdjectiveIndex < Index
+  def initialize
+    super("adj")
+  end
+end
+
+# An Index of adverbs.
+class AdverbIndex < Index
+  def initialize
+    super("adv")
+  end
+end
+
+end

data/lib/wordnet/lemma.rb

@@ -0,0 +1,38 @@
+module WordNet
+
+# Represents a single word in the WordNet lexicon, which can be used to look up a set of synsets.
+class Lemma
+  attr_accessor :lemma, :pos, :synset_cnt, :p_cnt, :ptr_symbol, :tagsense_cnt, :synset_offset
+  
+  # Create a lemma from a line in an index file. You should be creating Lemmas by hand; instead,
+  # use the WordNet#find and Index#find methods to find the Lemma for a word.
+  def initialize(index_line)
+    line = index_line.split(" ")
+    
+    @lemma = line.shift
+    @pos = line.shift
+    @synset_cnt = line.shift.to_i
+    @p_cnt = line.shift.to_i
+    
+    @ptr_symbol = []
+    @p_cnt.times { @ptr_symbol.push line.shift }
+    line.shift # Throw away redundant sense_cnt
+    @tagsense_cnt = line.shift.to_i
+    @synset_offset = []
+    @synset_cnt.times { @synset_offset.push line.shift.to_i }
+  end
+  
+  # Return a list of synsets for this Lemma. Each synset represents a different sense, or meaning, of the word.
+  def get_synsets
+    return @synset_offset.map { |offset| Synset.new(@pos, offset) }
+  end
+  
+  def to_s
+    [@lemma, @pos].join(",")
+  end
+  
+  alias synsets get_synsets
+  alias word lemma
+end
+
+end

data/lib/wordnet/pointer.rb

@@ -0,0 +1,15 @@
+module WordNet
+
+# Convenience class for treating hashes as objects, i.e. obj[:key] <=> obj.key. I know
+# this is probably a bad idea, but it's so convenient...
+class Pointer < Hash
+  def method_missing(msg, *args)
+    if self.include?(msg)
+      return self[msg] 
+    else
+      throw NoMethodError.new("undefined method `#{msg}' for #{self}:Pointer")
+    end
+  end
+end
+
+end

data/lib/wordnet/pointers.rb

@@ -0,0 +1,37 @@
+# A container for various constants. In particular, contains constants representing the WordNet symbols used to look up synsets by relation, i.e. Hypernym/Hyponym.
+# Use these symbols in conjunction with the Synset#get_relation method.
+
+module WordNet
+
+  NounPointers = {"-c"=>"Member of this domain - TOPIC", "+"=>"Derivationally related form", "%p"=>"Part meronym", "~i"=>"Instance Hyponym", "@"=>"Hypernym", ";r"=>"Domain of synset - REGION", "!"=>"Antonym", "#p"=>"Part holonym", "%s"=>"Substance meronym", ";u"=>"Domain of synset - USAGE", "-r"=>"Member of this domain - REGION", "#s"=>"Substance holonym", "="=>"Attribute", "-u"=>"Member of this domain - USAGE", ";c"=>"Domain of synset - TOPIC", "%m"=>"Member meronym", "~"=>"Hyponym", "@i"=>"Instance Hypernym", "#m"=>"Member holonym"}
+  VerbPointers = {"+"=>"Derivationally related form", "@"=>"Hypernym", ";r"=>"Domain of synset - REGION", "!"=>"Antonym", ";u"=>"Domain of synset - USAGE", "$"=>"Verb Group", ";c"=>"Domain of synset - TOPIC", ">"=>"Cause", "~"=>"Hyponym", "*"=>"Entailment"}
+  AdjectivePointers = {";r"=>"Domain of synset - REGION", "!"=>"Antonym", "\\"=>"Pertainym (pertains to noun)", "<"=>"Participle of verb", "&"=>"Similar to", "="=>"Attribute", ";c"=>"Domain of synset - TOPIC"}
+  AdverbPointers = {";r"=>"Domain of synset - REGION", "!"=>"Antonym", ";u"=>"Domain of synset - USAGE", "\\"=>"Derived from adjective", ";c"=>"Domain of synset - TOPIC"}
+
+  MemberOfThisDomainTopic = "-c"
+  DerivationallyRelatedForm = "+"
+  PartMeronym = "%p"
+  InstanceHyponym = "~i"
+  Hypernym = "@"
+  DomainOfSynsetRegion = ";r"
+  Antonym = "!"
+  PartHolonym = "#p"
+  SubstanceMeronym = "%s"
+  VerbGroup = "$"
+  DomainOfSynsetUsage = ";u"
+  MemberOfThisDomainRegion = "-r"
+  SubstanceHolonym = "#s"
+  DerivedFromAdjective = "\\"
+  ParticipleOfVerb = "<"
+  SimilarTo = "&"
+  Attribute = "="
+  AlsoSee = "^"
+  Cause = ">"
+  MemberOfThisDomainUsage = "-u"
+  DomainOfSynsetTopic = ";c"
+  MemberMeronym = "%m"
+  Hyponym = "~"
+  InstanceHypernym = "@i"
+  Entailment = "*"
+  MemberHolonym = "#m"
+end

data/lib/wordnet/pos.rb

@@ -0,0 +1,3 @@
+module WordNet
+  SynsetType = {"n" => "noun", "v" => "verb", "adj" => "adj", "adv" => "adv"}
+end

data/lib/wordnet/synset.rb

@@ -0,0 +1,90 @@
+module WordNet
+
+# Represents a synset (or group of synonymous words) in WordNet. Synsets are related to each other by various (and numerous!)
+# relationships, including Hypernym (x is a hypernym of y <=> x is a parent of y) and Hyponym (x is a child of y)
+class Synset
+  attr_reader :gloss, :synset_offset, :lex_filenum, :ss_type, :w_cnt, :wordcounts
+
+  # Create a new synset by reading from the data file specified by +pos+, at +offset+ bytes into the file. This is how
+  # the WordNet database is organized. You shouldn't be creating Synsets directly; instead, use Lemma#synsets.
+  def initialize(pos, offset)
+    data = File.open(File.join(WordNetDB.path,"dict","data.#{SynsetType[pos]}"),"r")
+    data.seek(offset)
+    data_line = data.readline.strip
+    data.close
+    
+    info_line, @gloss = data_line.split(" | ")
+    line = info_line.split(" ")
+    
+    @synset_offset = line.shift
+    @lex_filenum = line.shift
+    @ss_type = line.shift
+    @w_cnt = line.shift.to_i
+    @wordcounts = {}
+    @w_cnt.times do
+      @wordcounts[line.shift] = line.shift.to_i
+    end
+    
+    @p_cnt = line.shift.to_i
+    @pointers = []
+    @p_cnt.times do
+      pointer = Pointer.new
+      pointer[:symbol] = line.shift,
+      pointer[:offset] = line.shift.to_i
+      pointer[:pos] = line.shift
+      pointer[:source] = line.shift
+      pointer[:is_semantic?] = (pointer[:source] == "0000")
+      pointer[:target] = pointer[:source][2..3]
+      pointer[:source] = pointer[:source][0..1]
+      pointer[:symbol] = pointer[:symbol][0]
+      @pointers.push pointer
+    end
+  end
+  
+  # How many words does this Synset include?
+  def size
+    @wordcounts.size
+  end
+  
+  # Get a list of words included in this Synset
+  def words
+    @wordcounts.keys
+  end
+  
+  # List of valid +pointer_symbol+s is in pointers.rb
+  def get_relation(pointer_symbol)
+    @pointers.reject { |pointer| pointer.symbol != pointer_symbol }.map { |pointer| Synset.new(@ss_type, pointer.offset) }
+  end
+  
+  # Get the Synset of this sense's antonym
+  def antonym
+    get_relation(Antonym)
+  end
+  
+  # Get the parent synset (higher-level category, i.e. fruit -> reproductive_structure).
+  def hypernym
+    get_relation(Hypernym)[0]
+  end
+  
+  # Get the child synset(s) (i.e., lower-level categories, i.e. fruit -> edible_fruit)
+  def hyponym
+    get_relation(Hyponym)
+  end
+  
+  # Get the entire hypernym tree (from this synset all the way up to +entity+) as an array.
+  def expanded_hypernym
+    parent = self.hypernym
+    return [] if parent.nil?
+    
+    return [parent, parent.expanded_hypernym].flatten
+  end
+  
+  def to_s
+    "(#{@ss_type}) #{words.map {|x| x.gsub('_',' ')}.join(', ')} (#{@gloss})"
+  end
+  
+  alias parent hypernym
+  alias children hyponym
+end
+
+end

data/lib/wordnet/wordnetdb.rb

@@ -0,0 +1,54 @@
+module WordNet
+
+# Represents the WordNet database, and provides some basic interaction.
+class WordNetDB
+  # By default, use the bundled WordNet
+  @@path = File.join(File.dirname(__FILE__),"/../../WordNet-3.0/")
+  @@files = {}
+
+  # To use your own WordNet installation (rather than the one bundled with rwordnet:
+  def WordNetDB.path=(path_to_wordnet)
+    @@path = path_to_wordnet
+  end
+  
+  # Returns the path to the WordNet installation currently in use. Defaults to the bundled version of WordNet.
+  def WordNetDB.path
+    @@path
+  end
+  
+  # Look up a word in WordNet. Returns a list of lemmas occuring in any of the index files (noun, verb, adjective, adverb).
+  def WordNetDB.find(word)
+    lemmas = []
+    [NounIndex, VerbIndex, AdjectiveIndex, AdverbIndex].each do |index|
+      lemmas.push index.new.find(word)
+    end
+    return lemmas.flatten.reject { |x| x.nil? }
+  end
+  
+  # Register a new DB file handle. You shouldn't need to call this method; it's called automatically every time you open an index or data file.
+  def WordNetDB.open(path)
+    # If the file is already open, just return the handle.
+    return @@files[path] if @@files.include?(path) and not @@files[path].closed?
+    
+    # Open and store 
+    @@files[path] = File.open(path,"r")
+    return @@files[path]
+  end
+  
+  # You should call this method after you're done using WordNet.
+  def WordNetDB.close
+    WordNetDB.finalize(0)
+  end
+  
+  def WordNetDB.finalize(id)
+    @@files.each_value do |handle| 
+      begin
+        handle.close
+      rescue IOError
+        ; # Keep going, close the next file.
+      end
+    end
+  end
+end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,17 @@
+require "test/unit"
+require File.dirname(__FILE__) + "/../lib/wordnet"
+
+
+class << Test::Unit::TestCase
+  def test(name, &block)
+    test_name = :"test_#{name.gsub(' ','_')}"
+    raise ArgumentError, "#{test_name} is already defined" if self.instance_methods.include? test_name.to_s
+    define_method test_name, &block
+  end
+  
+  def expect(expected_value, &block)
+    define_method :"test_#{caller.first.split("/").last}" do
+      assert_equal expected_value, instance_eval(&block)
+    end 
+  end
+end

data/test/unit/index_test.rb

@@ -0,0 +1,21 @@
+require File.dirname(__FILE__) + "/../test_helper.rb"
+
+class TestIndex < Test::Unit::TestCase
+  @@index = nil
+  
+  def setup
+    @@index = WordNet::NounIndex.new if @@index.nil?
+  end
+  
+  test 'find a lemma by string' do
+    lemma = @@index.find("fruit")
+    assert_equal "fruit,n",lemma.to_s
+  end
+  
+  test 'get synsets for a lemma' do
+    lemma = @@index.find("fruit")
+    synsets = lemma.get_synsets
+    assert_equal 3, synsets.size
+    assert_equal "(n) yield, fruit (an amount of a product)",synsets[1].to_s
+  end
+end

data/test/unit/synset_test.rb

@@ -0,0 +1,44 @@
+require File.dirname(__FILE__) + "/../test_helper.rb"
+
+class TestSynset < Test::Unit::TestCase
+  @@synsets = nil
+
+  def setup
+    if @@synsets.nil?
+      index = WordNet::NounIndex.new
+      lemma = index.find("fruit")
+      @@synsets = lemma.get_synsets
+    end
+  end
+  
+  test 'get synsets for a lemma' do
+    assert_equal 3, @@synsets.size
+    assert_equal "(n) fruit (the ripened reproductive body of a seed plant)",@@synsets[0].to_s
+    assert_equal "an amount of a product",@@synsets[1].gloss
+  end
+  
+  test 'get hypernym for a synset' do
+    hypernym = @@synsets[0].get_relation(WordNet::Hypernym)
+    hypernym = @@synsets[0].hypernym
+    assert_equal 1,hypernym.size
+    assert_equal "(n) reproductive structure (the parts of a plant involved in its reproduction)",hypernym.to_s
+  end
+
+  test 'test shorthand for get_relation' do
+    hypernym = @@synsets[0].get_relation(WordNet::Hypernym)
+    hypernym2 = @@synsets[0].hypernym
+    assert_equal hypernym[0].gloss, hypernym2.gloss
+  end
+  
+  test 'get hyponyms for a synset' do
+    hyponym = @@synsets[0].get_relation(WordNet::Hyponym)
+    assert_equal 29,hyponym.size
+    assert_equal "fruit of various buckthorns yielding dyes or pigments",hyponym[26].gloss
+  end
+  
+  test 'test expanded hypernym tree' do
+    expanded = @@synsets[0].expanded_hypernym
+    assert_equal 8, expanded.size
+    assert_equal "entity", expanded[expanded.size-1].words[0]
+  end
+end