Senna_Snippet クラス

class Senna_Snippet

Senna_Snippetクラスは、Snippet(KWIC)を作成する機能を提供します。

このクラスは、文書内の指定したキーワードと、その前後の文を取り出して抜粋を作成します。タグを指定してキーワードをタグ付けすることも可能です。

• クラス概要
• クラス定数
  • Tokenizer関連
  • Snippet関連
  • HTMLメタ文字変換関連
  • クエリー関連
• コンストラクタ
  • __construct($encoding, $flags, $width [, $max_results [, $default_open_tag [, $default_close_tag [, $mapping ]]]])
• メソッド
  • クラスメソッド
    • createQuerySnippet($query_string, $max_exprs, $encoding, $flags, $width [, $max_results [, mixed $open_tag_list [, mixed $close_tag_list [, mixed $mapping ]]]])
  • インスタンスメソッド
    • addKeyword($keyword [, $open_tag [, $close_tag ]])
    • execute($target)
    • getKeywordCount()

クラス概要

<?php
$ss = new Senna_Snippet(
    Senna::ENC_EUC_JP, Senna_Snippet::NORMALIZE, 50, 3, '<strong>', '</strong>');

// 抽出対象キーワードを追加
$ss->addKeyword('php_senna');
$ss->addKeyword('全文検索', '<em>', '</em>');

// 登録したキーワード数
echo $ss->getKeywordCount();

// snippetの作成
$snippet_list = $ss->execute(
   "SennaのPHPバインディング「php_senna」を使って\n" .
   "オリジナル検索エンジンを作ろう\n" .
   "さあ君もphp_sennaで快適全文検索検索ライフ！"
);

echo join(' ... ', $snippet_list), ' ... ';

// クエリー文字列からインスタンス生成
$ss = Senna_Snippet::createQuerySnippet(
    'php_senna +全文検索 OR バインディング', 32,
         Senna::ENC_EUC_JP, Senna_Snippet::NORMALIZE, 50, 2, '<strong>', '</strong>')

クラス定数

Tokenizer関連

対象文字列からSnippetを作成する際の動作に関するフラグです。複数のフラグを組み合わせて指定する場合は、論理 OR (|) 演算子で連結します。

• NORMALIZE (integer)
  • 正規化してキーワードの検索を行います。
• SKIP_LEADING_SPACES (integer)
  • タグ付け対象キーワードの前に付いているスペースを含めずタグ付けします。Senna-1.1.2より前のバージョンを使用している場合、指定しても効果はありません。

「This is senna.」という文書に対してキーワード「senna」をタグ付けする場合の例：

SKIP_LEADING_SPACESフラグなし(通常):
This is<b> senna</b>.

SKIP_LEADING_SPACESフラグあり(Senna-1.1.2以降で指定可能):
This is <b>senna</b>.

Snippet関連

• MAX_RESULT_COUNT (integer)
  • 一度のexecute()で作成できるSnippet数の上限(32個)です。
• MAX_KEYWORD_COUNT (integer)
  • 1つのSenna_Snippetオブジェクトに追加可能なキーワード数の上限(32個)です。

HTMLメタ文字変換関連

• MAPPING_COMPAT (integer)
  • アンパサンド「&」を「&amp;」、少なり「<」を「&lt;」、大なり「>」を「&gt;」、ダブルクオート「"」を「&quot;」に変換します。シングルクオートは変換しません。htmlspecialchars()関数のENT_COMPATモードと同じ動作です。
• MAPPING_NONE (integer)
  • HTMLのメタ文字を変換しません。

クエリー関連

• DEFAULT_MAX_N_EXPRS (integer)
  • クエリー文字列内でタグ付け対象のキーワードとして使用する演算子数のデフォルト値(32)です。

コンストラクタ

public void __construct(
    int $encoding, int $flags, int $width [, int $max_results
        [, string $default_open_tag [, string $default_close_tag [, mixed $mapping]]]])

新しいSnippet作成用オブジェクトを生成します。

作成するSnippetの「表示上の幅」は、widthで指定したバイト数に収まる長さとなります。表示上の幅とは、ブラウザ等に表示する際、実際に可視化される文字列のバイト数です。キーワード修飾用のタグを指定した場合、そのタグの長さは含みません。そのため、作成したSnippetのstrlen()の値はwidthの値を超えることもあります。この振舞いが正しい動作かどうか確認を取っていません。Sennaのバグである可能性もあります。

default_open_tagおよびdefault_close_tagは、Snippet内のキーワードの前に付けるタグおよび後ろに付けるデフォルトのタグです。これらのタグは、可視化すると表示されない文字列（HTMLタグや書式変更用エスケープシーケンスなど）を想定しています。可視化できる通常の文字列を含めた場合、作成するSnippetの表示上の幅はwidthで指定した長さを超えることがあります。

• パラメータ
  • encoding - Snippet作成対象とする文書の文字コード
  • flags - フラグまたはNULL
  • width - 作成するSnippetの表示上の最大幅（バイト数）
  • max_results - 1つの文書から作成するSnippetの最大個数。1からSenna_Snippet::MAX_RESULT_COUNTまでの値。デフォルトは1
  • default_open_tag - キーワードの前に付けるタグ。デフォルトは空文字
  • default_close_tag - キーワードの後ろに付けるタグ。デフォルトは空文字
  • mapping - HTMLメタ文字の変換モード
• 例外
  • UnexpectedValueException - 以下の場合
    • encodingが未対応の文字コード
    • flagsで指定したフラグが使用不可
    • widthが1未満
    • max_resultsが1未満
  • SennaException - Snippet作成用オブジェクトが生成できなかった場合

メソッド

addKeyword

public Senna_Snippet addKeyword(string $keyword [, string $open_tag [, string $close_tag]])

検索対象のキーワードを追加します。

追加するキーワードの文字列長は、コンストラクタの引数widthで指定したバイト数以下である必要があります。

1つのSenna_Snippetオブジェクトには、最大Senna_Snippet::MAX_KEYWORD_COUNT個までのキーワードを追加可能です。

open_tagおよびclose_tagは、Snippet内の該当キーワードの前に付けるタグおよび後ろに付けるタグです。省略した場合はコンストラクタで指定したデフォルトのタグを使用します。これらのタグは、可視化すると表示されない文字列（HTMLタグや書式変更用エスケープシーケンスなど）を想定しています。可視化できる通常の文字列を含めた場合、作成するSnippetの表示上の幅はコンストラクタの引数widthで指定した長さを超えることがあります。

このメソッドはオブジェクト自身を返しますので、以下のように連続してメソッドを呼ぶことができます。

<?php
$ss = new Senna_Snippet(Senna::ENC_DEFAULT, 0, 128);
$ss->addKeyword('php_senna')
   ->addKeyword('検索エンジン', '<b>', '</b>')
   ->addKeyword('エクステンション', '<em>', '</em>');

• パラメータ
  • keyword - 検索対象キーワード
  • open_tag - 検索対象キーワードの前に付けるタグ
  • close_tag - 検索対象キーワードの後ろに付けるタグ
• 戻り値
  • オブジェクト自身
• 例外
  • UnexpectedValueException - 以下の場合
    • keywordが空文字
    • keywordの長さが、コンストラクタ引数widthで指定した値を超える
  • BadMethodCallException - 追加可能なキーワード数を超えた場合
  • SennaException - キーワードが追加できなかった場合

getKeywordCount

public int getKeywordCount()

このオブジェクトに登録中のキーワード数を返します。

createQuerySnippet()によって生成したオブジェクトの場合、初期状態ではcreateQuerySnippet()の第2引数max_exprsで指定した値を返します。そのため、この値は登録されている実際のキーワード数よりも多いことがあります。Senna内部で追加されたキーワード数を取得する方法が無いため、暫定的に最大キーワード数を返す仕様をとっています。

• 戻り値
  • 登録中のキーワード数

execute

public array execute(string $target)

指定された文字列からSnippetを作成し、作成したSnippetの配列を返します。指定された文字列内にキーワードが1つも含まれていない場合は空の配列を返します。

返す配列の各要素はSnippet文字列です。要素数は、最大でコンストラクタの引数max_resultsで指定した個数になります。

• パラメータ
  • target - Snippet作成対象の文書の内容
• 戻り値
  • 作成したSnippetの配列
• 例外
  • UnexpectedValueException - targetが空文字
  • SennaException - 以下の場合
    • Snippetの作成に失敗した
    • 作成したSnippetの情報を取得できなかった

createQuerySnippet

public Senna_Snippet createQuerySnippet(
    string $query_string, int $max_exprs,
        int $encoding, int $flags, int $width [, int $max_results
            [, mixed $open_tag_list [, mixed $close_tag_list [, mixed $mapping ]]]])

指定されたクエリー文字列からSenna_Snippetオブジェクトを生成します。

検索に使用したクエリー文字列を、そのままquery_string指定してください。新しいインスタンスを生成し、クエリー内の演算子を解釈してキーワードを切り出し、内部的にaddKeyword()を呼びます。クエリー内の演算子は先頭からmax_exprs個までを使用します。

キーワード修飾用のタグopen_tag_listおよびclose_tag_listは、文字列または文字列の配列を指定してください。

タグを文字列として指定した場合は、全てのキーワードを指定した文字列でタグ付けします。

タグを配列として指定した場合は、各配列の要素を順番に取り出してキーワード修飾用タグとして使用します。このとき、タグ配列の先頭の要素はクエリー内の先頭のキーワード用のタグになり、2番目の要素は2番目のキーワード用のタグになります。ただし、配列の要素数がクエリー内のキーワード数よりも少ない場合は、先頭の要素に戻って再び順番に使用します。それぞれの配列は要素数が一致していなければなりません。

その他の引数に関しては、コンストラクタの項目を参照してください。なお、このメソッドで生成したインスタンスのデフォルトタグは空文字です。addKeyword()でキーワードを追加する場合は必要に応じてタグを指定してください。

• パラメータ
  • query_string - クエリー文字列
  • max_exprs - クエリ内で使用する演算子数の上限
  • encoding - Snippet作成対象とする文書の文字コード
  • flags - フラグまたはNULL
  • width - 作成するSnippetの表示上の最大幅（バイト数）
  • max_results - 1つの文書から作成するSnippetの最大個数。1からSenna_Snippet::MAX_RESULT_COUNTまでの値。デフォルトは1
  • default_open_tag - キーワードの前に付けるタグ。デフォルトは空文字
  • default_close_tag - キーワードの後ろに付けるタグ。デフォルトは空文字
  • mapping - HTMLメタ文字の変換モード
• 戻り値
  • 指定したクエリー文字列内のキーワードを抽出対象とするSenna_Snippetオブジェクト
• 例外
  • UnexpectedValueException - 以下の場合
    • query_stringが空文字
    • (max_exprs < 1)または(Senna_Snippet::MAX_KEYWORD_COUNT < max_exprs)
    • open_tag_listとclose_tag_listの要素数が違う
    • encodingが未対応の文字コード
    • flagsで指定したフラグが使用不可
    • widthが1未満
    • max_resultsが1未満
  • SennaException - Snippet作成用オブジェクトが生成できなかった場合