Librería (string)

Autortrotacalles

¿Para qué sirve?

Esta librería está diseñada para realizar operaciones complejas sobre cadenas de texto. Su principal fortaleza es el análisis y la modificación de etiquetas de ASS, permitiendo la creación de efectos dinámicos que serían muy difíciles de lograr con las funciones estándar. Incluye herramientas para contar, evaluar, transformar y animar texto de formas avanzadas.

Funciones

Funciones de análisis y conversión

string.count

Cuenta el número de veces que un patrón de texto (o un tipo de dato) aparece en una cadena. Es más potente que un gsub simple porque tiene atajos para tipos de datos comunes.

Argumentos

• String: string: El texto en el que se buscará.
• Capture: string | table: El patrón a contar. Puede ser un patrón de LUA ("%d+"), una tabla de patrones, o palabras clave especiales como "number", "color", "alpha", "shape".

Ejemplo

string.count("El \\c&HFFFFFF& color es blanco", "color") -- Devuelve: 1

string.toval

Una de las funciones más potentes. Evalúa una cadena de texto como si fuera código Lua y devuelve su resultado. Esto permite escribir expresiones matemáticas y usar variables del efecto (p.e. line.width, syl.i, etc.) directamente en las casillas de texto de la interfaz.

Argumentos

• String: string: La expresión a evaluar, por ejemplo $5 + syl.i \times 10$.

Ejemplo

-- En la casilla "Scale x":
-- La escala aumentará en 10 por cada sílaba.
100 + 10 * syl.i
-- Kara Effector usará string.toval internamente para calcular el resultado.

string.i

Reemplaza la letra i dentro de los paréntesis de una etiqueta por un contador numérico secuencial. Es extremadamente útil para crear efectos oscilantes o progresivos donde cada ocurrencia necesita un valor diferente.

Argumentos

• String: string: Una cadena de texto que contiene tags con la letra i como variable (p.e. \\t(\\frz(10*i))).

Ejemplo

-- Usado con tag.oscill para que cada oscilación sea diferente:
tag.oscill(fx.dur, 200, "\\frz(10*i)")
-- La primera oscilación tendrá \frz0, la segunda \frz10, la tercera \frz20, etc.

---

Funciones de manipulación avanzada

string.change

Versión avanzada de string.gsub. Permite reemplazar o eliminar ocurrencias específicas de un patrón, protegiendo partes del texto contra modificaciones u omitiendo coincidencias concretas.

Argumentos

• String: string: El texto a modificar.
• Capture: string | table: El patrón a buscar.
• NoChange?: number | table, opcional: Índice de la ocurrencia que no se debe cambiar (ej: 2 para ignorar la segunda coincidencia).
• NoCapture?: string | table, opcional: Patrón protegido; sus coincidencias no se modificarán.
• Change?: string | function, opcional: Texto o función de reemplazo. Por defecto elimina la captura.

Ejemplo

-- Elimina el primer \c pero protege el que está dentro de \t:
string.change("\\c&H...&\\t(\\c&H...&)", "\\c&H%x+&", nil, "\\t%b()")

string.cap

Es una función de doble propósito:

1. Si se usan números como argumentos, actúa como string.sub para extraer un fragmento de texto, con soporte para Unicode.
2. Si se usan patrones, funciona como un gsub avanzado que puede manejar patrones de captura concatenados.

Argumentos (Modo substring)

• Capture: number: Posición de inicio.
• Extra_Capture: number: Posición final.

Argumentos (Modo Gsub Avanzado)

• Capture: number: Posición de inicio.
• Extra_Capture: number: Posición final.
• Filter: function: Función de reemplazo.

string.parts

Divide un texto en una tabla de fragmentos. El tamaño de cada fragmento puede ser fijo o aleatorio.

Argumentos

• String: string: El texto a dividir. Por defecto, el texto de la línea (line.text_stripped).
• Parts: number | table: Si es un número, es el tamaño fijo de cada parte. Si es una tabla {min, max}, el tamaño de cada parte será un número aleatorio entre min y max.

Ejemplo

string.parts("abcdef", 2) -- Devuelve {"ab", "cd", "ef"}

string.moveclip

Anima un \clip rectangular para que siga una trayectoria. Puede usar automáticamente los parámetros del \move principal del efecto o configuraciones personalizadas.

Argumentos

• String: string: La cadena de la etiqueta \clip rectangular (p.e. \\clip(100,100,200,200)).
• ...?: table[], opcional: Una o más tablas con el formato {Dx, Dy, t1, t2, Accel} para definir movimientos personalizados. Dx, Dy es el desplazamiento.

Ejemplo

-- Mueve el clip 200px a la derecha durante 1 segundo.
tag.clip(10,10,50,50):moveclip({200, 0, 0, 1000})

---

Funciones de búsqueda y reemplazo especializadas

Estas son variaciones avanzadas de las funciones estándar de Lua, diseñadas para el análisis complejo de múltiples etiquetas de ASS en una sola cadena de texto.

string.match2

Captura un patrón que se repite consecutivamente. Devuelve la cadena completa de repeticiones y el número de veces que se repitió.

Ejemplo

string.match2("abcabcabc-fin", "abc") -- Devuelve "abcabcabc", 3

string.newmatch

Intenta encontrar coincidencias con patrones progresivamente más largos, concatenando los patrones proporcionados.

Ejemplo

string.newmatch("{\\c&HFFFFFF&\\b1}", "{\\%w+&H%x+&}", "(\\%w+%d)}")

string.gmatch2

Una versión mejorada de gmatch que busca múltiples patrones y devuelve las coincidencias en el orden en que aparecen en el texto original, sin importar el orden de los patrones de búsqueda.

Ejemplo

string.gmatch2("\\b1\\c&HFF&", "\\c&H%x+&", "\\b%d") -- Devuelve {"\\b1", "\\c&HFF&"}

string.replace

Una versión mejorada de gsub que busca una secuencia de patrones concatenados y la reemplaza.

Ejemplo

string.replace("xy-z", "x", "y", "-", "z", "reemplazado") -- Devuelve "reemplazado"

---

InicioVolver a la biblioteca de funciones