On-the-fly ProgressJob reconfiguration with swapjob!()

[impact-basin]

This PR adds an additional function, swapjob!(), which is similar to addjob!() for progress bars, but allows for alteration of ProgressJob objects without displacing them from their location in the job list.

This interface is capable of many things:

• Switching between bounded (integer N) and unbounded (N == nothing) jobs,
• Changing N or the description, and
• Changing column layouts on the fly.

This is particularly useful when a set of jobs are moving through a state machine, with their best representation changing over time. An example of this might be a thread pool, where each worker in sequence is given URLs to download: we may want the task list to move from an unbounded "connecting" message, to a bounded progress bar with new columns indicating download progress, to "complete" and "idle" messages, as tasks are distributed.

(In fact, that's exactly my use case!)

I have updated the documentation and tests; the full series of commits is in this PR.

Note that this PR is independent of my other pending PR, but has been rebased on top of recent master.

A minimal example is here:

using Term, Term.Progress
import Term.Progress: DescriptionColumn, SeparatorColumn, CompletedColumn, ProgressColumn, SpinnerColumn

# make a progress bar, and add three jobs.
let p  = ProgressBar(; title = "swapjob!() Demo")
    j1 = addjob!(p; description="[1]: No N bound...")
    j2 = addjob!(p; description="[2]: No N bound...", transient = true)
    j3 = addjob!(p; description="[3]: No N bound...")

    # when we switch on limits, we will add these columns to each ProgressJob.
    cols = [DescriptionColumn, SeparatorColumn, CompletedColumn,
            SeparatorColumn, ProgressColumn, SeparatorColumn, SpinnerColumn]

    with(p) do
        for i in 1:300

            # invoke swapjob!() to change displays on-the-fly.
            if i == 50
                j1 = swapjob!(p, j1; N=300, description = "[1]: N bounded", columns = cols)
            end
            if i == 150
                j2 = swapjob!(p, j2; N=200, description = "[2]: N bounded", columns = cols)
            end
            if i == 200
                j3 = swapjob!(p, j3; N=300, description = "[3]: N bounded", columns = cols)
            end
            if i == 250
                j1 = swapjob!(p, j1, description = "[1]: Lost bound!", N=nothing, inherit = true)
            end

            update!.([j1, j2, j3])
            sleep(0.02)
        end
    end
end

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.10%. Comparing base (440ce2c) to head (65c5d1c).
⚠️ Report is 20 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #279      +/-   ##
==========================================
+ Coverage   87.27%   88.10%   +0.83%     
==========================================
  Files          48       48              
  Lines        2899     2925      +26     
==========================================
+ Hits         2530     2577      +47     
+ Misses        369      348      -21     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[impact-basin]

Seems some issues with the integration testing:

• UUID7 is OK on my machine but not globally
• Variable-scoping rules have changed between Julia versions; I'm on 1.12.

Testing issues only, but getting it cleaned up.

[impact-basin]

Just a heads-up that the pruning of the column vector in start!() for ProgressJobs creates spooky action at a distance -- it mutates the column vector provided by the caller. This is also true of the macro I was using for inheritance, so it has been removed.

I have this fixed in the patch here, but consider it to be an interface bug and will raise a separate issue.

[impact-basin]

:-)

[impact-basin]

Hi @FedeClaudi , @t-bltg, any motion on this?