API Reference

Treebars.fail_progress! Method

fail_progress!(node; kwargs...)

Mark a progress node as failed. No-op when nothing.

source

Treebars.finalize_progress! Method

finalize_progress!(node; kwargs...)

Mark a progress node as complete. No-op when nothing.

Prefer @progress or with_progress instead

Manual finalize_progress! is easy to forget or skip on exceptions. Use @progress or with_progress which handle finalization and failure automatically in a try/catch/finally block.

source

Treebars.initialize_progress! Method

initialize_progress!(kind::Symbol, N; description="Running...", kwargs...)
initialize_progress!(parent::ProgressNode, N; description="Running...", kwargs...)

Create a progress root (from a backend symbol like :state or :term) or a child node (from an existing ProgressNode). Returns a ProgressNode. No-op when nothing.

Prefer @progress or with_progress instead

Calling initialize_progress! / update_progress! / finalize_progress! manually is error-prone — forgetting finalize_progress! or missing exceptions leaves progress nodes stuck in the "running" state forever. Use the convenience API:

# Best: automatic initialize + update + finalize for loops
@progress parent for i in 1:N
    # ...
end

# Good: automatic finalize + fail handling via do-block
with_progress(parent, N; description="...") do p
    for i in 1:N
        # ...
        update_progress!(p, i)
    end
end

See with_progress, @progress.

source

Treebars.short_duration Method

short_duration(dt::Union{Dates.CompoundPeriod, Dates.Period}) -> String

Human-friendly duration string: "4s", "1m 23s", "2h 5m".

source

Treebars.update_progress! Method

update_progress!(node, i; kwargs...)
update_progress!(node, message::AbstractString; kwargs...)

Update progress on node. Pass an integer to set the counter, a string for a status message, or keyword arguments to create/update labeled child nodes. No-op when nothing.

See @progress and with_progress for wrappers that handle the full initialize/update/finalize lifecycle automatically.

source

Treebars.with_progress Method

with_progress(f, kind, N; kwargs...)

Initialize progress, call f(progress_node), finalize on completion or fail on error.

source

Treebars.@progress Macro

@progress for i in 1:N ... end
@progress backend for i in 1:N ... end

Wrap a for loop with automatic progress tracking. Rewrites the loop to call initialize_progress!, update_progress!, and finalize_progress! automatically.

source