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 tags 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.
string.count( String, Capture )Descripción: 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 de Uso: string.count("El \\c&HFFFFFF& color es blanco", "color") // Devuelve 1
string.toval( String )Descripción: 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 (como 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 * 10".Ejemplo de Uso:
-- 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( String )Descripción: Reemplaza la letra i dentro de los paréntesis de un tag 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, ej: \\t(\\frz(10*i)).Ejemplo de Uso:
-- 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.
string.change( String, Capture, NoChange, NoCapture, Change )Descripción: Es una versión avanzada de string.gsub. Permite reemplazar o eliminar ocurrencias específicas de un patrón, con la capacidad de proteger otras partes del texto de ser modificadas y de omitir ciertas ocurrencias del reemplazo.
Argumentos:
String (string): El texto a modificar.Capture (string | table): El patrón a buscar.NoChange (number | table, opcional): El número de la ocurrencia que no se debe cambiar (ej. 2 para ignorar la segunda coincidencia).NoCapture (string | table, opcional): Un patrón que se debe proteger. Las coincidencias de este patrón no serán modificadas.Change (string | function, opcional): El texto o función de reemplazo. Por defecto, elimina la captura.Ejemplo de Uso: string.change("\\c&H...&\\t(\\c&H...&)", "\\c&H%x+&", nil, "\\t%b()") // Elimina el primer \c pero protege el que está dentro de \t.
string.cap( String, Capture, Extra_Capture, Filter )Descripción: Es una función de doble propósito:
string.sub para extraer un fragmento de texto, con soporte para Unicode.gsub avanzado que puede manejar patrones de captura concatenados.Argumentos (Modo 1 - Substring):
Capture (number): Posición de inicio.Extra_Capture (number): Posición final.Argumentos (Modo 2 - Gsub Avanzado):
Capture (string): Patrón principal.Extra_Capture (table): Sub-patrones.Filter (function): Función de reemplazo.string.parts( String, Parts )Descripción: 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 de Uso: string.parts("abcdef", 2) // Devuelve {"ab", "cd", "ef"}
string.moveclip( String, ... )Descripción: 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 del tag \clip rectangular, ej: \\clip(100,100,200,200).... (opcional): Una o más tablas con el formato {Dx, Dy, t1, t2, Accel} para definir movimientos personalizados. Dx, Dy es el desplazamiento.Ejemplo de Uso: tag.clip(10,10,50,50):moveclip({200, 0, 0, 1000}) // Mueve el clip 200px a la derecha durante 1 segundo.
Estas son variaciones avanzadas de las funciones estándar de LUA, diseñadas para el análisis complejo de múltiples tags de ASS en una sola cadena de texto.
string.match2( String, Capture, Table )Descripción: Captura un patrón que se repite consecutivamente. Devuelve la cadena completa de repeticiones y el número de veces que se repitió.
Ejemplo de Uso: string.match2("abcabcabc-fin", "abc") // Devuelve "abcabcabc", 3
string.newmatch( String, ... )Descripción: Intenta encontrar coincidencias con patrones progresivamente más largos, concatenando los patrones proporcionados.
Ejemplo de Uso: string.newmatch("{\\c&HFFFFFF&\\b1}", "{\\%w+&H%x+&}", "(\\%w+%d)}")
string.gmatch2( String, ... )Descripción: 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 de Uso: string.gmatch2("\\b1\\c&HFF&", "\\c&H%x+&", "\\b%d") // Devuelve {"\\b1", "\\c&HFF&"}
string.replace( String, ... )Descripción: Una versión mejorada de gsub que busca una secuencia de patrones concatenados y la reemplaza.
Ejemplo de Uso: string.replace("xy-z", "x", "y", "-", "z", "reemplazado") // Devuelve "reemplazado"