terminal.lua

• Index

Contents

• Tables
• Methods

Classes

• Canvas
• EditLine
• Sequence
• canvas.TimeSeriesGraph
• canvas.Viewport
• cli.Confirm
• cli.MultiSelect
• cli.Prompt
• cli.Select
• progress.Bar
• ui.Panel
• ui.panel.Bar
• ui.panel.KeyBar
• ui.panel.Screen
• ui.panel.Set
• ui.panel.TabStrip
• ui.panel.Text

Modules

• spec.helpers
• terminal
• terminal.clear
• terminal.cursor
• terminal.cursor.position
• terminal.cursor.shape
• terminal.cursor.visible
• terminal.draw
• terminal.draw.line
• terminal.input
• terminal.input.keymap
• terminal.output
• terminal.progress
• terminal.scroll
• terminal.text
• terminal.text.color
• terminal.text.width
• terminal.utils

Topics

• 1. Introduction
• 2. Terminal handling
• 3. Text handling
• 4. Canvas (braille pixel graphics)
• CHANGELOG
• CONTRIBUTING
• MIT License

Examples

• async.lua
• canvas.lua
• car_race.lua
• colors.lua
• confirm.lua
• cow.lua
• graph.lua
• headers.lua
• keymap.lua
• multiselect.lua
• panel.lua
• progress.lua
• progressbar.lua
• prompt-copas.lua
• prompt.lua
• screen.lua
• select.lua
• sequence.lua
• tabstrip.lua
• testscreen.lua
• text_panel.lua

Class progress.Bar

A progress bar class.

A configurable horizontal progress bar that renders to a Sequence. The bar displays fixed elements (label, caps, format string, status) around a fill area, and the total output fills exactly the requested width in display columns.

Tables

progress.bar.block_tip_chars	Predefined tip-character sets for sub-character precision at the bar tip.
progress.bar.modes	Fill-mode constants for the mode constructor option.

Methods

progress.bar:get ()	Get the progress value.
progress.bar:init (opts)	Create a new Bar instance.
progress.bar:render (width)	Render the progress bar to a Sequence.
progress.bar:render_bar (fraction, width)	Render just the bar fill area.
progress.bar:set (value)	Set the progress value.
progress.bar:set_status (status)	Set the status text.

Tables

progress.bar.block_tip_chars

Predefined tip-character sets for sub-character precision at the bar tip.

Fields:

• block Array of 9 Unicode block elements for smooth fill progression

progress.bar.modes

Fill-mode constants for the mode constructor option.

Fields:

• clamp Value is clamped to [min, max] (default)
• loop Value wraps back to min after exceeding max
• bounce Value oscillates: fills left-to-right then right-to-left

Methods

progress.bar:get ()

Get the progress value.

Returns:

number The current progress value

progress.bar:init (opts)

Create a new Bar instance. Do not call this method directly, call on the class instead.

Parameters:

• opts Configuration options
  • filled_char string Character for fully-filled cells (default "█")
  • empty_char string Character for empty cells (default " ")
  • tip_chars table Array of tip characters for sub-char precision (1-indexed, ascending fill) The tip is always shown! so the range should start with empty and end with filled. (optional)
  • pad_char string Single-width character used to pad the bar to the requested width when the fill does not cover the full area; pass "" to omit padding entirely (default " ")
  • left_cap string Left bracket/delimiter (default " ")
  • right_cap string Right bracket/delimiter (default " ")
  • min number Minimum value (lower bound) (default 0)
  • max number Maximum value (upper bound) (default 100)
  • value number Initial value (defaults to opts.min) (optional)
  • mode string Fill mode: "clamp" stops at max, "loop" wraps back to min, "bounce" oscillates. See Bar.modes. (default "clamp")
  • reverse boolean When true, inverts progress (shows remaining instead) (default false)
  • label string Text printed before left cap (default "")
  • format string Format string for progress value (e.g. "%d%%" for "45%"), or nil to omit (optional)
  • status string Text printed after format string (e.g. "downloading", "complete") (default "")
  • attr textattr Text attributes wrapping entire output (optional)
  • cap_attr textattr Text attributes for left and right caps (optional)
  • filled_attr textattr Text attributes for filled + tip portion (optional)
  • empty_attr textattr Text attributes for empty portion (optional)
  • label_attr textattr Text attributes for label (optional)
  • status_attr textattr Text attributes for format string + status (optional)

Returns:

Bar A new Bar instance

Usage:

local Bar = require("terminal.progress.bar")

local bar = Bar {
  filled_char = "█", empty_char = " ",
  tip_chars = Bar.tip_chars.block,
  left_cap = "[", right_cap = "]",
  format = "%d%%",
  status = "downloading",
}

progress.bar:render (width)

Render the progress bar to a Sequence. The bar fills exactly width display columns, with fixed elements (label, caps, format, status) measured first and the fill area taking the remainder.

Parameters:

• width number Total output width in display columns

Returns:

1. Sequence The rendered bar
2. number The width passed in (sub-classes can override)
3. number Always 1 (bar height is fixed at one line, sub-classes can override)

progress.bar:render_bar (fraction, width)

Render just the bar fill area. Renders the fill, tip, and empty portions based on current value. Subclasses can override this to customize bar rendering.

Parameters:

• fraction number Progress as a fraction between 0 and 1
• width number Width available for the bar fill area (in display columns)

Returns:

1. Sequence The rendered bar fill
2. number Actual bar width in display columns (equals width unless pad_char="" and padding was needed)

progress.bar:set (value)

Set the progress value.

Parameters:

• value number The new progress value

Returns:

nothing

progress.bar:set_status (status)

Set the status text.

Parameters:

• status string The new status text (e.g. "waiting", "downloading", "unpacking", "complete")

Returns:

nothing