natto 0.0.2 → 0.0.3

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010, Brooke M. Fujita
+Copyright (c) 2010-2013, Brooke M. Fujita.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are

data/README

@@ -0,0 +1,67 @@
+= natto: A Tasty Ruby Binding with MeCab
+
+== What is natto?
+
+natto provides a Ruby binding with MeCab, 
+the part-of-speech and morphological analyzer 
+for the Japanese language.
+
+== Try It! Try It!
+
+=== Requirements
+natto requires the following:
+* {http://sourceforge.net/projects/mecab/files/mecab/ MeCab 0.98}
+* {http://rubygems.org/gems/ffi ffi 0.63 or greater}
+* Ruby 1.8.7 or greater
+
+=== Installation
+Install natto with the following gem command:
+* <code>gem install natto</code>
+
+=== Configuration
+* natto will try to locate the <tt>mecab</tt> library based upon its runtime environment.
+* In case of <tt>LoadError</tt>, please set the <tt>MECAB_PATH</tt> environment variable to the exact name/path to your <tt>mecab</tt> library.
+
+== Usage
+  require 'natto'
+
+  m = Natto::MeCab.new
+  puts m.parse("すもももももももものうち")
+  すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
+  も      助詞,係助詞,*,*,*,*,も,モ,モ
+  もも    名詞,一般,*,*,*,*,もも,モモ,モモ
+  も      助詞,係助詞,*,*,*,*,も,モ,モ
+  もも    名詞,一般,*,*,*,*,もも,モモ,モモ
+  の      助詞,連体化,*,*,*,*,の,ノ,ノ
+  うち    名詞,非自立,副詞可能,*,*,*,うち,ウチ,ウチ
+  EOS
+  => nil
+
+== Contributing to natto
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you must have your own version, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Changelog
+
+- **2010/12/22**: 0.0.3 release.
+    - On-going refactoring
+    - Adding documentation via yard
+
+- **2010/12/20**: 0.0.2 release.
+    - Continuing development on proper resource deallocation
+    - Adding options hash in object initializer 
+
+- **2010/12/13**: Released version 0.0.1. The objective is to provide
+  an easy-to-use, production-level Ruby binding to MeCab.
+    - Initial release 
+
+
+== Copyright
+
+natto (c) 2010-2013 by Brooke M. Fujita, licensed under the new BSD license. Please see the {file:LICENSE} document for further details.

data/lib/natto.rb

@@ -1,38 +1,106 @@
 # -*- coding: UTF-8 -*-
 require 'rubygems' if RUBY_VERSION.to_f < 1.9
 
-module Natto
+# natto combines the Ruby programming language with MeCab, 
+# the part-of-speech and morphological analyzer for the
+# Japanese language.
+# 
+# === Requirements
+# natto requires the following:
+# * {http://sourceforge.net/projects/mecab/files/mecab/ MeCab 0.98}
+# * {http://rubygems.org/gems/ffi ffi 0.63 or greater}
+#
+# === Installation
+# Install natto with the following gem command:
+# * <code>gem install natto</code>
+#
+# === Configuration
+# * natto will try to locate the <tt>mecab</tt> library based upon its runtime environment.
+# * In case of <tt>LoadError</tt>, please set the <tt>MECAB_PATH</tt> environment variable to the exact name/path to your <tt>mecab</tt> library.
+#
+#== Usage
+#  require 'natto'
+#
+#  m = Natto::MeCab.new
+#  puts m.parse("すもももももももものうち")
+#  すもも  名詞,一般,*,*,*,*,すもも,スモモ,スモモ
+#  も      助詞,係助詞,*,*,*,*,も,モ,モ
+#  もも    名詞,一般,*,*,*,*,もも,モモ,モモ
+#  も      助詞,係助詞,*,*,*,*,も,モ,モ
+#  もも    名詞,一般,*,*,*,*,もも,モモ,モモ
+#  の      助詞,連体化,*,*,*,*,の,ノ,ノ
+#  うち    名詞,非自立,副詞可能,*,*,*,うち,ウチ,ウチ
+#  EOS
+#  => nil
+#
+# @author Brooke M. Fujita (buruzaemon)
+module Natto 
   require 'ffi'
 
+  # <tt>MeCab</tt> is a wrapper class to the <tt>mecab</tt> parser.
+  # Options to the <tt>mecab</tt> parser are passed in as a hash to
+  # #initialize.
+  # 
+  # @see {SUPPORTED_OPTS}
   class MeCab
+    # Supported options to the <tt>mecab</tt> parser.
+    # See the <tt>mecab</tt> help for more details. 
     SUPPORTED_OPTS = [ :rcfile, :dicdir, :userdic, :output_format_type, :lattice_level, 
                        :node_format, :unk_format, :bos_format, :eos_format, :eon_format,
-                       :unk_feature, :nbest, :theta, :cost_factor ]
+                       :unk_feature, :nbest, :theta, :cost_factor ].freeze
                        # :all_morphs, :partial, :allocate_sentence ]
-    attr_reader :ptr
 
+    # Initialize the wrapped <tt>mecab</tt> instance, with the
+    # given <tt>options</tt> hash.
+    # <br/>
+    # Options supported are:
+    # * :rcfile -- resource file
+    # * :dicdir -- system dicdir
+    # * :userdic -- user dictionary
+    # * :lattice_level -- lattice information level (integer, default 0)
+    # * :output_format_type -- output format type (wakati, chasen, yomi, dump)
+    # * :node_format -- user-defined node format
+    # * :unk_format -- user-defined unknown node format
+    # * :bos_format -- user-defined beginning-of-sentence format
+    # * :eos_format -- user-defined end-of-sentence format
+    # * :eon_format -- user-defined end-of-NBest format
+    # * :unk_feature -- feature for unknown word
+    # * :nbest --  output N best results (integer, default 1)
+    # * :theta -- temperature parameter theta (float, default 0.75)
+    # * :cost_factor -- cost factor (integer, default 700)
+    #
+    # @param [Hash]
+    # @see {SUPPORTED_OPTS}
     def initialize(options={})
       opt_str = self.class.build_options_str(options)
-      #@ptr = FFI::MemoryPointer.new :pointer
       @ptr = Natto::Binding.mecab_new2(opt_str)
-      puts @ptr.inspect
-      raise MeCabError.new("MeCab initialiation error with '#{opt_str}'") if @ptr.address == 0
+      raise MeCabError.new("MeCab initialization error with '#{opt_str}'") if @ptr.address == 0
       #@dict = Natto::DictionaryInfo.new(Natto::Binding.mecab_dictionary_info(@ptr))
       ObjectSpace.define_finalizer(self, self.class.create_free_proc(@ptr))
     end
 
+    # Parses the given string <tt>s</tt>.
+    #
+    # @param [String]
     def parse(s)
       Natto::Binding.mecab_sparse_tostr(@ptr, s) || 
         raise(MeCabError.new(Natto::Binding.mecab_strerror(@ptr)))
     end
-    
+
+    # Returns a <tt>Proc</tt> that is registered to be invoked
+    # after the object owning <tt>ptr</tt> has been destroyed.
+    #
+    # @param [FFI::MemoryPointer] ptr
     def self.create_free_proc(ptr)
       Proc.new do
-        #puts "mecab_destroy #{ptr}"
         Natto::Binding.mecab_destroy(ptr)
       end
     end
 
+    # Returns a string-representation of the options to
+    # be passed in the construction of <tt>mecab</tt>.
+    #
+    # @param [Hash] options 
     def self.build_options_str(options={})
       opt = []
       SUPPORTED_OPTS.each do |k|
@@ -44,9 +112,31 @@ module Natto
       opt.join(" ")
     end
   end
- 
+
+  # <tt>MeCabError</tt> is a general error class 
+  # for the <tt>Natto</tt> module.
   class MeCabError < RuntimeError; end
 
+  # <tt>DictionaryInfo</tt> is a wrapper for a <tt>MeCab</tt>
+  # instance's related dictionary information.
+  # <br>
+  # Values may be obtained by using the following symbols 
+  # as keys to the hash of <tt>mecab</tt> dictionary information.
+  # * :filename
+  # * :charset
+  # * :size
+  # * :type
+  # * :lsize
+  # * :rsize
+  # * :version
+  # * :next
+  # <br>
+  #
+  #  dict = Natto::DictionaryInfo.new(mecab_ptr)
+  #  puts dict[:filename]
+  #  =>  /usr/local/lib/mecab/dic/ipadic/sys.dic
+  #  puts dict[:charset]
+  #  =>  utf8
   class DictionaryInfo < FFI::Struct
     layout  :filename, :string,
             :charset,  :string,
@@ -58,16 +148,29 @@ module Natto
             :next,     :pointer 
   end
 
+  # Module <tt>Binding</tt> encapsulates operations which are
+  # made available via <tt>FFI</tt> bindings to <tt>mecab</tt>
   module Binding
     require 'rbconfig'
     extend FFI::Library
 
+    # String name for the environment variable used by 
+    # <tt>Natto</tt> to indicate the exact name / full path
+    # to the <tt>mecab</tt> library.
     MECAB_PATH = 'MECAB_PATH'
-
+    
+    # @private
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    # Returns the name of the <tt>mecab</tt> library based on 
+    # the runtime environment. The value of the environment
+    # parameter <tt>MECAB_PATH</tt> is checked before this
+    # function is invoked, and in the case of Windows, a
+    # <tt>LoadError</tt> will be raised if <tt>MECAB_PATH</tt>
+    # is <b>not</b> set to the full path of the <tt>mecab</tt>
+    # library.
     def self.find_library
       host_os = RbConfig::CONFIG['host_os']
 
@@ -89,6 +192,7 @@ module Natto
     attach_function :mecab_strerror, [:pointer],:string
     attach_function :mecab_dictionary_info, [:pointer], :pointer
 
+    # @private
     module ClassMethods
       def mecab_version
         Natto::Binding.mecab_version

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Brooke M. Fujita
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-20 00:00:00 +09:00
+date: 2010-12-22 00:00:00 +09:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,6 +44,7 @@ files:
 - lib/natto.rb
 - test/test_natto.rb
 - LICENSE
+- README
 has_rdoc: true
 homepage: http://code.google.com/p/natto/
 licenses: