Search documentation of Ragex

# Ragex.CLI.Progress (Ragex v0.4.0)

View Source

Progress bar and spinner utilities for CLI operations.

Provides visual feedback for long-running operations with progress bars, spinners, and status indicators.

## Summary

### Functions

bar(current, total, opts \\ [])

Renders a progress bar.

percent(percentage, opts \\ [])

Displays a percentage-based progress update.

spinner(opts \\ [])

Starts a spinner for an indeterminate operation.

start(label, opts \\ [])

Starts a progress indicator with a label.

status(message, opts \\ [])

Displays a simple status message with icon.

steps(step_names, current_step)

Renders a multi-step progress indicator.

stop(pid)

Stops a progress indicator.

stop(pid, message)

Stops a progress indicator with a completion message.

stop_spinner(pid, message \\ nil)

Stops a running spinner and displays completion message.

task_list(tasks)

Renders a task list with status indicators.

update(pid, label)

Updates a running progress indicator with a new label.

## Functions

# bar(current, total, opts \\ [])

    @spec bar(non_neg_integer(), pos_integer(), keyword()) :: :ok

Renders a progress bar.

## Options

- `:width` - Width of the progress bar (default: 40)
- `:show_percent` - Show percentage (default: true)
- `:show_fraction` - Show current/total (default: true)
- `:label` - Label to display before the bar (default: nil)
- `:complete_char` - Character for completed portion (default: "█")
- `:incomplete_char` - Character for incomplete portion (default: "░")

## Examples

    iex> Progress.bar(50, 100, label: "Processing")
    Processing [████████████████████░░░░░░░░░░░░░░░░░░░░] 50% (50/100)

# percent(percentage, opts \\ [])

    @spec percent(
      number(),
      keyword()
    ) :: :ok

Displays a percentage-based progress update.

## Examples

    iex> Progress.percent(75, label: "Upload")
    Upload: 75%

# spinner(opts \\ [])

    @spec spinner(keyword()) :: pid()

Starts a spinner for an indeterminate operation.

Returns a PID that can be used to stop the spinner. For most use cases, prefer `start/1` or `start/2`.

## Options

- `:label` - Label to display next to spinner (default: nil)
- `:frames` - Custom spinner frames (default: unicode spinner)
- `:interval` - Milliseconds between frames (default: 80)

## Examples

    iex> pid = Progress.spinner(label: "Loading")
    iex> # Do work...
    iex> Progress.stop_spinner(pid, "Done!")

# start(label, opts \\ [])

    @spec start(
      String.t(),
      keyword()
    ) :: pid() | nil

Starts a progress indicator with a label.

This is a convenience function that starts a spinner for indeterminate operations. Returns a reference that can be used with `stop/1` or `stop/2`.

## Options

- `:type` - Progress type (`:spinner` or `:dots`) (default: `:spinner`)
- `:frames` - Custom spinner frames (default: unicode spinner)
- `:interval` - Milliseconds between frames (default: 80)

## Examples

    iex> progress = Progress.start("Loading data")
    iex> # Do work...
    iex> Progress.stop(progress)

    iex> progress = Progress.start("Processing", type: :dots)
    iex> # Do work...
    iex> Progress.stop(progress, "Complete!")

# status(message, opts \\ [])

    @spec status(
      String.t(),
      keyword()
    ) :: :ok

Displays a simple status message with icon.

## Options

- `:status` - Status type (:success, :error, :warning, :info)

## Examples

    iex> Progress.status("All tests passed", status: :success)
    ✓ All tests passed

    iex> Progress.status("Warning: deprecated function", status: :warning)
    ⚠ Warning: deprecated function

# steps(step_names, current_step)

    @spec steps([String.t()], non_neg_integer()) :: :ok

Renders a multi-step progress indicator.

## Examples

    iex> Progress.steps(["Parse", "Analyze", "Generate"], 1)
    [✓] Parse
    [→] Analyze
    [ ] Generate

# stop(pid)

    @spec stop(pid() | nil) :: :ok

Stops a progress indicator.

Accepts a PID from `start/1`, `start/2`, or `spinner/1`. If nil is passed, this function is a no-op (useful for conditional progress).

## Examples

    iex> progress = Progress.start("Loading")
    iex> Progress.stop(progress)

    iex> Progress.stop(nil)  # Safe - does nothing
    :ok

# stop(pid, message)

    @spec stop(pid() | nil, String.t()) :: :ok

Stops a progress indicator with a completion message.

## Examples

    iex> progress = Progress.start("Loading")
    iex> Progress.stop(progress, "Done!")

    iex> Progress.stop(nil, "Skipped")  # Safe - just prints message
    :ok

# stop_spinner(pid, message \\ nil)

    @spec stop_spinner(pid(), String.t() | nil) :: :ok

Stops a running spinner and displays completion message.

For most use cases, prefer `stop/1` or `stop/2`.

## Examples

    iex> pid = Progress.spinner(label: "Loading")
    iex> Progress.stop_spinner(pid, "Complete!")

# task_list(tasks)

    @spec task_list([{String.t(), :done | :running | :pending | :error}]) :: :ok

Renders a task list with status indicators.

## Examples

    iex> Progress.task_list([
    ...>   {"Fetch data", :done},
    ...>   {"Process", :running},
    ...>   {"Save", :pending}
    ...> ])

# update(pid, label)

    @spec update(pid() | nil, String.t()) :: :ok

Updates a running progress indicator with a new label.

## Examples

    iex> progress = Progress.start("Step 1")
    iex> Progress.update(progress, "Step 2")