.. $Id: README.rst 229 2012-11-10 12:43:12Z atzm $

:mod:`migemo` --- C/Migemo の Python バインディング
===================================================

.. module:: migemo
   :synopsis: C/Migemo の Python バインディング
.. moduleauthor:: Atzm WATANABE <atzm@atzm.org>

`C/Migemo <http://www.kaoriya.net/software/cmigemo>`_ を
Python から利用するための拡張モジュールです．

このモジュールの利用にあたっては，
C/Migemo がインストールされていることが前提となっています．
ライブラリ検索パスに migemo.so が，
ヘッダ検索パスに migemo.h が存在することをご確認下さい．

インストール
------------
同梱の setup.py をご利用下さい::

   $ ./setup.py build
   # ./setup.py install

setup.py の実行には `setuptools <http://pypi.python.org/pypi/setuptools>`_
が必要です．
エラーが発生する場合は setuptools をインストールしてから再度実施して下さい．

基本的な使い方
--------------
基本的な使い方は以下のようになります::

   >>> import migemo
   >>> m = migemo.Migemo('/usr/share/migemo/migemo-dict')
   >>> print(m.query('hoge'))
   (hoge|ｈｏｇｅ|ほげ|捕鯨|帆桁|補元|ホゲ)

migemo-dict 辞書ファイルと共に :class:`Migemo` クラスのオブジェクトを生成し，
:meth:`Migemo.query` メソッドに文字列を渡すと，正規表現が返ります．
この正規表現を :mod:`re` と組み合わせれば検索等の用途に利用することができます．

.. note::
   返却される正規表現は読み込んだ辞書によって異なるので，
   必ずしも上記の通りになるとは限りません．

リファレンス
------------

:class:`Migemo` クラス
``````````````````````

.. class:: Migemo(dictionary)

   migemo をハンドルするクラスです．
   *dictionary* は利用する migemo-dict 辞書ファイルのパスです．

   .. method:: query(query)

      *query* から正規表現を返します．
      *query* は unicode でもエンコードされた文字列でも構いません．
      ただし *query* がエンコードされた文字列の場合，
      そのエンコーディングが辞書のエンコーディングと異なると，
      エラーとなる可能性があります．

   .. method:: is_enable()

      辞書を正常に読み込めているかどうかチェックします．
      正常に読み込めている場合は ``True`` が，
      そうでない場合は ``False`` が返ります．

   .. method:: load(dict_id, dict_file)

      辞書を読み込みます．
      *dict_id* は後述の DICTID のいずれかで，読み込む辞書の種類を指定します．
      *dict_file* は辞書ファイルのパスです．
      このメソッドは成功すると読み込んだ辞書の DICTID を返します．
      読み込みに失敗した場合は :data:`DICTID_INVALID` を返します．

   .. method:: get_operator(index)

      *index* で指定された，正規表現に使用するメタ文字を返します．
      *index* は後述の OPINDEX のいずれかを指定する必要があります．

   .. method:: set_operator(index, op)

      *index* で指定された正規表現に使用するメタ文字を *op* に変更します．
      *index* は後述の OPINDEX のいずれかを指定する必要があります．
      変更に成功すれば ``True`` が，失敗すれば ``False`` が返ります．

   .. method:: get_encoding()

      読み込んだ辞書のエンコーディングを返します．
      例えば EUC-JP で書かれた辞書であれば ``'euc_jp'`` が返ります．
      ``'cp932'`` か ``'euc_jp'`` か ``'utf8'`` か ``'ascii'``
      のいずれかが返ります．

DICTID
``````

:meth:`Migemo.load` で利用する辞書の種類です．

.. data:: DICTID_MIGEMO

   migemo-dict 辞書を示します．

.. data:: DICTID_ROMA2HIRA

   ローマ字→平仮名変換表を示します．

.. data:: DICTID_HIRA2KATA

   平仮名→カタカナ変換表を示します．

.. data:: DICTID_HAN2ZEN

   半角→全角変換表を示します．

.. data:: DICTID_ZEN2HAN

   全角→半角変換表を示します．

.. data:: DICTID_INVALID

   辞書の読み込みに失敗した場合に返る DICTID です．

OPINDEX
```````

:meth:`Migemo.get_operator` または :meth:`Migemo.set_operator`
で利用するメタ文字の種類です．

.. data:: OPINDEX_OR

   論理和を示します．
   デフォルトは ``'|'`` です．

.. data:: OPINDEX_NEST_IN

   グルーピング時の開き括弧を示します．
   デフォルトは ``'('`` です．

.. data:: OPINDEX_NEST_OUT

   グルーピング時の閉じ括弧を示します．．
   デフォルトは ``')'`` です．

.. data:: OPINDEX_SELECT_IN

   選択の開始を表す開き鈎括弧を示します．
   デフォルトは ``'['`` です．

.. data:: OPINDEX_SELECT_OUT

   選択の終了を表す閉じ鈎括弧を示します．
   デフォルトは ``']'`` です．

.. data:: OPINDEX_NEWLINE

   各文字の間に挿入される「0 個以上の空白もしくは改行にマッチする」
   パターンを示します．
   デフォルトは ``''`` です．

VERSION
```````

migemo のバージョンです．

.. data:: MIGEMO_VERSION

   C/Migemo のバージョンを示します．

.. data:: PYMIGEMO_VERSION

   PyMigemo のバージョンを示します．

ライセンス
----------
二条項 BSD ライセンスに準拠します．
詳細は同梱の LICENSE ファイルをご覧下さい．