API principal de Lua

ptool expone estos helpers principales del runtime directamente bajo ptool y p.

ptool run <lua_file> ejecuta un script Lua e inyecta la variable global ptool (o su alias p; por ejemplo, p.run es equivalente a ptool.run). Para archivos que terminan en .lua, ptool <lua_file> es un atajo de CLI con el mismo comportamiento.

El runtime Lua embebido conserva los globales básicos de Lua y, por defecto, solo expone estas bibliotecas estándar:

• table
• string
• math
• utf8

Los módulos integrados orientados al host, como io, os y package, no están disponibles intencionadamente. Usa APIs de ptool como ptool.fs, ptool.os, ptool.path y ptool.run para operaciones de sistema de archivos, entorno, procesos, red y demás tareas de runtime.

Si quieres pasar argumentos a un script Lua, puedes hacerlo así:

ptool run script.lua --name alice -v a.txt b.txt
ptool script.lua --name alice -v a.txt b.txt

Luego los argumentos pueden analizarse con ptool.args.parse(...).

Aquí tienes un script de ejemplo:

ptool.use("v0.1.0")

ptool.run("echo", {"hello", "world"})

Se admite shebang, así que puedes añadir esto al comienzo del archivo:

#!/usr/bin/env ptool

ptool.use

v0.1.0 - Introducido. v0.7.0 - Se añadieron expresiones de requisito de versión al estilo Cargo.

ptool.use declara la versión o el requisito de versión de ptool que necesita un script.

ptool.use("v0.1.0")
ptool.use("^0.6.0")
ptool.use(">= v0.6.0, < 0.7.0")

• El argumento acepta una cadena de versión semántica simple o una expresión de requisito de versión al estilo Cargo.
• Una cadena de versión simple admite un prefijo v opcional, como v0.1.0 o 0.1.0, y mantiene el comportamiento histórico de declarar la versión mínima requerida de ptool.
• Las expresiones de requisito admiten operadores y patrones como ^0.6.0, ~0.6.0, >=0.6.0, <0.7.0, 1.* y 1.2.*.
• Las expresiones de requisito también aceptan componentes de versión con un prefijo v opcional, como >= v0.6.0, < 0.7.0.
• Si la versión actual de ptool no satisface la versión o el requisito declarados, el script termina de inmediato con un error.

ptool.version

v0.8.0 - Introducido.

ptool.version() devuelve la cadena de versión actual de ptool.

• Devuelve: string.
• El valor devuelto es una cadena de versión semántica como 0.7.2.
• Úsalo cuando un script necesite imprimir, registrar o comparar la versión de ptool en tiempo de ejecución.

Ejemplo:

print(ptool.version())
print(p.version())

ptool.unindent

v0.1.0 - Introducido.

ptool.unindent procesa cadenas multilínea eliminando el prefijo | después de la indentación inicial en cada línea y recortando las líneas en blanco del principio y del final.

local str = ptool.unindent([[
  | line 1
  | line 2
]])

Esto equivale a:

local str = [[line 1
line 2]]

ptool.inspect

v0.1.0 - Introducido.

ptool.inspect(value[, options]) representa un valor Lua como una cadena legible al estilo Lua. Su objetivo principal es depurar y mostrar el contenido de tablas.

• value (any, obligatorio): El valor Lua que se va a inspeccionar.
• options (table, opcional): Opciones de renderizado. Campos admitidos:
  • indent (string, opcional): Indentación usada en cada nivel de anidación. Por defecto son dos espacios.
  • multiline (boolean, opcional): Si las tablas se representan en varias líneas. Por defecto es true.
  • max_depth (integer, opcional): Profundidad máxima de anidación que se representará. Los valores más profundos se reemplazan por <max-depth>.
• Devuelve: string.

Comportamiento:

• Las entradas tipo arreglo (1..n) se representan primero.
• Los demás campos de la tabla se representan después de la parte tipo arreglo, con un orden estable por clave.
• Las claves de cadena con forma de identificador se representan como key = value; las demás se representan como [key] = value.
• Las referencias recursivas a tablas se representan como <cycle>.
• Las funciones, threads y userdata se representan con valores marcadores como <function> y <userdata>.

Ejemplo:

local value = {
  "hello",
  user = { name = "alice", tags = {"dev", "ops"} },
}
value.self = value

print(ptool.inspect(value))
print(ptool.inspect(value, { multiline = false }))

ptool.ask

v0.1.0 - Introduced. v0.5.0 - Added validation options and prompt subcommands.

ptool.ask ofrece prompts interactivos. Puedes llamarlo directamente para pedir texto, o usar sus subprompts para confirmación, selección simple, selección múltiple y entrada secreta.

Comportamiento común:

• Todos los prompts de ptool.ask requieren un TTY interactivo. Ejecutarlos en un entorno no interactivo produce un error.
• Si el usuario cancela un prompt, el script produce un error.
• Los nombres de opción desconocidos o los tipos de valor no válidos producen un error.

ptool.ask

ptool.ask(prompt[, options]) pide al usuario una línea de texto y devuelve la respuesta.

• prompt (string, obligatorio): El prompt que se muestra al usuario.
• options (table, opcional): Opciones del prompt. Campos admitidos:
  • default (string, opcional): Valor por defecto usado cuando el usuario envía una respuesta vacía.
  • help (string, opcional): Texto de ayuda adicional mostrado bajo el prompt.
  • placeholder (string, opcional): Texto placeholder mostrado antes de que el usuario empiece a escribir.
  • required (boolean, opcional): Si la respuesta debe ser no vacía.
  • allow_empty (boolean, opcional): Si se acepta una respuesta vacía. El valor por defecto es true.
  • trim (boolean, opcional): Si se deben recortar los espacios al inicio y al final antes de devolver la respuesta.
  • min_length (integer, opcional): Longitud mínima aceptada.
  • max_length (integer, opcional): Longitud máxima aceptada.
  • pattern (string, opcional): Expresión regular que la respuesta debe cumplir.
• Devuelve: string.

Ejemplo:

local project = ptool.ask("Project name?", {
  placeholder = "my-tool",
  help = "Lowercase letters, digits, and dashes only",
  required = true,
  trim = true,
  pattern = "^[a-z0-9-]+$",
})

ptool.ask.confirm

v0.5.0 - Introducido.

ptool.ask.confirm(prompt[, options]) pide al usuario una respuesta de sí/no.

• prompt (string, obligatorio): El prompt que se muestra al usuario.
• options (table, opcional): Opciones del prompt. Campos admitidos:
  • default (boolean, opcional): Respuesta por defecto cuando el usuario pulsa Enter sin escribir.
  • help (string, opcional): Texto de ayuda adicional mostrado bajo el prompt.
• Devuelve: boolean.

Ejemplo:

local confirmed = ptool.ask.confirm("Continue?", {
  default = true,
})

ptool.ask.select

v0.5.0 - Introducido.

ptool.ask.select(prompt, items[, options]) pide al usuario elegir un elemento de una lista.

• prompt (string, obligatorio): El prompt que se muestra al usuario.
• items (table, obligatorio): Elementos candidatos. Cada entrada puede ser:
  • Un string, usado como etiqueta mostrada y como valor devuelto.
  • Un table como { label = "Patch", value = "patch" }.
• options (table, opcional): Opciones del prompt. Campos admitidos:
  • help (string, opcional): Texto de ayuda adicional mostrado bajo el prompt.
  • page_size (integer, opcional): Número máximo de filas mostradas a la vez.
  • default_index (integer, opcional): Índice 1-based del elemento inicialmente seleccionado.
• Devuelve: string.

Ejemplo:

local bump = ptool.ask.select("Select bump type", {
  { label = "Patch", value = "patch" },
  { label = "Minor", value = "minor" },
  { label = "Major", value = "major" },
}, {
  default_index = 2,
})

ptool.ask.multiselect

v0.5.0 - Introducido.

ptool.ask.multiselect(prompt, items[, options]) pide al usuario elegir cero o más elementos de una lista.

• prompt (string, obligatorio): El prompt que se muestra al usuario.
• items (table, obligatorio): Elementos candidatos. El formato es el mismo que ptool.ask.select.
• options (table, opcional): Opciones del prompt. Campos admitidos:
  • help (string, opcional): Texto de ayuda adicional mostrado bajo el prompt.
  • page_size (integer, opcional): Número máximo de filas mostradas a la vez.
  • default_indexes (table, opcional): Índices 1-based seleccionados por defecto.
  • min_selected (integer, opcional): Cantidad mínima de elementos que deben seleccionarse.
  • max_selected (integer, opcional): Cantidad máxima de elementos que pueden seleccionarse.
• Devuelve: table.

Ejemplo:

local targets = ptool.ask.multiselect("Select targets", {
  "linux",
  "macos",
  "windows",
}, {
  default_indexes = { 1, 2 },
  min_selected = 1,
})

ptool.ask.secret

v0.5.0 - Introducido.

ptool.ask.secret(prompt[, options]) pide al usuario una entrada secreta, como un token o una contraseña.

• prompt (string, obligatorio): El prompt que se muestra al usuario.
• options (table, opcional): Opciones del prompt. Campos admitidos:
  • help (string, opcional): Texto de ayuda adicional mostrado bajo el prompt.
  • required (boolean, opcional): Si la respuesta debe ser no vacía.
  • allow_empty (boolean, opcional): Si se acepta una respuesta vacía. El valor por defecto es false.
  • confirm (boolean, opcional): Si se debe pedir al usuario que escriba el secreto dos veces. El valor por defecto es false.
  • confirm_prompt (string, opcional): Prompt personalizado para el paso de confirmación.
  • mismatch_message (string, opcional): Mensaje de error personalizado cuando las dos respuestas no coinciden.
  • display_toggle (boolean, opcional): Si se permite mostrar temporalmente el secreto escrito.
  • min_length (integer, opcional): Longitud mínima aceptada.
  • max_length (integer, opcional): Longitud máxima aceptada.
  • pattern (string, opcional): Expresión regular que la respuesta debe cumplir.
• Devuelve: string.

Ejemplo:

local token = ptool.ask.secret("API token?", {
  confirm = true,
  min_length = 20,
})

ptool.config

v0.1.0 - Introducido.

ptool.config establece la configuración de runtime del script.

Campos admitidos actualmente:

• run (table, opcional): Configuración por defecto de ptool.run, ptool.run_capture, ptool.pipe y ptool.run_shell. Campos admitidos:
  • echo (boolean, opcional): Interruptor echo por defecto. Por defecto es true.
  • check (boolean, opcional): Si los fallos deben producir error por defecto. Por defecto es false.
  • confirm (boolean, opcional): Si por defecto debe requerirse confirmación antes de ejecutar. Por defecto es false.
  • retry (boolean, opcional): Si debe preguntarse al usuario si quiere reintentar después de una ejecución fallida cuando check = true. Por defecto es false.
• shell (string, opcional): Comando de shell por defecto usado por ptool.run_shell. El valor por defecto es "bash".

Ejemplo:

ptool.config({
  shell = "bash",
  run = {
    echo = false,
    check = true,
    confirm = false,
    retry = false,
  },
})

ptool.cd

v0.1.0 - Introducido.

ptool.cd(path) actualiza el directorio actual de runtime de ptool.

• path (string, obligatorio): Ruta del directorio destino, absoluta o relativa.

Comportamiento:

• Las rutas relativas se resuelven desde el directorio de runtime actual de ptool.
• El destino debe existir y debe ser un directorio.
• Esto actualiza el estado interno de runtime de ptool y afecta a las APIs que usan ese cwd de runtime (como ptool.run, ptool.path.abspath y ptool.path.relpath).

Ejemplo:

ptool.cd("foobar")
local res = ptool.run({ cmd = "pwd", stdout = "capture" })
print(res.stdout)

ptool.script_path

v0.4.0 - Introducido.

ptool.script_path() devuelve la ruta absoluta del script de entrada actual.

• Devuelve: string|nil.

Comportamiento:

• Al ejecutar con ptool run <file>, devuelve la ruta del script de entrada como una ruta absoluta y normalizada.
• La ruta devuelta queda fijada cuando se inicia el runtime y no cambia después de ptool.cd(...).
• En ptool repl, devuelve nil.

Ejemplo:

local script_path = ptool.script_path()
local script_dir = ptool.path.dirname(script_path)
local project_root = ptool.path.dirname(script_dir)

ptool.try

v0.4.0 - Introducido.

ptool.try(fn) ejecuta fn y convierte los errores lanzados en valores de retorno.

• fn (function, obligatorio): Callback que se va a ejecutar.
• Devuelve: ok, value, err.

Reglas del valor devuelto:

• En caso de éxito, ok = true, err = nil y value contiene el resultado del callback.
• Si el callback no devuelve valores, value es nil.
• Si el callback devuelve un solo valor, value es ese valor.
• Si el callback devuelve varios valores, value es una tabla tipo arreglo.
• En caso de fallo, ok = false, value = nil y err es una tabla.

Campos de error estructurado:

• kind (string): Categoría estable del error, como io_error, command_failed, invalid_argument, http_error o lua_error.
• message (string): Mensaje de error legible para humanos.
• op (string, opcional): Nombre de la API u operación, como ptool.fs.read.
• detail (string, opcional): Detalle adicional del fallo.
• path (string, opcional): Ruta implicada en un fallo del sistema de archivos.
• input (string, opcional): Entrada original que no pudo analizarse o validarse.
• cmd (string, opcional): Nombre del comando en fallos de comandos.
• status (integer, opcional): Código de salida o código HTTP cuando esté disponible.
• stderr (string, opcional): stderr capturado en fallos de comandos.
• url (string, opcional): URL implicada en un fallo HTTP.
• cwd (string, opcional): Directorio de trabajo efectivo en fallos de comandos.
• target (string, opcional): Objetivo SSH en fallos de comandos relacionados con SSH.
• retryable (boolean): Si tiene sentido reintentar. El valor por defecto es false.

Comportamiento:

• Las APIs de ptool lanzan errores estructurados. ptool.try los convierte en la tabla err anterior para que quien llama pueda ramificar según err.kind y otros campos.
• Los errores Lua normales también se capturan. En ese caso, err.kind es lua_error y solo se garantiza message.
• ptool.try es la forma recomendada de manejar errores de APIs como ptool.fs.read, ptool.http.request, ptool.run(..., { check = true }), ptool.pipe(..., { check = true }) y res:assert_ok().

Ejemplo:

local ok, content, err = ptool.try(function()
  return ptool.fs.read("missing.txt")
end)

if not ok and err.kind == "io_error" then
  print(err.op, err.path)
end

local ok2, _, err2 = ptool.try(function()
  local res = ptool.run({
    cmd = "sh",
    args = {"-c", "echo bad >&2; exit 7"},
    stderr = "capture",
  })
  res:assert_ok()
end)

if not ok2 and err2.kind == "command_failed" then
  print(err2.cmd, err2.status, err2.stderr)
end

ptool.run

v0.1.0 - Introducido.

ptool.run ejecuta comandos externos desde Rust.

Se admiten las siguientes formas de llamada:

ptool.run("echo hello world")
ptool.run("echo", "hello world")
ptool.run("echo", {"hello", "world"})
ptool.run("echo hello world", { echo = true })
ptool.run("echo", {"hello", "world"}, { echo = true })
ptool.run({ cmd = "echo", args = {"hello", "world"} })
ptool.run({ cmd = "echo", args = {"hello"}, stdout = "capture" })

Reglas de argumentos:

• ptool.run(cmdline): cmdline se divide usando reglas estilo shell (shlex). El primer elemento se trata como comando y el resto como argumentos.
• ptool.run(cmd, argsline): cmd se usa directamente como comando y argsline se divide en una lista de argumentos con reglas estilo shell (shlex).
• ptool.run(cmd, args): cmd es una cadena y args es un arreglo de cadenas.
• ptool.run(cmdline, options): options sobrescribe la configuración de esta invocación, como echo.
• ptool.run(cmd, args, options): args puede ser una cadena o un arreglo de cadenas, y options sobrescribe la configuración de esta invocación, como echo.
• ptool.run(options): options es una tabla.
• Cuando el segundo argumento es una tabla: si es un arreglo (claves enteras consecutivas 1..n), se trata como args; en caso contrario se trata como options.

Reglas del valor devuelto:

• Siempre se devuelve una tabla con los siguientes campos:
  • ok (boolean): Si el código de salida es 0.
  • code (integer|nil): El código de salida del proceso. Si el proceso fue terminado por una señal, esto es nil.
  • cmd (string): Nombre del comando usado para la ejecución.
  • cwd (string): Directorio de trabajo efectivo usado para la ejecución.
  • stdout (string, opcional): Presente cuando stdout = "capture".
  • stderr (string, opcional): Presente cuando stderr = "capture".
  • assert_ok(self) (function): Produce un error estructurado cuando ok = false. El tipo de error es command_failed y puede incluir cmd, status, stderr y cwd.
• El valor por defecto de check proviene de ptool.config({ run = { check = ... } }). Si no se configura, el valor por defecto es false. Cuando check = false, quien llama puede inspeccionar ok por su cuenta o llamar a res:assert_ok().
• Cuando check = true y retry = true, ptool.run pregunta si debe reintentarse el comando fallido antes de producir el error final.
• Cuando check = true, ptool.run produce el mismo error estructurado command_failed que res:assert_ok(). Usa ptool.try(...) si quieres capturarlo e inspeccionarlo desde Lua.

Ejemplo:

ptool.config({ run = { echo = false } })

ptool.run("echo from ptool")
ptool.run("echo", "from ptool")
ptool.run("echo", {"from", "ptool"})
ptool.run("echo from ptool", { echo = true })
ptool.run("echo", {"from", "ptool"}, { echo = true })
ptool.run("pwd")

local res = ptool.run({
  cmd = "sh",
  args = {"-c", "echo bad >&2; exit 7"},
  stderr = "capture",
})
print(res.ok, res.code)
res:assert_ok()

También se admite ptool.run(options), donde options es una tabla con los siguientes campos:

• cmd (string, obligatorio): El nombre del comando o la ruta del ejecutable.
• args (string[], opcional): La lista de argumentos.
• cwd (string, opcional): El directorio de trabajo del proceso hijo.
• env (table, opcional): Variables de entorno adicionales, donde claves y valores son nombres y valores de variable.
• stdin (string|table, opcional): Fuente de stdin del proceso hijo.
  • Una cadena envía esa misma cadena al stdin del proceso hijo.
  • Una tabla { file = "path" } lee stdin desde un archivo.
  • Si se omite, el proceso hijo hereda el stdin del proceso actual.
• trim (booleano, opcional): si se deben recortar los espacios en blanco iniciales y finales de stdout y stderr capturados antes de devolverlos. Esto solo afecta a las transmisiones configuradas en "capture". El valor predeterminado es false.
• echo (boolean, opcional): Si debe imprimirse información del comando para esta ejecución. Si se omite, se usa el valor de ptool.config({ run = { echo = ... } }); si también falta, el valor por defecto es true.
• check (boolean, opcional): Si debe producirse un error inmediatamente cuando el código de salida no es 0. Si se omite, se usa el valor de ptool.config({ run = { check = ... } }); si también falta, el valor por defecto es false.
• confirm (boolean, opcional): Si debe pedirse confirmación al usuario antes de ejecutar. Si se omite, se usa el valor de ptool.config({ run = { confirm = ... } }); si también falta, el valor por defecto es false.
• retry (boolean, opcional): Si debe preguntarse al usuario si quiere reintentar después de un fallo cuando check = true. Si se omite, se usa el valor de ptool.config({ run = { retry = ... } }); si también falta, el valor por defecto es false.
• stdout (string|table, opcional): Estrategia de manejo de stdout.
  • "inherit": hereda del terminal actual (predeterminado).
  • "capture": Capturar en res.stdout.
  • "null": Descarta la salida.
  • { file = "path" }: Escribe stdout en un archivo, truncándolo primero.
  • { file = "path", append = true }: Añade stdout al final de un archivo.
• stderr (string|table, opcional): Estrategia de manejo de stderr.
  • "inherit": hereda del terminal actual (predeterminado).
  • "capture": Capturar en res.stderr.
  • "null": Descarta la salida.
  • { file = "path" }: Escribe stderr en un archivo, truncándolo primero.
  • { file = "path", append = true }: Añade stderr al final de un archivo.
• Cuando se utilizan formularios de llamadas abreviadas como ptool.run(cmdline, options) o ptool.run(cmd, args, options), la tabla options por llamada también acepta stdin y trim con el mismo significado.
• Las rutas de redirección de archivos se resuelven relativas al cwd efectivo del proceso hijo, salvo que se proporcione una ruta absoluta.
• Cuando confirm = true:
  • Si el usuario rechaza la ejecución, se produce un error de inmediato.
  • Si el entorno actual no es interactivo (sin TTY), se produce un error de inmediato.
• Cuando retry = true y check = true:
  • Si el comando falla, ptool.run pregunta si debe reintentarse el mismo comando.
  • Si el entorno actual no es interactivo (sin TTY), se produce un error de inmediato en lugar de pedir reintento.

Ejemplo:

ptool.run({
  cmd = "echo",
  args = {"hello"},
  env = { FOO = "bar" },
})

local res0 = ptool.run({
  cmd = "cat",
  stdin = "hello from stdin",
  trim = true,
  stdout = "capture",
})
print(res0.stdout)

ptool.run({
  cmd = "sh",
  args = {"-c", "cat; printf ' err' >&2"},
  stdin = { file = "input.txt" },
  stdout = { file = "output.log" },
  stderr = { file = "error.log", append = true },
})

local res = ptool.run({
  cmd = "sh",
  args = {"-c", "printf 'out'; printf 'err' >&2; exit 7"},
  stdout = "capture",
  stderr = "capture",
  check = false,
})
print(res.ok, res.code)
print(res.stdout)
print(res.stderr)
res:assert_ok()

ptool.run_shell

v0.9.0 - Introducido.

ptool.run_shell(command) ejecuta command a través del shell configurado.

• command (string, obligatorio): Script de shell o texto de comando de shell.
• Devuelve: La misma tabla de resultado que ptool.run(...).

Comportamiento:

• El comando de shell proviene de ptool.config({ shell = ... }).
• Si shell no está configurado, ptool.run_shell(...) usa "bash".
• ptool.run_shell(command) equivale a:

ptool.run(shell, {"-c", command})

• Los valores por defecto de echo, check, confirm y retry siguen viniendo de ptool.config({ run = { ... } }).
• Si necesitas options por invocación, como cwd, env, stdin o stdout = "capture", llama a ptool.run(...) directamente con el shell y -c.

Ejemplo:

ptool.config({
  shell = "sh",
  run = {
    check = false,
  },
})

local res = ptool.run_shell("printf 'out'; printf 'err' >&2; exit 7")
print(res.ok, res.code)
res:assert_ok()

ptool.pipe

v0.9.0 - Introducido.

ptool.pipe(stages[, options]) ejecuta un pipeline local sin invocar un shell.

• stages (table, obligatorio): Lista de etapas del pipeline. Se requieren al menos dos etapas.
• options (table, opcional): Sobrescrituras por invocación.
• Devuelve: Una tabla de resultado similar a ptool.run(...).

Reglas de las etapas:

• Cada etapa puede ser una cadena de comando como "printf hello".
• Cada etapa puede ser un arreglo como {"tr", "a-z", "A-Z"}, donde el primer elemento es el comando y el resto son argumentos.
• Cada etapa puede ser una tabla como { cmd = "tr", args = {"a-z", "A-Z"} }.
• Las cadenas de comando de las etapas y las cadenas de argumentos se dividen usando reglas de estilo shell (shlex), igual que en ptool.run(...).

Reglas del valor devuelto:

• ok (boolean): Si todas las etapas salieron con estado 0.
• code (integer|nil): Estado resumido del pipeline. Si tiene éxito, este es el estado de la última etapa. Si falla, es el último estado distinto de cero, o nil si la etapa relevante terminó por una señal.
• codes (integer|nil)[]: Estados de salida por etapa en el orden de las etapas.
• cmd (string): Forma visible del pipeline completo, como printf hello | tr a-z A-Z.
• cwd (string): Directorio de trabajo efectivo usado para el pipeline.
• stdout (string, opcional): Presente cuando stdout = "capture". Captura la salida estándar de la última etapa.
• stderr (string, opcional): Presente cuando stderr = "capture". Combina la salida de error de todas las etapas en el orden de las etapas.
• assert_ok(self) (function): Lanza la misma forma de error estructurado command_failed que ptool.run(...) cuando falla cualquier etapa.

Comportamiento:

• options admite los mismos campos por invocación que ptool.run(options), salvo que cmd y args se sustituyen por la tabla posicional stages.
• Los valores por defecto de echo, check, confirm y retry siguen viniendo de ptool.config({ run = { ... } }).
• stdin se conecta a la primera etapa.
• stdout se refiere a la salida de la última etapa.
• stderr se aplica a todas las etapas.
• Cuando check = true, cualquier etapa fallida produce un error estructurado command_failed, y retry = true pregunta si debe volver a ejecutarse todo el pipeline.

Ejemplo:

local res = ptool.pipe(
  {
    "printf hello",
    {"tr", "a-z", "A-Z"},
  },
  {
    stdout = "capture",
    trim = true,
  }
)

print(res.ok, res.code)
print(res.codes[1], res.codes[2])
print(res.stdout)
res:assert_ok()

ptool.run_capture

v0.6.0 - Introducido.

ptool.run_capture ejecuta comandos externos desde Rust con las mismas formas de llamada, reglas de argumentos, reglas de valor devuelto y opciones que ptool.run.

La única diferencia es el manejo por defecto de los streams:

• stdout por defecto es "capture".
• stderr por defecto es "capture".

trim todavía tiene como valor predeterminado false y aún puede anular cualquiera de estos campos explícitamente en options.

Ejemplo:

local res = ptool.run_capture("echo hello world")
print(res.stdout)

local res2 = ptool.run_capture({
  cmd = "cat",
  stdin = "captured stdin",
  trim = true,
})
print(res2.stdout)

ptool.run_capture({
  cmd = "sh",
  args = {"-c", "printf 'captured'; printf ' problem' >&2"},
  stdout = { file = "captured.log" },
  stderr = { file = "captured.err" },
})

local res3 = ptool.run_capture("echo hello", {
  stderr = "inherit",
})
print(res3.stdout)

ptool.exec

v0.7.0 - Introducido.

ptool.exec reemplaza el proceso actual de ptool por un comando externo.

Admite las mismas formas de llamada de argumentos de comando que ptool.run:

ptool.exec("echo hello world")
ptool.exec("echo", "hello world")
ptool.exec("echo", {"hello", "world"})
ptool.exec("echo hello world", { echo = true })
ptool.exec("echo", {"hello", "world"}, { confirm = true })
ptool.exec({ cmd = "echo", args = {"hello", "world"} })

Comportamiento:

• Si tiene éxito, ptool.exec no devuelve. El proceso actual de ptool es reemplazado por el comando de destino.
• No se ejecuta ningún código Lua después de una llamada exitosa a ptool.exec(...).
• En ptool repl, una llamada exitosa a ptool.exec(...) también reemplaza el proceso del REPL.
• En plataformas Unix, esto usa semántica real de reemplazo de proceso.
• En plataformas no Unix, ptool.exec actualmente produce un error unsupported.

Reglas de argumentos:

• ptool.exec(cmdline): cmdline se divide usando reglas de estilo shell (shlex). El primer elemento se trata como comando y el resto como argumentos.
• ptool.exec(cmd, argsline): cmd se usa directamente como comando y argsline se divide en una lista de argumentos con reglas de estilo shell (shlex).
• ptool.exec(cmd, args): cmd es una cadena y args es un arreglo de cadenas.
• ptool.exec(cmdline, options): options sobrescribe la configuración de esta invocación, por ejemplo echo.
• ptool.exec(cmd, args, options): args puede ser una cadena o un arreglo de cadenas, y options sobrescribe la configuración de esta invocación, por ejemplo confirm.
• ptool.exec(options): options es una tabla.
• Cuando el segundo argumento es una tabla: si es un arreglo (claves enteras consecutivas 1..n), se trata como args; en caso contrario se trata como options.

También se admite ptool.exec(options), donde options es una tabla con los siguientes campos:

• cmd (string, obligatorio): El nombre del comando o la ruta del ejecutable.
• args (string[], opcional): La lista de argumentos.
• cwd (string, opcional): El directorio de trabajo del proceso hijo.
• env (table, opcional): Variables de entorno adicionales, donde claves y valores son nombres y valores de variable.
• stdin (table, opcional): Fuente de stdin del proceso hijo.
  • { file = "path" }: Lee stdin desde un archivo.
• echo (boolean, opcional): Si debe mostrarse información del comando antes del reemplazo. Si se omite, se usa el valor de ptool.config({ run = { echo = ... } }); si tampoco está definido, el valor predeterminado es true.
• confirm (boolean, opcional): Si debe pedirse confirmación al usuario antes del reemplazo. Si se omite, se usa el valor de ptool.config({ run = { confirm = ... } }); si tampoco está definido, el valor predeterminado es false.
• stdout (string|table, opcional): Estrategia de manejo de stdout.
  • "inherit": hereda del terminal actual (predeterminado).
  • "null": Descarta la salida.
  • { file = "path" }: Escribe stdout en un archivo, truncándolo primero.
  • { file = "path", append = true }: Añade stdout al final de un archivo.
• stderr (string|table, opcional): Estrategia de manejo de stderr.
  • "inherit": hereda del terminal actual (predeterminado).
  • "null": Descarta la salida.
  • { file = "path" }: Escribe stderr en un archivo, truncándolo primero.
  • { file = "path", append = true }: Añade stderr al final de un archivo.
• A diferencia de ptool.run, ptool.exec no admite stdin como cadena, stdout = "capture", stderr = "capture", trim, check ni retry.
• Las rutas de redirección de archivos se resuelven relativas al cwd efectivo del proceso hijo, salvo que se proporcione una ruta absoluta.
• Cuando confirm = true:
  • Si el usuario rechaza la ejecución, se produce un error de inmediato.
  • Si el entorno actual no es interactivo (sin TTY), se produce un error de inmediato.

Ejemplo:

ptool.config({ run = { echo = false } })

ptool.exec("echo from ptool")
ptool.exec("echo", "from ptool")
ptool.exec("echo", {"from", "ptool"})

ptool.exec({
  cmd = "sh",
  args = {"-c", "printf '%s|%s' \"$FOO\" \"$PWD\""},
  cwd = "crates",
  env = { FOO = "bar" },
})

ptool.exec({
  cmd = "sh",
  args = {"-c", "cat; printf ' done'; printf ' warn' >&2"},
  stdin = { file = "input.txt" },
  stdout = { file = "output.log" },
  stderr = { file = "error.log", append = true },
})