Processamento de Texto
O módulo text oferece expressões regulares, comparação e aplicação de patches em textos, além da divisão de documentos. Esta página é uma referência de API. Os blocos curtos são chamadas isoladas; os exemplos mais longos de divisão são receitas parciais, cujos documentos, recursos de sistema de arquivos configurados e processamento posterior pertencem à aplicação que os utiliza.
Carregamento
local text = require("text")
Expressões Regulares
text.regexp.compile
Compila uma expressão regular compatível com RE2.
local re, err = text.regexp.compile("[0-9]+")
if err then
return nil, err
end
| Parâmetro | Tipo | Descrição |
|---|---|---|
pattern |
string | Padrão regex compatível com RE2 |
Retorna: Regexp, error
re:match_string
Testa uma string contra a expressão compilada.
local ok = re:match_string("abc123")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para match |
Retorna: boolean
re:find_string
Encontra a primeira substring correspondente.
local match = re:find_string("abc123def")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para buscar |
Retorna: string | nil
Nesta versão do runtime, uma correspondência com a string vazia também é representada por nil. Use um padrão que consuma pelo menos um caractere quando for necessário distinguir uma correspondência vazia da ausência de correspondência.
re:find_all_string
Encontra todas as substrings correspondentes.
local matches = re:find_all_string("a1b2c3")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para buscar |
Retorna: string[]
re:find_string_submatch
Encontra a primeira correspondência e seus grupos de captura.
local match = re:find_string_submatch("user@example.com")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para buscar |
Retorna: string[] | nil (match completo + grupos de captura)
re:find_all_string_submatch
Encontra todas as correspondências e seus grupos de captura.
local matches = re:find_all_string_submatch("a=1 b=2")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para buscar |
Retorna: string[][]
re:find_string_index
Encontra os limites, com índices a partir de 1, da primeira correspondência.
local pos = re:find_string_index("abc123")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para buscar |
Retorna: table | nil ({início, fim}, base 1)
re:find_all_string_index
Encontra os limites de todas as correspondências.
local positions = re:find_all_string_index("a1b2c3")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para buscar |
Retorna: table[] | nil (nil quando não há correspondências)
re:replace_all_string
Substitui todas as substrings correspondentes.
local result = re:replace_all_string("a1b2", "X")
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String de entrada |
repl |
string | String de substituição |
Retorna: string
re:split
Divide uma string nas correspondências da expressão compilada.
local parts = re:split("a,b,c", -1)
| Parâmetro | Tipo | Descrição |
|---|---|---|
s |
string | String para dividir |
n |
integer | Max partes, -1 para todas |
Retorna: string[]
re:num_subexp
Retorna o número de subexpressões de captura.
local count = re:num_subexp()
Retorna: number
re:subexp_names
Retorna os nomes das subexpressões de captura.
local names = re:subexp_names()
Retorna: string[]
re:string
Retorna a string do padrão compilado.
local pattern = re:string()
Retorna: string
Diff de Texto
Compare versões de texto e gere patches com go-diff, uma implementação do algoritmo diff-match-patch do Google.
text.diff.new
Cria um comparador de textos com opções padrão ou personalizadas.
local diff, err = text.diff.new()
local diff, err = text.diff.new(options)
Retorna: Differ, error
Opções {id="diff-options"}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
diff_timeout |
number | 1.0 | Timeout em segundos |
diff_edit_cost |
integer | 4 | Custo de uma edição vazia |
match_threshold |
number | 0.5 | Tolerância de correspondência, de 0 a 1 |
match_distance |
integer | 1000 | Distância para buscar uma correspondência |
patch_delete_threshold |
number | 0.5 | Threshold de delete |
patch_margin |
integer | 4 | Margem de contexto |
diff:compare
Compara duas strings e retorna operações que transformam text1 em 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"}
| Parâmetro | Tipo | Descrição |
|---|---|---|
text1 |
string | Texto original |
text2 |
string | Texto modificado |
Retorna: table, error (array de {operation, text})
Operações: "equal", "delete", "insert"
diff:summarize
Conta os bytes UTF-8 inalterados, inseridos e excluídos. Em textos não ASCII, esses totais não são contagens de pontos de código Unicode nem de grafemas.
-- `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)
| Parâmetro | Tipo | Descrição |
|---|---|---|
diffs |
table | Array de diff do compare |
Retorna: table ({insertions, deletions, equals})
diff:pretty_text
Formata um diff com cores ANSI para exibição no terminal.
local formatted, err = diff:pretty_text(diffs)
if err then
return nil, err
end
print(formatted)
| Parâmetro | Tipo | Descrição |
|---|---|---|
diffs |
table | Array de diff do compare |
Retorna: string, error
diff:pretty_html
Formata diff como HTML com tags <del> e <ins>.
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.
| Parâmetro | Tipo | Descrição |
|---|---|---|
diffs |
table | Array de diff do compare |
Retorna: string, error
diff:patch_make
Gera patches que podem ser aplicados para transformar um texto em outro. Patches podem ser serializados e aplicados depois.
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
text1 |
string | Texto original |
text2 |
string | Texto modificado |
Retorna: table, error
diff:patch_apply
Aplica patches a uma string e retorna o resultado e a indicação de que todos os patches foram aplicados com sucesso.
local result, success = diff:patch_apply(patches, text1)
-- result = "The quick red fox jumps over the lazy cat"
-- success = true
Verifique success antes de tratar result como a transformação solicitada. Passe tabelas de patches produzidas por patch_make; nesta versão do runtime, texto serializado malformado dentro de uma tabela construída manualmente pode ser ignorado, em vez de gerar um erro separado.
| Parâmetro | Tipo | Descrição |
|---|---|---|
patches |
table | Patches de patch_make |
text |
string | Texto para aplicar patches |
Retorna: string, boolean
Divisão de Texto
Divide documentos em trechos preservando limites semânticos. Os divisores se baseiam na implementação do langchaingo.
text.splitter.recursive
O divisor recursivo tenta primeiro duas quebras de linha, depois uma quebra de linha, espaços e, por fim, caracteres individuais. Ele avança para o separador seguinte quando um trecho excede o limite de tamanho.
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
Retorna: Splitter, error
Opções {id="recursive-splitter-options"}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
chunk_size |
integer | 4000 | Max caracteres por chunk |
chunk_overlap |
integer | 200 | Caracteres repetidos entre chunks adjacentes |
keep_separator |
boolean | false | Manter separadores na saída |
separators |
string[] | nil | Lista customizada de separadores |
text.splitter.markdown
O divisor Markdown pode manter títulos com seu conteúdo, preservar blocos de código e agrupar linhas de tabela.
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)
Esta receita parcial exige que a entrada habilite text e fs, que exista um recurso de sistema de arquivos app:docs configurado e que um README.md legível esteja disponível nesse recurso.
Retorna: Splitter, error
Opções {id="markdown-splitter-options"}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
chunk_size |
integer | 4000 | Max caracteres por chunk |
chunk_overlap |
integer | 200 | Caracteres repetidos entre chunks adjacentes |
code_blocks |
boolean | false | Manter blocos de código juntos |
reference_links |
boolean | false | Preservar links de referência |
heading_hierarchy |
boolean | false | Respeitar niveis de heading |
join_table_rows |
boolean | false | Manter linhas de tabela juntas |
separators |
string[] | nil | Lista de separadores customizada |
splitter:split_text
Divide um único documento em um array de chunks.
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
Aqui, splitter é um divisor criado com sucesso, enquanto document e process são fornecidos pela aplicação.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text |
string | Texto para dividir |
Retorna: string[], error
splitter:split_batch
Divide múltiplos documentos preservando seus metadados. Cada documento de entrada pode produzir vários trechos de saída. Todos os trechos herdam os metadados do documento de origem.
-- 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
pages |
table | Array de {content, metadata} |
Retorna: table, error (array de {content, metadata})
split_batch ignora silenciosamente um item quando ele não é uma tabela, quando seu campo content está ausente, vazio ou não é uma string, ou quando a divisão desse item falha. Ainda assim, retorna os demais trechos com erro nil. Valide cada item antes da chamada e verifique na aplicação qualquer requisito de cardinalidade; uma chamada bem-sucedida não prova que todas as entradas foram representadas.
Erros
| Condição | Tipo | Retentável |
|---|---|---|
| Sintaxe de padrão inválida | errors.INVALID |
não |
| Erro interno | errors.INTERNAL |
não |
Veja Tratamento de Erros para trabalhar com erros.