rwordnet 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4bea9b677b6a581d27c04ad1912c3034bf8329d8
-  data.tar.gz: 4fdef6fdfdbe2373b445f7857d3fe5ff5071fba2
+  metadata.gz: af20be262ff83829299dfcaab7bdaf6daca77d9e
+  data.tar.gz: 5fdf6de52538acc9e2e6c6cd59af7f8055aa1361
 SHA512:
-  metadata.gz: c1471523dcb27e496eb72b406f37ddd83184dfcecbcabe95c492f6018b29fa53180d06035b7f9c0a938bfde0e4c28a37f89473c0b3a712be527ed2abf6261af3
-  data.tar.gz: 25cf40f306f3dfcf8076d9430cfd5d8d805af9198762a530ed4f293e5b0c4e5ccc680e941b2256f63c5141d5499ad77b7821eec5b4e245a72a47e1f9ca6e83b3
+  metadata.gz: 9f232d93029c8f200e6ba54af4461df6a4430e7ecc1189510cee59447303a350bb47f6deab13ad9b3cb7d6730b52d514b73377f673f1d81c03b4997d2a6ababe
+  data.tar.gz: d374907bacd015be0274bb8f8219d1803bc884b9c852f99c83441ca303e7fe2ac4687be7341462e6bb5fb54657f09c91d4cf64edc746ee27c8577ce2286a2942

data/README.markdown

@@ -1,6 +1,9 @@
 # A pure Ruby interface to WordNet #
 
 [![Build Status](https://travis-ci.org/doches/rwordnet.png)](https://travis-ci.org/doches/rwordnet)
+[![Documentation Status](https://inch-ci.org/github/doches/rwordnet.svg?branch=master)](https://inch-ci.org/github/doches/rwordnet)
+[![Code Climate](https://codeclimate.com/github/doches/rwordnet/badges/gpa.svg)](https://codeclimate.com/github/doches/rwordnet)
+[![Test Coverage](https://codeclimate.com/github/doches/rwordnet/badges/coverage.svg)](https://codeclimate.com/github/doches/rwordnet/coverage)
 
 ## Summary ##
 

data/examples/full_hypernym.rb

@@ -1,9 +1,9 @@
 require 'wordnet'
 
-# Find the word 'fruit'
-lemma = WordNet::Lemma.find("fruit", :noun)
-# Find all the synsets for 'fruit', and pick the first one.
+# Find the word 'dog'
+lemma = WordNet::Lemma.find("dog", :noun)
+# Find all the synsets for 'dog', 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 }
+# Print the full hypernym derivation for the first sense of 'dog'.
+synset.expanded_hypernyms.each { |d| puts d }

data/examples/morphy.rb

@@ -0,0 +1,20 @@
+require 'wordnet'
+
+puts 'dogs'
+puts '--------------'
+puts 'as noun'
+p WordNet::Synset.morphy('dogs', 'noun')
+puts 'as verb'
+p WordNet::Synset.morphy('dogs', 'verb')
+
+
+puts ''
+puts 'hiking'
+puts '--------------'
+puts 'as noun'
+p WordNet::Synset.morphy('hiking', 'noun')
+puts 'as verb'
+p WordNet::Synset.morphy('hiking', 'verb')
+puts 'as all'
+p WordNet::Synset.morphy_all('hiking')
+

data/examples/synset_find.rb

@@ -0,0 +1,8 @@
+require 'wordnet'
+
+puts 'hiking'
+WordNet::Synset.find_all('hiking').each{|d| puts d}
+
+puts''
+puts 'dogs'
+WordNet::Synset.find_all('dogs').each{|d| puts d}

data/lib/wordnet/db.rb

@@ -1,14 +1,25 @@
+require 'stringio'
+
 module WordNet
   # Represents the WordNet database, and provides some basic interaction.
   class DB
     # By default, use the bundled WordNet
     @path = File.expand_path("../../../WordNet-3.0/", __FILE__)
 
+    class << self; attr_accessor :cached end
+    @raw_wordnet = {}
+
+
     class << self
       # To use your own WordNet installation (rather than the one bundled with rwordnet:
       # Returns the path to the WordNet installation currently in use. Defaults to the bundled version of WordNet.
       attr_accessor :path
 
+      # Open a wordnet database. You shouldn't have to call this directly; it's
+      # handled by the autocaching implemented in lemma.rb.
+      #
+      # `path` should be a string containing the absolute path to the root of a
+      # WordNet installation.
       def open(path, &block)
         File.open(File.join(self.path, path), "r", &block)
       end

data/lib/wordnet/lemma.rb

@@ -2,9 +2,27 @@ module WordNet
   # Represents a single word in the WordNet lexicon, which can be used to look up a set of synsets.
   class Lemma
     SPACE = ' '
-    attr_accessor :word, :pos, :pointer_symbols, :tagsense_count, :synset_offsets, :id
 
-    # Create a lemma from a line in an lexicon file. You should be creating Lemmas by hand; instead,
+    # The word this lemma represents
+    attr_accessor :word
+
+    # The part of speech (noun, verb, adjective) of this lemma. One of 'n', 'v', 'a' (adjective), or 'r' (adverb)
+    attr_accessor :pos
+
+    # The number of times the sense is tagged in various semantic concordance texts. A tagsense_count of 0 indicates that the sense has not been semantically tagged.
+    attr_accessor :tagsense_count
+
+    # The offset, in bytes, at which the synsets contained in this lemma are stored in WordNet's internal database.
+    attr_accessor :synset_offsets
+
+    # A unique integer id that references this lemma. Used internally within WordNet's database.
+    attr_accessor :id
+
+    # An array of valid pointer symbols for this lemma. The list of all valid
+    # pointer symbols is defined in pointers.rb.
+    attr_accessor :pointer_symbols
+
+    # Create a lemma from a line in an lexicon file. You should not be creating Lemmas by hand; instead,
     # use the WordNet::Lemma.find and WordNet::Lemma.find_all methods to find the Lemma for a word.
     def initialize(lexicon_line, id)
       @id = id
@@ -24,6 +42,8 @@ module WordNet
       @synset_offsets.map { |offset| Synset.new(@pos, offset) }
     end
 
+    # Returns a compact string representation of this lemma, e.g. "fall, v" for
+    # the verb form of the word "fall".
     def to_s
       [@word, @pos].join(",")
     end
@@ -31,6 +51,7 @@ module WordNet
     class << self
       @@cache = {}
 
+      # Find all lemmas for this word across all known parts of speech
       def find_all(word)
         [:noun, :verb, :adj, :adv].flat_map do |pos|
           find(word, pos) || []

data/lib/wordnet/pointer.rb

@@ -1,7 +1,25 @@
 module WordNet
+  # Pointers represent the relations between the words in one synset and another.
   class Pointer
-    attr_reader :symbol, :offset, :pos, :source, :target
+    # The symbol that devices the relationship this pointer represents, e.g. "!" for verb antonym. Valid
+    # pointer symbols are defined in pointers.rb
+    attr_reader :symbol
 
+    # The offset, in bytes, of this pointer in WordNet's internal database.
+    attr_reader :offset
+
+    # The part of speech this pointer represents. One of 'n', 'v', 'a' (adjective), or 'r' (adverb).
+    attr_reader :pos
+
+    # The synset from which this pointer...points.
+    attr_reader :source
+
+    # The synset to which this pointer...points.
+    attr_reader :target
+
+    # Create a pointer. Pointers represent the relations between the words in one synset and another,
+    # and are referenced by a shorthand symbol (e.g. '!' for verb antonym). The list
+    # of valid pointer symbols is defined in pointers.rb
     def initialize(symbol: raise, offset: raise, pos: raise, source: raise)
       @symbol, @offset, @pos, @source = symbol, offset, pos, source
       @target = source.slice!(2,2)

data/lib/wordnet/synset.rb

@@ -4,7 +4,47 @@ 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, :synset_type, :word_counts, :pos_offset, :pos
+    @morphy_path = File.expand_path("../../../morphy/", __FILE__)
+    @exception_map = {}
+    @morphological_substitutions = {
+        'noun' => [['s', ''], ['ses', 's'], ['ves', 'f'], ['xes', 'x'],
+               ['zes', 'z'], ['ches', 'ch'], ['shes', 'sh'],
+               ['men', 'man'], ['ies', 'y']],
+        'verb' => [['s', ''], ['ies', 'y'], ['es', 'e'], ['es', ''],
+               ['ed', 'e'], ['ed', ''], ['ing', 'e'], ['ing', '']],
+        'adj' => [['er', ''], ['est', ''], ['er', 'e'], ['est', 'e']],
+        'adv' => []}
+
+    # Get the offset, in bytes, at which this synset's information is stored in WordNet's internal DB.
+    # You almost certainly don't care about this.
+    attr_reader :synset_offset
+
+    # A two digit decimal integer representing the name of the lexicographer file containing the synset for the sense.
+    # Probably only of interest if you're using a wordnet database marked up with custom attributes, and you
+    # want to ensure that you're using your own additions.
+    attr_reader :lex_filenum
+
+    # Get the list of words (and their frequencies within the WordNet graph) contained
+    # in this Synset.
+    attr_reader :word_counts
+
+    # Get the part of speech type of this synset. One of 'n' (noun), 'v' (verb), 'a' (adjective), or 'r' (adverb)
+    attr_reader :synset_type
+
+    # Get the offset, in bytes, at which this synset's POS information is stored in WordNet's internal DB.
+    # You almost certainly don't care about this.
+    attr_reader :pos_offset
+
+    # Get a shorthand representation of the part of speech this synset represents, e.g. "v" for verbs.
+    attr_reader :pos
+
+    # Get a string representation of this synset's gloss. "Gloss" is a human-readable
+    # description of this concept, often with example usage, e.g:
+    #
+    #    move upward; "The fog lifted"; "The smoke arose from the forest fire"; "The mist uprose from the meadows"
+    #
+    # for the second sense of the verb "fall"
+    attr_reader :gloss
 
     # 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.
@@ -40,6 +80,93 @@ module WordNet
       end
     end
 
+    # Ported from python NLTK
+    # Load all synsets with a given lemma and part of speech tag.
+    # If no pos is specified, all synsets for all parts of speech
+    # will be loaded. 
+    # If lang is specified, all the synsets associated with the lemma name
+    # of that language will be returned.
+    def self.find(word, pos)
+        word = word.downcase
+        lemmas = self.morphy(word, pos).map{|form| WordNet::Lemma.find(form, pos)}
+        lemmas.map{|lemma| lemma.synsets}.flatten
+    end
+
+    def self.find_all(word)
+        SYNSET_TYPES.values.map{|pos| self.find(word, pos)}.flatten
+    end
+
+    def self.load_exception_map
+        SYNSET_TYPES.each do |_, pos|
+            @exception_map[pos] = {}
+            File.open(File.join(@morphy_path, 'exceptions', "#{pos}.exc"), 'r').each_line do |line|
+                line = line.split
+                @exception_map[pos][line[0]] = line[1..-1]
+            end
+        end
+    end
+
+    def self._apply_rules(forms, pos)
+        substitutions = @morphological_substitutions[pos]
+        out = []
+        forms.each do |form|
+            substitutions.each do |old, new|
+                if form.end_with? old
+                    out.push form[0...-old.length] + new
+                end
+            end
+        end
+        return out
+    end
+
+    def self._filter_forms(forms, pos)
+        forms.reject{|form| Lemma.find(form, pos).nil?}.uniq
+    end
+
+    # ported from nltk python
+    # from jordanbg:
+    # Given an original string x
+    # 1. Apply rules once to the input to get y1, y2, y3, etc.
+    # 2. Return all that are in the database
+    # 3. If there are no matches, keep applying rules until you either
+    #    find a match or you can't go any further
+    def self.morphy(form, pos)
+        if @exception_map == {}
+            self.load_exception_map
+        end
+        exceptions = @exception_map[pos]
+
+        # 0. Check the exception lists
+        if exceptions.has_key? form
+            return self._filter_forms([form] + exceptions[form], pos)
+        end
+
+        # 1. Apply rules once to the input to get y1, y2, y3, etc.
+        forms = self._apply_rules([form], pos)
+
+        # 2. Return all that are in the database (and check the original too)
+        results = self._filter_forms([form] + forms, pos)
+        if results != []
+            return results
+        end
+
+        # 3. If there are no matches, keep applying rules until we find a match
+        while forms.length > 0
+            forms = self._apply_rules(forms, pos)
+            results = self._filter_forms(forms, pos)
+            if results != []
+                return results
+            end
+        end
+
+        # Return an empty list if we can't find anything
+        return []
+    end
+
+    def self.morphy_all(form)
+        SYNSET_TYPES.values.map{|pos| self.morphy(form, pos)}.flatten
+    end
+
     # How many words does this Synset include?
     def word_count
       @word_counts.size
@@ -50,14 +177,19 @@ module WordNet
       @word_counts.keys
     end
 
-    # List of valid +pointer_symbol+s is in pointers.rb
+    # Get an array of Synsets with the relation `pointer_symbol` relative to this
+    # Synset. Mostly, this is an internal method used by convience methods (e.g. Synset#antonym), but
+    # it can take any valid valid +pointer_symbol+ defined in pointers.rb.
+    #
+    # Example (get the gloss of an antonym for 'fall'):
+    #     WordNet::Lemma.find("fall", :verb).synsets[1].relation("!")[0].gloss
     def relation(pointer_symbol)
       @pointers.select { |pointer| pointer.symbol == pointer_symbol }.
         map! { |pointer| Synset.new(@synset_type, pointer.offset) }
     end
 
     # Get the Synset of this sense's antonym
-    def antonym
+    def antonyms
       relation(ANTONYM)
     end
 
@@ -66,13 +198,18 @@ module WordNet
       relation(HYPERNYM)[0]
     end
 
+    # Get the parent synset (higher-level category, i.e. fruit -> reproductive_structure).
+    def hypernyms
+      relation(HYPERNYM)
+    end
+
     # Get the child synset(s) (i.e., lower-level categories, i.e. fruit -> edible_fruit)
-    def hyponym
+    def hyponyms
       relation(HYPONYM)
     end
 
     # Get the entire hypernym tree (from this synset all the way up to +entity+) as an array.
-    def expanded_hypernym
+    def expanded_first_hypernyms
       parent = hypernym
       list = []
       return list unless parent
@@ -80,19 +217,61 @@ module WordNet
       while parent
         break if list.include? parent.pos_offset
         list.push parent.pos_offset
-        parent = parent.parent
+        parent = parent.hypernym
+      end
+
+      list.flatten!
+      list.map! { |offset| Synset.new(@pos, offset)}
+    end
+
+    # Get the entire hypernym tree (from this synset all the way up to +entity+) as an array.
+    def expanded_hypernyms
+      parents = hypernyms
+      list = []
+      return list unless parents
+
+      while parents.length > 0
+        parent = parents.pop
+        next if list.include? parent.pos_offset
+        list.push parent.pos_offset
+        parents.push *parent.hypernyms
       end
 
       list.flatten!
       list.map! { |offset| Synset.new(@pos, offset)}
     end
 
+    def expanded_hypernyms_depth
+      parents = hypernyms.map{|hypernym| [hypernym, 1]}
+      list = []
+      out = []
+      return list unless parents
+
+      max_depth = 1
+      while parents.length > 0
+        parent, depth = parents.pop
+        next if list.include? parent.pos_offset
+        list.push parent.pos_offset
+        out.push [Synset.new(@pos, parent.pos_offset), depth]
+        parents.push *(parent.hypernyms.map{|hypernym| [hypernym, depth + 1]})
+        max_depth = [max_depth, depth].max
+      end
+      return [out, max_depth]
+    end
+
+    # Returns a compact, human-readable form of this synset, e.g.
+    #
+    #    (v) fall (descend in free fall under the influence of gravity; "The branch fell from the tree"; "The unfortunate hiker fell into a crevasse")
+    #
+    # for the second meaning of the verb "fall."
     def to_s
       "(#{@synset_type}) #{words.map { |x| x.tr('_',' ') }.join(', ')} (#{@gloss})"
     end
 
+    alias to_str to_s
     alias size word_count
     alias parent hypernym
-    alias children hyponym
+    alias parents hypernyms
+    alias children hyponyms
   end
 end

data/lib/wordnet/version.rb

@@ -1,3 +1,3 @@
 module WordNet
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end