テキスト処理

textモジュールは、正規表現、テキストの比較とパッチ適用、文書分割を提供します。このページはAPIリファレンスです。短いコードブロックは独立した呼び出しであり、長い分割処理のコードブロックは部分的なレシピです。そこで扱う文書、設定済みファイルシステムリソース、後続処理は周囲のアプリケーションが提供します。

ロード

local text = require("text")

正規表現

text.regexp.compile

RE2互換の正規表現をコンパイルします。

local re, err = text.regexp.compile("[0-9]+")
if err then
    return nil, err
end

戻り値: Regexp, error

re:match_string

コンパイル済みの式に文字列が一致するかを調べます。

local ok = re:match_string("abc123")

戻り値: boolean

re:find_string

最初に一致する部分文字列を検索します。

local match = re:find_string("abc123def")

戻り値: string | nil

このランタイムの固定バージョンでは、空文字列との一致もnilで表されます。一致なしと空文字列との一致を区別する必要がある場合は、少なくとも1文字を消費するパターンを使用してください。

re:find_all_string

一致するすべての部分文字列を検索します。

local matches = re:find_all_string("a1b2c3")

戻り値: string[]

re:find_string_submatch

最初の一致とそのキャプチャグループを検索します。

local match = re:find_string_submatch("user@example.com")

戻り値: string[] | nil（完全マッチ + キャプチャグループ）

re:find_all_string_submatch

すべての一致と各キャプチャグループを検索します。

local matches = re:find_all_string_submatch("a=1 b=2")

戻り値: string[][]

re:find_string_index

最初の一致範囲を1始まりのインデックスで検索します。

local pos = re:find_string_index("abc123")

戻り値: table | nil（{start, end}、1ベース）

re:find_all_string_index

すべての一致範囲を検索します。

local positions = re:find_all_string_index("a1b2c3")

戻り値: table[] | nil（一致がない場合は nil）

re:replace_all_string

一致するすべての部分文字列を置換します。

local result = re:replace_all_string("a1b2", "X")

戻り値: string

re:split

コンパイル済みの式に一致する位置で文字列を分割します。

local parts = re:split("a,b,c", -1)

戻り値: string[]

re:num_subexp

キャプチャ用部分式の数を返します。

local count = re:num_subexp()

戻り値: number

re:subexp_names

キャプチャ用部分式の名前を返します。

local names = re:subexp_names()

戻り値: string[]

re:string

コンパイル済みパターンの文字列を返します。

local pattern = re:string()

戻り値: string

テキスト差分

テキストの各バージョンを比較してパッチを生成します。go-diffは、Googleのdiff-match-patchアルゴリズムを実装しています。

text.diff.new

デフォルトまたはカスタムオプションを指定してテキストDifferを作成します。

local diff, err = text.diff.new()
local diff, err = text.diff.new(options)

戻り値: Differ, error

オプション {id="diff-options"}

diff:compare

2つの文字列を比較し、text1をtext2へ変換する操作を返します。

local diff, diff_err = text.diff.new()
if diff_err then
    return nil, diff_err
end
local diffs, err = diff:compare("hello world", "hello there")
if err then
    return nil, err
end

-- diffs contains:
-- {operation = "equal", text = "hello "}
-- {operation = "delete", text = "world"}
-- {operation = "insert", text = "there"}

戻り値: table, error（{operation, text}の配列）

操作: "equal"、"delete"、"insert"

diff:summarize

変更されていない、挿入された、削除されたUTF-8バイト数を集計します。非ASCIIテキストでは、これらの合計はUnicodeコードポイント数や書記素数ではありません。

-- `diffs` is the checked result from diff:compare.
local summary = diff:summarize(diffs)

-- summary.equals = 6 (bytes unchanged)
-- summary.deletions = 5 (bytes removed)
-- summary.insertions = 5 (bytes added)

戻り値: table（{insertions, deletions, equals}）

diff:pretty_text

ターミナル表示用にANSIカラーで差分をフォーマットします。

local formatted, err = diff:pretty_text(diffs)
if err then
    return nil, err
end
print(formatted)

戻り値: string, error

diff:pretty_html

<del>要素と<ins>要素を使用して、差分をHTMLとしてフォーマットします。

local html, err = diff:pretty_html(diffs)
if err then
    return nil, err
end
-- `html` is an HTML fragment with equal, deleted, and inserted spans.

戻り値: string, error

diff:patch_make

テキストを別のテキストに変換するためのパッチを生成します。パッチはシリアライズして後で適用できます。

local text1 = "The quick brown fox jumps over the lazy dog"
local text2 = "The quick red fox jumps over the lazy cat"

local patches, err = diff:patch_make(text1, text2)
if err then
    return nil, err
end

戻り値: table, error

diff:patch_apply

テキストを変換するためにパッチを適用します。結果とすべてのパッチが正常に適用されたかどうかを返します。

local result, success = diff:patch_apply(patches, text1)
-- result = "The quick red fox jumps over the lazy cat"
-- success = true

戻り値: string, boolean

要求した変換としてresultを扱う前にsuccessを確認してください。patch_makeが生成したパッチテーブルを渡してください。このランタイムの固定バージョンでは、手作業で作ったテーブルに含まれる不正なシリアライズ済みパッチテキストは、個別のエラーとして報告されずにスキップされる場合があります。

テキスト分割

意味上の境界を保ちながら、文書をチャンクに分割します。スプリッターはlangchaingoの実装に基づいています。

text.splitter.recursive

再帰スプリッターは、二重改行、単一改行、空白、個々の文字の順に試します。チャンクがサイズ制限を超えると、次の区切り文字へ移ります。

local splitter, err = text.splitter.recursive({
    chunk_size = 1000,
    chunk_overlap = 100
})
if err then
    return nil, err
end

local long_text = "This is a long text that needs splitting..."
local chunks, split_err = splitter:split_text(long_text)
if split_err then
    return nil, split_err
end

戻り値: Splitter, error

オプション {id="recursive-splitter-options"}

text.splitter.markdown

Markdownスプリッターは、見出しとその本文をまとめ、コードブロックを保持し、テーブル行をグループ化できます。

local splitter, err = text.splitter.markdown({
    chunk_size = 2000,
    code_blocks = true,
    heading_hierarchy = true
})
if err then
    return nil, err
end

local readme = fs.get("app:docs"):readfile("README.md")
local chunks, err = splitter:split_text(readme)

この部分的なレシピでは、実行エントリでtextとfsの両方を有効にし、app:docsファイルシステムリソースを設定して、そのリソース内のREADME.mdを読み取り可能にする必要があります。

戻り値: Splitter, error

オプション {id="markdown-splitter-options"}

splitter:split_text

単一のドキュメントをチャンクの配列に分割します。

local chunks, err = splitter:split_text(document)
if err then
    return nil, err
end

for i, chunk in ipairs(chunks) do
    -- Process each chunk (e.g., create embedding, send to LLM)
    process(chunk)
end

ここで、splitterは正常に作成されたスプリッターであり、documentとprocessはアプリケーションから渡されます。

戻り値: string[], error

splitter:split_batch

メタデータを保持したまま複数の文書を分割します。1つの入力文書から複数のチャンクが生成される場合があり、それぞれに元の文書のメタデータが付与されます。

-- Input: pages from a PDF with page numbers
local pages = {
    {content = "First page content...", metadata = {page = 1}},
    {content = "Second page content...", metadata = {page = 2}}
}

local chunks, err = splitter:split_batch(pages)
if err then
    return nil, err
end

-- Output: each chunk knows which page it came from
for _, chunk in ipairs(chunks) do
    print("Page " .. chunk.metadata.page .. ": " .. chunk.content:sub(1, 50))
end

戻り値: table, error（{content, metadata}の配列）

入力要素がテーブルでない場合、contentフィールドが欠落、空、または文字列でない場合、あるいはその要素の分割に失敗した場合、split_batchはその要素を通知せずにスキップします。残りのチャンクはnilエラーとともに返されます。呼び出し前に各入力要素を検証し、要素数に関する要件はアプリケーションコードで確認してください。呼び出しが成功しても、すべての入力が結果に含まれた証明にはなりません。

エラー

エラーの扱いについては、エラー処理を参照してください。