=begin
= Sary Ruby Binding Reference

== Suffix Array を用いた検索
ファイル filename に対して pattern で検索を行い、検索結果を出現位置順にソートし、行単位で表示する例です。


 #!/usr/local/bin/ruby

 require 'sary'

 pattern = ARGV.shift

 ARGV.each {|filename|
     searcher = Sary::Saercher.new(filename)
     if searcher.search(pattern)
         searcher.sort_occurrences
         searcher.each_context_line {|text| print text, "\n" }
     end
 }

== Suffix Array を作成する
行頭にインデックス ポイントを割り当てる例です。 

 #!/usr/local/bin/ruby

 require 'sary'

 filename = ARGV.shift
 arrayname = filename + ".ary"

 text = open(filename, "r")
 array = open(arrayname, "w")

 offset = 0
 text.each {|line|
     array.print [offset].pack('N')
     offset += line.length
 }
 text.close
 array.close

 builder = Sary::Builder.new(filename, arrayname)
 builder.block_sort

== Sary module
Sary::Searcher と Sary::Builder の2つのクラスを含みます。

== Searcher class
array ファイル（とテキストファイル）のクラスです。

Searcher#count_occurrences 以外のインスタンスメソッドは破壊的なメソッド
です。

--- Searcher.new(filename[,arrayname])
    検索のためにテキストファイルと array ファイルを開きます。
    引数にテキストファイル名と array ファイル名を指定します。
    array ファイル名を省略すると ((|filename|)).ary が使われます。

    失敗すると (({IOError})) 例外を発生します。

--- Searcher#search(pattern)
    キーワード検索を行ないます。

    検索に成功すると (({true}))、失敗すると (({false})) を返します。

--- Searcher#isearch(pattern, len)
    効率の良いインクリメンタル検索を行ないます。
    ((|pattern|)) を固定して、((|len|)) の値を ((|pattern|))の長さ
    まで徐々に 大きくしながら連続して呼び出すことによりインクリメンタル
    検索が出来ます。

    ((<Searcher#sort_occurrences>)) との併用はできません。

    検索に成功すると (({true}))、失敗すると (({false})) を返します。

--- Searcher#isearch_reset
    ((<Searcher#isearch>)) 用の内部状態をリセットします。

    新たな pattern で ((<Searcher#isearch>)) を呼び出すときは、事前にこ
    の関数を実行して内部状態をリセットしてください。

--- Searcher#icase_search(pattern)
    アルファベットの大文字小文字を区別しない検索を行ないます。

    検索に成功すると (({true}))、失敗すると (({false})) を返します。

--- Searcher#multi_search(pattern_array)
    配列 ((|pattern_array|)) 中のキーワードをまとめて一度に検索します.

--- Searcher#get_next_context_line
    次の検索結果を行単位で取り出します。

    この関数を連続して呼ぶと、すべての検索結果が得られます。残りの検索
    結果がないときは (({nil})) を返します。

--- Searcher#get_next_context_lines([bkwrd, frwrd])
    次の検索結果をコンテクスト行単位(直前((|bkwrd|))行、直後
    ((|frwrd|))行)で取り出します。

    この関数を連続して呼ぶと、すべての検索結果が得られます。残りの検索
    結果がないときは (({nil})) を返します。

--- Searcher#each_context_line{|text| ...}
    検索結果を含む行に対するイテレータ。

--- Searcher#each_context_lines([bkwrd, frwrd]){|text| ...}
    検索結果を含むコンテキスト行に対するイテレータ。

--- Searcher#get_next_context_region(start_tag, end_tag)
    次の検索結果を ((|start_tag|)) と ((|end_tag|)) で囲まれた領域とし
    て取り出します(((|start_tag|)) と ((|end_tag|)) を含みます)。

    この関数を連続して呼ぶと、すべての検索結果が得られます。残りの検索
    結果がないときは (({nil})) を返します。

--- Searcher#get_offsets
    検索結果を、ファイル先頭からのオフセット値の配列として取得します。

--- Searcher#get_line_by_offset(offset)
    ファイルのオフセット値から1行分を文字列として取得します。

--- Searcher#get_ranges
    検索結果を、ファイルの範囲(Rangeオブジェクト)の配列として取得します。

--- Searcher#get_line_by_range(range)
    rangeで指定されたファイルの範囲(Rangeオブジェクト)を文字列として取得
    します。

--- Searcher#count_occurrences
    検索のヒット数を返します。

--- Searcher#sort_occurrences
    検索結果を出現位置順にソートします。

--- Searcher#enable_cache
    キャッシュ機構を働かせます。検索結果をキャッシュし、同じパターンで
    の 2度目以降の検索を高速化します。

--- Searcher.array_sort(filename)
    ((|filename|)).ary ファイルをソートします。

    失敗すると (({IOError})) 例外を発生します。

== Builder class
Suffix Array を作成するためのクラスです。

--- Builder.new(filename[,arrayname])
    引数にテキストファイル名と array ファイル名を指定します。
    array ファイル名を省略すると ((|filename|)).ary が使われます。

    失敗すると (({IOError})) 例外を発生します。

--- Builder#sort [{|task, current, total, is_finished|...}]
    Suffix Array のソートを行ないます。

    プログレスバーを表示するためのブロックを渡すことができます。

    失敗すると (({RuntimeError})) 例外を発生します。

--- Builder#block_sort [{|task, current, total, is_finished|...}]
    Suffix Array のソートを行ないます。ブロック単位でソートを行なうた
    め、メモリを節約できます。

    プログレスバーを表示するためのブロックを渡すことができます。

    失敗すると (({RuntimeError})) 例外を発生します。

--- Builder#set_block_size(size)
    ((<Builder#block_sort>)) のためのブロックサイズを設定します。

--- Builder#set_nthread(n)
    ((<Builder#block_sort>)) を行なうときのスレッドの数を指定します。

    CPU が複数ある計算機では速度が向上します。
=end
$Id: Reference.ja.rd,v 1.2 2005/03/29 04:20:50 knok Exp $