___ Region Oriented Ascii Processor [USAGE] ___

使い方
======

シェル上で以下のように打鍵すると、処理されたデータが標準出力に出力される。

    $ roap.py スクリプトファイル 入力ファイル

スクリプトファイルについて
==========================

スクリプトファイルは、XMLで記述され、
記述された正規表現のマッチング処理をしながら、外部プロセッサを呼び出していく。
例えば、ある定型フォーマット(例えば、見出しにはテキストの次の行を`='で埋める
という決まりがあるとする)をHTMLへ変換したい場合は、見出しとして認識されるように
フォーマット認識ファイルに書いてやり、認識されたテキストを外部のツール
(python、perl、sed、awk、などで書かれてるようなスクリプトなど)を起動して
標準入力へ渡し、返って来る標準出力を受ける。これを繰り返すことで、
フォーマットが変換されていく。

領域の定義
----------

ルート要素をroapとして、次のように認識する領域を設定する。

    <region processor="executable">
      <match range="*">regex text</match>
      <match range="1">regex text</match>
      ...
    </region>

どの外部プロセッサにかければ良いかを判断するために、マッチング処理を行う。
region要素にはそれぞれ外部プロセッサを指定しておく。
match要素には正規表現を含んだ文字列と、適用される行数(range属性)を指定する。
また、「*」なら、0行以上、「+」なら1行以上のマッチング指定となる。

極端な例
--------

以下の例では、全ての領域をcatにフィルタする。

    <roap>
     <region processor="cat">
      <match range="+">.*</match>
     </region>
    </roap>

このファイル自身(USAGE.ja)を入力ファイルとし、
前述のスクリプトを書いたテキストファイルをcat.xmlとすると、
以下のようなコマンドを打鍵することになる。

    $ roap.py cat.xml USAGE.ja

実行するとわかるとおもうが、空行が詰められて出力されているのがわかるはずだ。
つまり、空行を区切りとして認識しているので、空行そのものは出力されない。

基本的な例
----------

さっきの例では実用的な使い方とは言い難いので、もうすこし使えそうな例を示す。

    <roap>
     <region processor="python title.py">
      <match range="+">\s+___ .* ___</match>
     </region>
     <region processor="python header.py -2">
      <match range="+">.*</match>
      <match range="1" content="no">=+</match>
     </region>
     <region processor="python header.py -3">
      <match range="+">.*</match>
      <match range="1" content="no">-+</match>
     </region>
     <region processor="python preformat.py">
      <match range="+">    .*</match>
     </region>
     <region processor="python list.py">
      <match range="+">o .*</match>
     </region>
     <region processor="python paragraph.py">
      <match range="+">.*</match>
     </region>
    </roap>

このスクリプトでは、5つの領域を定義している。これらの正規表現は、
この文書を処理することができるようになっている。
そしてこれらを実際に処理するものはPythonのスクリプトである。
実際の内容はexamplesディレクトリにあるサンプルコードを眺めて欲しい。

大事なこと
----------

region要素の並べ方に注目してもらうと分かるかもしれないが、
ある一定の決まりがある。それは、下の方に行くほど、
マッチングのパターン定義が曖昧になる傾向があるということだ。
これはどういうことかと言うと、roapは入力ファイルから領域を読みとって、
それをregion要素の一番上からマッチするかどうかを試していく。
全部試したところで、一つもマッチしなければ出力さえされないのである。
前述の例の最後にあるregion要素はどんな文字列が来てもマッチするので、
出力がされないということはない。
もし、このパターン定義が一番上(最初)に来ている場合は、
全て最初にマッチングしてしまうことになり、
それ以降のパターン定義は無視されるということになる。

その他思い付く使い方
====================

o データベースへの登録バッチ処理
o LaTeX、HTMLなどのマークアップ文書作成支援

バグ報告はurago@users.sourceforge.netへ。