boltbuild 0.1.0

---@meta

local function use(var)
    return var
end

---Creates a driver to execute a specified command with arguments and variable expansions, primarily for task management.
---The command is a string that may include references to environment variables using `${VAR}` syntax. Variables from the
---task’s environment are expanded to strings or lists of strings, allowing flexibility in argument construction.
---
---In addition to general variables, this driver supports the special variables `SRC` and `TGT`:
---  - `${SRC}`: Expands to the list of the task's declared inputs.
---  - `${TGT}`: Expands to the list of the task's declared outputs.
---
---Pattern processing is also supported: `${PATTERN:VAR}` expands `VAR` as a list, applying `PATTERN` to each element. If
---`PATTERN` includes `%s`, each element replaces `%s`; otherwise, the pattern and element are concatenated.
---Using `${VAR[index]}`, a specific item in a list variable can be retrieved.
---
---For example, if `env.PATTERN = '-I'` and `env.SRC = {'/usr/include', '/usr/local/include'}`, the syntax `${PATTERN:SRC}`
---would expand to `-I/usr/include -I/usr/local/include`.
---
---@param name string The driver’s name.
---@param color string Color for logging this driver’s output.
---@param command string The command to execute, potentially including variables for expansion.
---@param run_before string[]|nil Optional. The name of other drivers that this driver runs before. All tasks using this driver will be scheduled before tasks using the specified drivers.
function Context:command_driver(name, color, command, run_before)
    use(name)
    use(color)
    use(command)
    use(run_before)
end

---Creates a dependency-tracking command driver that runs the specified command, similar to `command_driver`.
---This driver is specifically tailored to parse dependency outputs generated by MSVC, GCC, and Clang, such as outputs from
---the `-MD` flag for GCC/Clang and `/sourceDependencies` for MSVC. Only these tools are supported by this driver.
---
---For tools that do not produce compatible dependency files, use a Lua script driver instead (`lua_driver`), which allows
---custom dependency parsing and handling.
---
---@param name string The name of the driver, used for identification.
---@param color string A color identifier for the driver, used for console log display.
---@param command string The command string to execute.
---@param run_before string[]|nil Optional. The name of other drivers that this driver runs before. All tasks using this driver will be scheduled before tasks using the specified drivers.
function Context:dependency_driver(name, color, command, run_before)
    use(name)
    use(color)
    use(command)
    use(run_before)
end

---Creates a Lua driver that executes a specified Lua script, allowing for custom task handling and dependency parsing.
---When the Lua script is run, the `Task` object is passed as an argument, allowing the script to access task details and
---dynamically determine dependencies. The script should return two values:
---  - An exit code, where `0` indicates success.
---  - A list of additional dependencies, which includes any required files not initially listed as task inputs.
---
---This Lua driver is especially useful for tools not supported by `dependency_driver`, allowing custom logic for dependency
---management.
---
---@param name string The name of the driver, used for identification.
---@param color string A color identifier for the driver, used for console log display.
---@param script Node The path to the Lua script file to execute.
---@param run_before string[]|nil Optional. The name of other drivers that this driver runs before. All tasks using this driver will be scheduled before tasks using the specified drivers.
function Context:lua_driver(name, color, script, run_before)
    use(name)
    use(color)
    use(script)
    use(run_before)
end

---Represents a task generated by a specific generator and executable by a specified driver.
---Tasks track their dependencies, input and output nodes, and their environment, ensuring correct task execution order.
---@class Task
---@field driver string The name of the driver responsible for executing this task.
---@field generator string The name of the generator that created this task.
---@field group string The name of the task group, shared with other tasks in the same generator.
---@field env Environment The environment settings for this task, derived from the generator's environment.
---@field inputs Node[] A list of `Node` objects that serve as the inputs for this task.
---@field outputs Node[] A list of `Node` objects that are created or modified by this task.
Task = {}

---Adds one or more nodes as inputs to this task. Inputs are dependencies that must be up-to-date before the task executes.
---If adding an input creates a dependency cycle, no changes are made, and an error is raised.
---@param input Node|Node[] A `Node` or list of `Node` objects to be used as task inputs.
function Task:add_input(input)
    use(input)
end

---Adds one or more nodes as outputs for this task. Outputs are the results created or modified by the task.
---If adding an output creates a dependency cycle, no changes are made, and an error is raised.
---@param output Node|Node[] A `Node` or list of `Node` objects that are produced by the task.
function Task:add_output(output)
    use(output)
end

---Sets this task to run before the specified task.
---This ensures that this task is completed before the `other` task starts.
---
---@param other Task The task that should run after this task.
function Task:set_run_before(other)
    use(output)
end

---Sets this task to run after the specified task.
---This ensures that the `other` task is completed before this task starts.
---
---@param other Task The task that should run before this task.
function Task:set_run_after(other)
    use(output)
end

---Executes a command for the task, handling variable expansions as the `command_driver` would.
---This method allows Lua drivers to run commands with access to the task's environment, expanding any variables
---in the `command` string.
---
---Pattern expansion and list indexing follow the same rules as in `command_driver`. `${PATTERN:VAR}` applies `PATTERN`
---to each item in the list `VAR`, where `%s` in the pattern is replaced by each item. If `%s` is absent, the pattern and
---item are concatenated. `${VAR[index]}` allows retrieval of specific list elements.
---
---Returns:
---  - The command's exit code (`0` indicates success).
---  - Combined output and error logs.
---  - The expanded command string, showing what was actually executed.
---
---@param command string The command to execute, potentially including variables for expansion.
---@return number, string, string Exit code, combined output and error logs, and expanded command string.
function Task:run_command(command)
    return 0, '', ''
end