natto 0.9.6 → 0.9.7

data/lib/natto/natto.rb

@@ -11,18 +11,18 @@ module Natto
   #
   # ## Usage
   #
-  #     require 'rubygems' if RUBY_VERSION.to_f < 1.9
   #     require 'natto'
   #
   #     nm = Natto::MeCab.new('-Ochasen')
   #     => #<Natto::MeCab:0x28d3bdc8 \
   #          @tagger=#<FFI::Pointer address=0x28afb980>, \
+  #          @libpath="/usr/local/lib/libmecab.so"       \
   #          @options={:output_format_type=>"chasen"},   \
   #          @dicts=[#<Natto::DictionaryInfo:0x289a1f14  \
-  #                    type="0", \
-  #                    filename="/usr/local/lib/mecab/dic/ipadic/sys.dic", \
-  #                    charset="utf8">], \
-  #          @version="0.996">
+  #                    @filepath="/usr/local/lib/mecab/dic/ipadic/sys.dic", \
+  #                    charset=utf8 \
+  #                    type=0>], \
+  #          @version=0.996>
   #
   #     nm.parse('凡人にしか見えねえ風景ってのがあるんだよ。') do |n| 
   #       puts "#{n.surface}\t#{n.feature}" 
@@ -46,8 +46,17 @@ module Natto
   class MeCab
     include Natto::Binding
     include Natto::OptionParse
-
-    attr_reader :tagger, :options, :dicts, :version
+ 
+    # @return [FFI:Pointer] pointer to MeCab tagger.
+    attr_reader :tagger
+    # @return [String] absolute filepath to MeCab library.
+    attr_reader :libpath
+    # @return [Hash] MeCab options as key-value pairs.
+    attr_reader :options
+    # @return [Array] listing of all of dictionaries referenced.
+    attr_reader :dicts
+    # @return [String] `MeCab` versions.
+    attr_reader :version
 
     # Initializes the wrapped `mecab` instance with the
     # given `options`.
@@ -83,12 +92,13 @@ module Natto
     #     nm = Natto::MeCab.new(:node_format=>'%m¥t%f[7]¥n')
     #     => #<Natto::MeCab:0x28d2ae10 
     #          @tagger=#<FFI::Pointer address=0x28a97980>, \
+    #          @libpath="/usr/local/lib/libmecab.so",     \
     #          @options={:node_format=>"%m¥t%f[7]¥n"},     \
     #          @dicts=[#<Natto::DictionaryInfo:0x28d2a85c  \
-    #                    type="0", \
-    #                    filename="/usr/local/lib/mecab/dic/ipadic/sys.dic" \
-    #                    charset="utf8">], \
-    #          @version="0.996">
+    #                    @filepath="/usr/local/lib/mecab/dic/ipadic/sys.dic" \
+    #                    charset=utf8, \
+    #                    type=0>] \
+    #          @version=0.996>
     # 
     #     puts nm.parse('才能とは求める人間に与えられるものではない。')
     #     才能    サイノウ
@@ -106,14 +116,15 @@ module Natto
     #     。      。
     #     EOS
     #
-    # @param [Hash or String]
+    # @param [Hash, String] options MeCab options for tagger
     # @raise [MeCabError] if `mecab` cannot be initialized with the given `options`
     def initialize(options={})
       @options = self.class.parse_mecab_options(options) 
       @dicts = []
 
-      opt_str = self.class.build_options_str(@options)
-      @tagger = self.mecab_new2(opt_str)
+      opt_str  = self.class.build_options_str(@options)
+      @tagger  = self.class.mecab_new2(opt_str)
+      @libpath = self.class.find_library
       raise MeCabError.new("Could not initialize MeCab with options: '#{opt_str}'") if @tagger.address == 0x0
 
       self.mecab_set_theta(@tagger, @options[:theta]) if @options[:theta]
@@ -123,69 +134,79 @@ module Natto
        
       # Set mecab parsing implementations for N-best and regular parsing,
       # for both parsing as string and yielding a node object
-      # N-Best parsing implementations
       if @options[:nbest] && @options[:nbest] > 1
+        # N-Best parsing implementations
         self.mecab_set_lattice_level(@tagger, (@options[:lattice_level] || 1))
-        @parse_tostr = lambda do |str| 
-          return self.mecab_nbest_sparse_tostr(@tagger, @options[:nbest], str) || 
+
+        @parse_tostr = lambda do |text| 
+          retval = self.mecab_nbest_sparse_tostr(@tagger, @options[:nbest], text) || 
                 raise(MeCabError.new(self.mecab_strerror(@tagger))) 
+          retval.force_encoding(Encoding.default_external)
         end 
-        @parse_tonodes = lambda do |str| 
-          nodes = []
-          if @options[:nbest] && @options[:nbest] > 1
-            self.mecab_nbest_init(@tagger, str) 
+
+        @parse_tonodes = lambda do |text| 
+          Enumerator.new do |y|
+            self.mecab_nbest_init(@tagger, text) 
             n = self.mecab_nbest_next_tonode(@tagger)
             raise(MeCabError.new(self.mecab_strerror(@tagger))) if n.nil? || n.address==0x0
+
             nlen = @options[:nbest]
             nlen.times do |i|
-              s = str.bytes.to_a
+              s = text.bytes.to_a
               while n && n.address != 0x0
                 mn = Natto::MeCabNode.new(n)
-                s = s.drop_while {|e| (e==0xa || e==0x20)}
-                if !s.empty?
-                  sarr = []
-                  mn.length.times { sarr << s.shift }
-                  surf = sarr.pack('C*')
-                  #mn.surface = self.class.force_enc(surf)
-                  mn.surface = surf.force_encoding(Encoding.default_external)
-                end
-                if @options[:output_format_type] || @options[:node_format]
-                  mn.feature = self.mecab_format_node(@tagger, n).force_encoding(Encoding.default_external)
+                # ignore BOS nodes, since mecab does so
+                if !mn.is_bos?
+                  s = s.drop_while {|e| (e==0xa || e==0x20)}
+                  if !s.empty?
+                    sarr = []
+                    mn.length.times { sarr << s.shift }
+                    surf = sarr.pack('C*')
+                    mn.surface = surf.force_encoding(Encoding.default_external)
+                  end
+                  if @options[:output_format_type] || @options[:node_format]
+                    mn.feature = self.mecab_format_node(@tagger, n).force_encoding(Encoding.default_external)
+                  end
+                  y.yield mn
                 end
-                nodes << mn if !mn.is_bos?
                 n = mn.next
               end
               n = self.mecab_nbest_next_tonode(@tagger)
             end
           end
-          return nodes
         end
       else
         # default parsing implementations
-        @parse_tostr = lambda do |str|
-          return self.mecab_sparse_tostr(@tagger, str) || 
+        @parse_tostr = lambda do |text|
+          retval = self.mecab_sparse_tostr(@tagger, text) || 
                 raise(MeCabError.new(self.mecab_strerror(@tagger))) 
+          retval.force_encoding(Encoding.default_external)
         end
-        @parse_tonodes = lambda do |str| 
-          nodes = []
-          n = self.mecab_sparse_tonode(@tagger, str) 
-          raise(MeCabError.new(self.mecab_strerror(@tagger))) if n.nil? || n.address==0x0
-          mn = Natto::MeCabNode.new(n)
-          n = mn.next if mn.next.address!=0x0
-          s = str.bytes.to_a
-          while n && n.address!=0x0
+
+        @parse_tonodes = lambda do |text| 
+          Enumerator.new do |y|
+            n = self.mecab_sparse_tonode(@tagger, text) 
+            raise(MeCabError.new(self.mecab_strerror(@tagger))) if n.nil? || n.address==0x0
+          
             mn = Natto::MeCabNode.new(n)
-            s = s.drop_while {|e| (e==0xa || e==0x20)}
-            if !s.empty?
-              sarr = []
-              mn.length.times { sarr << s.shift }
-              surf = sarr.pack('C*')
-              mn.surface = surf.force_encoding(Encoding.default_external)
+            n = mn.next if mn.next.address!=0x0
+            s = text.bytes.to_a
+            while n && n.address!=0x0
+              mn = Natto::MeCabNode.new(n)
+              s = s.drop_while {|e| (e==0xa || e==0x20)}
+              if !s.empty?
+                sarr = []
+                mn.length.times { sarr << s.shift }
+                surf = sarr.pack('C*')
+                mn.surface = surf.force_encoding(Encoding.default_external)
+              end
+              if @options[:output_format_type] || @options[:node_format]
+                mn.feature = self.mecab_format_node(@tagger, n).force_encoding(Encoding.default_external)
+              end
+              y.yield mn
+              n = mn.next
             end
-            nodes << mn 
-            n = mn.next
           end
-          return nodes
         end
       end
 
@@ -199,24 +220,48 @@ module Natto
       ObjectSpace.define_finalizer(self, self.class.create_free_proc(@tagger))
     end
     
-    # Parses the given string `str`. If a block is passed to this method,
-    # then node parsing will be used and each node yielded to the given block.
+    # Parses the given `text`, returning the MeCab output as a single string. 
+    # If a block is passed to this method, then node parsing will be used
+    # and each node yielded to the given block.
     #
-    # @param [String] str
-    # @return parsing result from `mecab`
-    # @raise [MeCabError] if the `mecab` tagger cannot parse the given string `str`
-    # @raise [ArgumentError] if the given string `str` argument is `nil`
+    # @param [String] text
+    # @return [String] parsing result from `mecab`
+    # @raise [MeCabError] if the `mecab` tagger cannot parse the given `text`
+    # @raise [ArgumentError] if the given string `text` argument is `nil`
     # @see MeCabNode
-    def parse(str)
-      raise ArgumentError.new 'String to parse cannot be nil' if str.nil?
+    def parse(text)
+      raise ArgumentError.new 'Text to parse cannot be nil' if text.nil?
       if block_given?
-        nodes = @parse_tonodes.call(str)
-        nodes.each {|n| yield n }
+        @parse_tonodes.call(text).each {|n| yield n }
       else
-        @parse_tostr.call(str).force_encoding(Encoding.default_external)
+        @parse_tostr.call(text)
       end
     end
 
+    # Parses the given string `text`, returning an
+    # {http://www.ruby-doc.org/core-2.1.5/Enumerator.html Enumerator} that may be
+    # used to iterate over the resulting {MeCabNode} objects. This is more 
+    # efficient than parsing to a simple string, since each node's
+    # information will not be materialized all at once as with it is with
+    # string output.
+    #
+    # MeCab nodes contain much more detailed information about
+    # the morpheme. Node-formatting  may also be used to customize
+    # the resulting node's `feature` attribute.
+    #
+    # @param [String] text
+    # @return [Enumerator] of MeCabNode instances
+    # @raise [MeCabError] if the `mecab` tagger cannot parse the given `text`
+    # @raise [ArgumentError] if the given string `text` argument is `nil`
+    # @see MeCabNode
+    # @see http://www.ruby-doc.org/core-2.1.5/Enumerator.html
+    def enum_parse(text)
+      raise ArgumentError.new 'Text to parse cannot be nil' if text.nil?
+      @parse_tonodes.call(text)
+    end
+
+    # @deprecated
+    # DEPRECATED: use enum_parse instead, this convenience method is useless.
     # Parses the given string `str`, and returns
     # a list of `mecab` nodes.
     # @param [String] str
@@ -225,10 +270,14 @@ module Natto
     # @raise [ArgumentError] if the given string `str` argument is `nil`
     # @see MeCabNode
     def parse_as_nodes(str)
+      $stderr.puts 'DEPRECATED: use enum_parse instead'
+      $stderr.puts '            This method will be removed in the next release!'
       raise ArgumentError.new 'String to parse cannot be nil' if str.nil?
       @parse_tonodes.call(str)
     end
 
+    # @deprecated
+    # DEPRECATED: use enum_parse instead, this convenience method is useless.
     # Parses the given string `str`, and returns
     # a list of `mecab` result strings.
     # @param [String] str
@@ -236,19 +285,29 @@ module Natto
     # @raise [MeCabError] if the `mecab` tagger cannot parse the given string `str`
     # @raise [ArgumentError] if the given string `str` argument is `nil`
     def parse_as_strings(str)
+      $stderr.puts 'DEPRECATED: use enum_parse instead'
+      $stderr.puts '            This method will be removed in the next release!'
       raise ArgumentError.new 'String to parse cannot be nil' if str.nil?
-      @parse_tostr.call(str).force_encoding(Encoding.default_external).lines.to_a
+      @parse_tostr.call(str).lines.to_a
     end
 
-    # DEPRECATED: use parse_as_nodes instead.
+    # @deprecated
+    # DEPRECATED: use enum_parse instead, this convenience method is useless.
+    # @param [String] str
+    # @return [Array] of parsed `mecab` nodes.
     def readnodes(str)
-      $stdout.puts 'DEPRECATED: use parse_as_nodes instead'
+      $stderr.puts 'DEPRECATED: use enum_parse instead'
+      $stderr.puts '            This method will be removed in the next release!'
       parse_as_nodes(str)
     end
 
-    # DEPRECATED: use parse_as_strings instead.
+    # @deprecated
+    # DEPRECATED: use enum_parse instead, this convenience method is useless.
+    # @param [String] str
+    # @return [Array] of parsed `mecab` result strings.
     def readlines(str)
-      $stdout.puts 'DEPRECATED: use parse_as_strings instead'
+      $stderr.puts 'DEPRECATED: use enum_parse instead'
+      $stderr.puts '            This method will be removed in the next release!'
       parse_as_strings(str)
     end
 
@@ -257,18 +316,27 @@ module Natto
     #
     # - encoded object id
     # - underlying FFI pointer to the `mecab` tagger
+    # - real file path to `mecab` library
     # - options hash
     # - list of dictionaries
     # - MeCab version
     #
-    # @return [String] encoded object id, underlying FFI pointer, options hash, list of dictionaries, and MeCab version
+    # @return [String] encoded object id, underlying FFI pointer,
+    #   file path to `mecab` library, options hash,
+    #   list of dictionaries and MeCab version
     def to_s
-      %(#{super.chop} @tagger=#{@tagger}, @options=#{@options.inspect}, @dicts=#{@dicts.to_s}, @version="#{@version.to_s}">)
+      [ super.chop,
+        "@tagger=#{@tagger},", 
+        "@libpath=\"#{@libpath}\",",
+        "@options=#{@options.inspect},", 
+        "@dicts=#{@dicts.to_s},", 
+        "@version=#{@version.to_s}>" ].join(' ')
     end
 
     # Overrides `Object#inspect`.
     # 
-    # @return [String] encoded object id, FFI pointer, options hash, list of dictionaries, and MeCab version
+    # @return [String] encoded object id, FFI pointer, options hash,
+    #   list of dictionaries, and MeCab version
     # @see #to_s
     def inspect
       self.to_s
@@ -293,3 +361,29 @@ module Natto
   # for the `Natto` module.
   class MeCabError < RuntimeError; end
 end
+
+# Copyright (c) 2014-2015, Brooke M. Fujita.
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#  * Redistributions of source code must retain the above
+#    copyright notice, this list of conditions and the
+#    following disclaimer.
+# 
+#  * 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.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 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.

data/lib/natto/option_parse.rb

@@ -115,3 +115,29 @@ module Natto
     end
   end
 end
+
+# Copyright (c) 2014-2015, Brooke M. Fujita.
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#  * Redistributions of source code must retain the above
+#    copyright notice, this list of conditions and the
+#    following disclaimer.
+# 
+#  * 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.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 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.

data/lib/natto/struct.rb

@@ -21,21 +21,21 @@ module Natto
     end
   end
 
-  # `DictionaryInfo` is a wrapper for `struct mecab_dictionary_info_t`
-  # that holds the `MeCab` instance's related dictionary information.
+  # `DictionaryInfo` is a wrapper for the `struct mecab_dictionary_info_t`
+  # structure holding the `MeCab` instance's related dictionary information.
   # 
   # Values for the `mecab` dictionary attributes may be 
   # obtained by using the following `Symbol`s as keys 
   # to the layout associative array of `FFI::Struct` members.
   #
-  # - :filename
-  # - :charset
-  # - :size
-  # - :type
-  # - :lsize
-  # - :rsize
-  # - :version
-  # - :next
+  # - :filename - filename of dictionary; on Windows, filename is stored in UTF-8 encoding
+  # - :charset - character set of the dictionary
+  # - :size - number of words contained in dictionary
+  # - :type - dictionary type: 0 (system), 1 (user-defined), 2 (unknown)
+  # - :lsize - left attributes size
+  # - :rsize - right attributes size
+  # - :version - version of this dictionary
+  # - :next - pointer to next dictionary in list
   # 
   # ## Usage
   # `mecab` dictionary attributes can be obtained by
@@ -44,16 +44,20 @@ module Natto
   #     nm = Natto::MeCab.new
   #
   #     sysdic = nm.dicts.first
-  #
-  #     puts sysdic.filename
-  #     => "/usr/local/lib/mecab/dic/ipadic/sys.dic"
+  #    
+  #     # display the real path to the mecab lib
+  #     puts sysdic.filepath
+  #     => /usr/local/lib/mecab/dic/ipadic/sys.dic
   #
   #     puts sysdic.charset
-  #     => "utf8"
+  #     => utf8
   # 
   #     puts sysdic.is_sysdic?
   #     => true
   class DictionaryInfo < MeCabStruct
+    # @return [String] Absolute filepath to MeCab dictionary.
+    attr_reader :filepath
+
     # System dictionary.
     SYS_DIC = 0
     # User dictionary.
@@ -83,17 +87,31 @@ module Natto
       end
     end
 
+    # Initializes this dictionary info instance.
+    # Sets the `DictionaryInfo` filepath value.
+    #
+    # @param [FFI::Pointer] ptr pointer to MeCab dictionary
+    def initialize(ptr)
+      super(ptr)
+
+      @filepath = File.absolute_path(self[:filename])
+    end
+
     # Returns human-readable details for this `mecab` dictionary.
     # Overrides `Object#to_s`.
     #
     # - encoded object id
-    # - dictionary type
-    # - full-path dictionary filename
+    # - real file path to this dictionary
     # - dictionary charset
+    # - dictionary type
     #
-    # @return [String] encoded object id, type, dictionary filename, and charset
+    # @return [String] encoded object id, file path to dictionary, charset and
+    # type
     def to_s
-      %(#{super.chop} type="#{self.type}", filename="#{self.filename}", charset="#{self.charset}">)
+      [ super.chop,
+        "@filepath=\"#{@filepath}\",", 
+         "charset=#{self.charset},", 
+         "type=#{self.type}>" ].join(' ')
     end
     
     # Overrides `Object#inspect`.
@@ -123,35 +141,35 @@ module Natto
     end
   end
 
-  # `MeCabNode` is a wrapper for the structure holding
-  # the parsed `node`.
+  # `MeCabNode` is a wrapper for the `struct mecab_node_t`
+  # structure holding the parsed `node`.
   # 
   # Values for the `mecab` node attributes may be 
   # obtained by using the following `Symbol`s as keys 
   # to the layout associative array of `FFI::Struct` members.
   #
-  # - :prev
-  # - :next
-  # - :enext
-  # - :bnext
-  # - :rpath
-  # - :lpath
-  # - :surface
-  # - :feature
-  # - :id
-  # - :length
-  # - :rlength
-  # - :rcAttr
-  # - :lcAttr
-  # - :posid
-  # - :char_type
-  # - :stat
-  # - :isbest
-  # - :alpha
-  # - :beta
-  # - :prob
-  # - :wcost
-  # - :cost
+  # - :prev - pointer to previous node
+  # - :next - pointer to next node
+  # - :enext - pointer to the node which ends at the same position
+  # - :bnext - pointer to the node which starts at the same position
+  # - :rpath - pointer to the right path; nil if MECAB_ONE_BEST mode
+  # - :lpath - pointer to the right path; nil if MECAB_ONE_BEST mode
+  # - :surface - surface string; length may be obtained with length/rlength members
+  # - :feature - feature string
+  # - :id - unique node id
+  # - :length - length of surface form
+  # - :rlength - length of the surface form including white space before the morph
+  # - :rcAttr - right attribute id
+  # - :lcAttr - left attribute id
+  # - :posid - part-of-speech id
+  # - :char_type - character type
+  # - :stat - node status; 0 (NOR), 1 (UNK), 2 (BOS), 3 (EOS), 4 (EON)
+  # - :isbest - 1 if this node is best node
+  # - :alpha - forward accumulative log summation, only with marginal probability flag
+  # - :beta - backward accumulative log summation, only with marginal probability flag
+  # - :prob - marginal probability, only with marginal probability flag
+  # - :wcost - word cost
+  # - :cost - best accumulative cost from bos node to this node
   #
   # ## Usage
   # An instance of `MeCabNode` is yielded to the block
@@ -164,7 +182,7 @@ module Natto
   #       puts "#{n.surface}\t#{n.cost}" if n.is_nor? 
   #     end
   #     卓球     2874
-  #     な       4398
+  #     なんて    4398
   #     死ぬ     9261
   #     まで     9386
   #     の       10007
@@ -173,36 +191,29 @@ module Natto
   #     よ       14396
   #     。       10194
   #
-  # It is also possible to use the `Symbol` for the
+  # While it is also possible to use the `Symbol` for the
   # `mecab` node member to index into the 
-  # `FFI::Struct` layout associative array like so:
-  #     
-  #     nm.parse('あいつ笑うと結構可愛い顔してんよ。') {|n| puts n[:feature] }
-  #     名詞,代名詞,一般,*,*,*,あいつ,アイツ,アイツ
-  #     動詞,自立,*,*,五段・ワ行促音便,基本形,笑う,ワラウ,ワラウ
-  #     助詞,接続助詞,*,*,*,*,と,ト,ト
-  #     副詞,一般,*,*,*,*,結構,ケッコウ,ケッコー
-  #     形容詞,自立,*,*,形容詞・イ段,基本形,可愛い,カワイイ,カワイイ
-  #     名詞,一般,*,*,*,*,顔,カオ,カオ
-  #     動詞,自立,*,*,サ変・スル,連用形,する,シ,シ
-  #     動詞,非自立,*,*,一段,体言接続特殊,てる,テン,テン
-  #     助詞,終助詞,*,*,*,*,よ,ヨ,ヨ
-  #     記号,句点,*,*,*,*,。,。,。
-  #     BOS/EOS,*,*,*,*,*,*,*,*
-  #
+  # `FFI::Struct` layout associative array, please use the attribute
+  # accessors. In the case of `:surface` and `:feature`, `mecab` 
+  # returns the raw bytes, so `natto` will convert that into
+  # a string using the default encoding.
   class MeCabNode < MeCabStruct
-    attr_accessor :surface, :feature
+    # @return [String] surface morpheme surface value.
+    attr_accessor :surface
+    # @return [String] corresponding feature value.
+    attr_accessor :feature
+    # @return [FFI::Pointer] pointer to MeCab node struct.
     attr_reader   :pointer
 
-    # Normal `mecab` node defined in the dictionary.
+    # Normal `mecab` node defined in the dictionary, c.f. `stat`.
     NOR_NODE = 0
-    # Unknown `mecab` node not defined in the dictionary.
+    # Unknown `mecab` node not defined in the dictionary, c.f. `stat`.
     UNK_NODE = 1
-    # Virtual node representing the beginning of the sentence.
+    # Virtual node representing the beginning of the sentence, c.f. `stat`.
     BOS_NODE = 2
-    # Virutual node representing the end of the sentence.
+    # Virutual node representing the end of the sentence, c.f. `stat`.
     EOS_NODE = 3
-    # Virtual node representing the end of an N-Best `mecab` node list.
+    # Virtual node representing the end of an N-Best `mecab` node list, c.f. `stat`.
     EON_NODE = 4
 
     layout  :prev,            :pointer,
@@ -227,25 +238,11 @@ module Natto
             :prob,            :float,
             :wcost,           :short,
             :cost,            :long
-   
-    #if RUBY_VERSION.to_f < 1.9
-    #  alias_method :deprecated_id, :id
-    #  # `Object#id` override defined when `RUBY_VERSION` is
-    #  # older than 1.9. This is a hack to avoid the `Object#id`
-    #  # deprecation warning thrown up in Ruby 1.8.7.
-    #  #
-    #  # <i>This method override is not defined when the Ruby interpreter
-    #  # is 1.9 or greater.</i>
-    #  # @return [Fixnum] `mecab` node id
-    #  def id
-    #    self[:id]
-    #  end
-    #end
 
     # Initializes this node instance.
     # Sets the `MeCab` feature value for this node.
     #
-    # @param [FFI::Pointer]
+    # @param [FFI::Pointer] ptr pointer to MeCab node
     def initialize(ptr)
       super(ptr)
       @pointer = ptr
@@ -308,3 +305,29 @@ module Natto
     end
   end
 end
+
+# Copyright (c) 2014-2015, Brooke M. Fujita.
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#  * Redistributions of source code must retain the above
+#    copyright notice, this list of conditions and the
+#    following disclaimer.
+# 
+#  * 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.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 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.