Console Progress Bar Library
#Loading the Console Progress Bar Library

The Console Progress Bar library is optional. In order to use this library, you must require it in one of your source files (preferably main.lua) prior to use. It only needs to be required once in a single file. It is recommended you do this at the top of your main.lua file, outside of any functions or other code, and you may do this by using this code:

Example:
require 'console/progressbar'
 #Usage example Basic Example
require 'console/progressbar' function doWork() -- Pretend this function actually did something useful and processed a file system.rest(100) end local filesToProcess = 50 local barWidth = 40 local style = RainbowConsoleProgressBarStyle(1.0, 2.0) local bar = ConsoleProgressBar(0, filesToProcess, barWidth, style) printf("%s", "Processing files: ") bar:begin() for i = 1, filesToProcess do doWork() bar:advance() end bar:finish()

The above example will work well enough. Consider what would happen if each file look longer than 100ms to process. The bar would only update after each file finished processing, which may be a second or more. As a result, the animation would look terrible!

To improve the animation in these types of scenarios, we could chunk the processing up further and update the bar with every chunk. This will cause the progress bar to animate much more smoothly, even between files finishing their processing.

Smoother animation
function processFile(bar) -- Pretend this function actually did something useful and processed a file local fileChunks = 1000 for i = 1, fileChunks, 10 do -- Process only a little bit of it at a time... system.rest(10) -- Update progress bar bar:update() end end local filesToProcess = 10 local barWidth = 40 local bar = ConsoleProgressBar(0, filesToProcess, barWidth, RainbowConsoleProgressBarStyle(1.0, 2.0)) printf("%s", "Processing files: ") bar:begin() for i = 1, filesToProcess do processFile(bar) bar:advance() end bar:finish()

#Available styles
Style Description Options
ConsoleProgressBarStyleThe default progress bar style.character - a single character to use. Default: #
SafeModeConsoleProgressBarStyleThe fallback style for limited ANSI supported machines
SolidConsoleProgressBarStyleA solid bar with configurable color (RGB) r - The red channel. Default: 64
g - The green channel. Default: 255
b - The blue channel. Default: 64
StoplightConsoleProgressBarStyleA solid yellow bar that turns green when completed
RainbowConsoleProgressBarStyleA rainbow bar with configurable saturation and animation saturation - Color saturation level between 0 (grayscale) and 1 (full color). A value of 0.5 would give a pastel rainbow. Default: 1.0
animSpeed - Should be a number. If given, scrolls the rainbow bar left (negitive values) or right (positive values). Default: nil
OceanWaveConsoleProgressBarStyleAn animated bar simulating ocean waves rolling in and out.speed - Default: 1.0
Animated example image of console progress bars
 #Create your own style

Creating your own Progress Bar style is easy! You need only to create a new child class from ConsoleProgressBarStyle and customize to your liking.

For basic, non-animated bars, you can generally get away with simply modifying a few properties, like filledBarFmt to style the "filled" section using ANSI console features. For more advanced and animated progress bars, you will likely want to modify the behavior of methods such as getFilledStyle() or getFilledChar(). See lib/console/progressbar_style.lua for examples on how to best leverage all of the available options.

In the below example, we see how to create a progress bar that will use alphabet characters for each position along the bar.

A custom style
require 'console/progressbar' MyStyle = class.new(ConsoleProgressBarStyle) function MyStyle:constructor() MyStyle.parent.constructor(self) -- don't show the x/y progress on the left self.showRaw = false -- Enclose the bar in curly braces {} instead of square braces [] self.startFmt = '{' self.endFmt = '}' end -- Get the character at `position` along the bar function MyStyle:getFilledChar(position, filledWidth, totalWidth, step, minStep, maxStep) local chars = {'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'} local char = chars[((position - 1) % #chars) + 1] return char end -- Just reuses getFilledChar(), since we want both to be the same for this example function MyStyle:getUnfilledChar(position, filledWidth, totalWidth, step, minStep, maxStep) return self:getFilledChar(position, filledWidth, totalWidth, step, minStep, maxStep) end local steps = 100 local width = 26 -- because 26 chars in the alphabet local bar = ConsoleProgressBar(0, steps, width, MyStyle()) bar:begin() for i = 1,steps do system.rest(50) bar:advance() end bar:finish()

#Supported Methods #Constructor class ConsoleProgressBar(number min, number max) class ConsoleProgressBar(number min, number max, number width) class ConsoleProgressBar(number min, number max, number width, ConsoleProgressBarStyle style)

Instantiates a new Console Progress Bar object. You should always specify min (the "start" number, usually 0 or 1) and max (the number of items to be completed). For example, if you had 20 files to process, you might use a min 0 and max of 20. The width of the progress bar should be specified in characters; a value between 20 and 60 is usually best.

If you do not specify style, then the default will be selected for you. You may also choose to use one of the available styles, or create your own!

#ConsoleProgressBar:begin ConsoleProgressBar:begin()

Indicates that a progress bar should start functioning. It is important to always call this right before you begin the processing loop for a progress bar, otherwise you may end up with rendering issues.

#ConsoleProgressBar:advance ConsoleProgressBar:advance() ConsoleProgressBar:advance(number amount)

Advances the progress bar's completed work indicator. If amount isn't given, a value of 1 is assumed.

You should call this after each piece of work completes. This will update the progress bar's display for you.

 #ConsoleProgressBar:finish ConsoleProgressBar:finish()

This function will redraw the progress bar and move on to the next line. You should discontinue using this instance of the progress bar after this point; rather than reusing the progress bar, create a new one.

#ConsoleProgressBar:draw ConsoleProgressBar:draw()

Forces redrawing the progress bar in its current state.

Generally, this isn't needed as it is handled automatically for you by advance() or finish().

 #ConsoleProgressBar:update ConsoleProgressBar:update()

This function will redraw the progress bar if necessary. This is based on a number of factors, including time since last redraw or whether any changes have been made.

While you generally won't need to call this manually, it can be helpful to render animated progress bars more regularly.

Page last updated at 2024-04-03 17:51:37

Copyright 2024