mpm.auto_progress: a console progress bar for impatient users

[mpmxyz 27]

Introduction

 

We all know the problem:

Users - including me - can be quite impatient.

This is especially true if a busy program does not give a clue if it is actually doing something.

That's where a progress bar is useful.

This library - I named it 'auto_progress' - makes it easy to include a nice progress bar into your program.

 

Apart from the progress bar itself you also get a numeric indication and a time to finish estimate.

To avoid cluttering the limited screen space it is only activated if your program didn't finish the first 50% within a second.

Redrawing is limited to 4 redraws per second to reduce the slowdown due to drawing operations.

 

To use it you need a number to describe an amount of 'work'.

This can be a number of bytes, a number of items or any unit you like. (You define it!)

 

API

FUNCTIONS

auto_progress.new(totalWork or table or nil) -> progress_state
 if the parameter is a table: uses this table as the progress_state, adds methods and default values
 if it is a number: creates a new progress state with totalWork set to the number
 if it is nil: creates a new progress state with totalWork=1

progress_state.update(workAdded)
 adds 'workAdded' to the internal progress counter and updates the progress bar if necessary.
 (should be called at regular intervals)

progress_state.finish()
 draws the final 100%-progress bar if it has been drawn before.
 (should be called if the program finished it's operation successfully)

progress_state.draw()
 forces drawing the progress bar.
 It also cancels the initial drawing delay by setting progress_state.drawing to true.

PROPERTIES

progress_state.x, progress_state.y
 uses the given position to draw the progress bar. (recommended if you want to use the progress bar within an UI)
 Nil values are replaced by the corresponding term.getCursor() ordinates,
 unless both values are nil and the cursor isn't at the beginning of the line.
 Then they will be set to the beginning of the next line.

progress_state.width
 sets the width of the progress bar; nil makes the progress bar extend to the end of the line.

progress_state.drawing
 setting this to true cancels the drawing delay.
 
progress_state.disabled
 true disables automatic drawing; manual drawing is still possible though.

progress_state.doneWork
 the counter which is summing up all workAdded values from progress_state.update()

progress_state.totalWork
 the amount of work that corrensponds to 100%

progress_state.creationTime
 the computer.uptime() when the object was created
 
progress_state.lastUpdate
 the computer.uptime() from the last progress_state.draw() call

Example

--load library
local auto_progress = require 'mpm.auto_progress'
--generate a list of actions
local todo = {}
for i=1, 30 do
  todo[i] = math.random() * 2
end
--create progress bar: initialize it with the amount of work to do
local pbar = auto_progress.new(#todo)
for _, duration in pairs(todo) do
  --simulate an action
  os.sleep(duration)
  --update progress bar: 1 step done
  pbar.update(1)
end
--tell progress bar that the action has been finished
pbar.finish()

Example output:

[-----50% ETA: 30s     ]

[----------100%----------]

 

Dependencies

 

Software

This library only depends on standard OpenComputers libraries.

It was tested with OpenComputers 1.4.1.14.

 

Hardware

To see a progress bar you obviously need a screen and a gpu.

But the library itself should work fine without them. Anything else is a bug!

 

Installation

 

Just download the library and move it to the lib directory of your choice.

I recommend "/home/lib".

 

Download (last update: 07.05.15)

 

github

 

Ingame:

wget 'https://raw.githubusercontent.com/mpmxyz/ocprograms/master/home/lib/mpm/auto_progress.lua'

Update from 07.05.15: changed library name from "auto_progress" to "mpm.auto_progress" to clean up library directories

 

Known Issues

 

The progress bar does not move upward, if you print something on the screen that causes scrolling.

If you have an idea how to fix that or any other suggestion, feel free to leave a comment below.

 

I also added a lot of features while writing this description.

If something doesn't work as expected: It's a bug in the code or in the documentation.