progress.h

Simple progress bar display for the terminal inspired by node-progress

usage

#include<progress.h>

example

#include<progress.h>voidon_progress (progress_data_t*data);
intmain (void) {
progress_t*progress=progress_new(100, 60);
progress->fmt="progress [:bar] :percent :elapsed";
// listen for progressprogress_on(progress, PROGRESS_EVENT_PROGRESS, on_progress);
// tick progressprogress_tick(progress, 10);
}
voidon_progress (progress_data_t*data) {
progress_write(data->holder);
}

output

progress [======------------------------------------------------------] 10% 0.0s

usage

setup

Create a new progress_t * pointer with a given int total and progress bar size_t width.

inttotal=100;
size_twidth=20;
progress_t*progress=progress_new

format

You can define the output to stdout by setting the char * fmt member on the progress_t * pointer. Available tokens in the format string are:

• :bar - represents progress bar
• :percent - represents current progress percent
• :elapsed - represents current elapsed time in seconds as a float

progress->fmt=" downloading :percent (:elapsed) :bar";

The characters used to draw the complete and incomplete parts of the progress bar can be set too.

progress->bar_char=".";
progress->bg_bar_char=" ";

events

Bind function callbacks to events where an progress_event_type_t event is:

• PROGRESS_EVENT_START - represents an event type for when progress has begun
• PROGRESS_EVENT_PROGRESS - represents an event type for when progress has ticked
• PROGRESS_EVENT_END - represents an event type for when progress has completed

A valid callback has the following signature which accepts a progress_data_t * pointer.

voidcallback (progress_data_t*data);

progress_on(progress, PROGRESS_EVENT_START, on_progress_start);
progress_on(progress, PROGRESS_EVENT_PROGRESS, on_progress);
progress_on(progress, PROGRESS_EVENT_END, on_progress_end);

ticks

To increment progress the progress_t * pointer must be passded to progress_tick. If the total has been met then any function pointer bound to PROGRESS_EVENT_END will be called in the order they were bound.

progress_tick(progress, 42);

value

to set the progress bar to specific value you can call. If the total has been met then any function pointer bound to PROGRESS_EVENT_END will be called in the order they were bound.

progress_value(progress, 20);

inspect

You can inspect your progress_t * struct with progress_inspect(progress);.

progress_inspect(progress);

output

#progress =>
.value: 100
.total: 100
.listener_count: 3
.elapsed: 2.000000
.start: 1378344826
.width: 60
.started: true
.finished: true
.bar_char: "="
.bg_bar_char: "-"
.fmt: "progress [:bar] :percent :elapsed"
.listeners[3]

api

progress_new(total, width);

progress_t*progress_new (inttotal, size_twidth);

Initializes a new progress_t * pointer with a total and width.

example

progress_t*progress=progress_new(100, 20);

progress_event_new(type);

progress_event_t*progress_event_new(progress_event_type_ttype);

Initializes a new progress_event_t * pointer with an event type where type is of enum progress_event_types.

example

progress_event_t*=progress_event_new(PROGRESS_EVENT_PROGRESS);

progress_event_listener_new(type, cb);

progress_event_listener_t*progress_event_listener_new (progress_event_t*event, progress_cb_tcb);

Initializes a new progress_event_listener_t * pointer bound to an event with a given callback progress_cb_t function pointer.

example

...
progress_event_t*event=progress_event_new(PROGRESS_EVENT_PROGRESS);
progress_event_listener_t*listener=progress_event_listener_new(event, onprogress);
...
voidonprogress (progress_data_t*data) {
printf("value -> %d\n", data->value);
printf("ts -> %d\n", data->ts);
}

progress_event_listener_free(listener);

voidprogress_event_listener_free (progress_event_listener_t*listener);

Frees a progress_event_listener_t * pointer

example

progress_event_listener_free(listener);

progress_data_new(holder, value);

Initializes a new progress_data_t * pointer

progress_data_t*progress_data_new (progress_t*holder, intvalue);

example

progress_data_t*data=progress_data_new(progress, 32);

progress_on(progress, type, cb);

boolprogress_on (progress_t*progress, progress_event_type_ttype, progress_cb_tcb);

Binds a progress_cb_t * pointer to a progress_event_t pointer on a progress_t pointer.

example

progress_on(progress, PROGRESS_EVENT_PROGRESS, onprogress);

progress_emit(progress, event, data);

Emits an event with data.

boolprogress_emit (progress_t*progress, progress_event_t*event, progress_data_t*data);

example

progress_event_t*event=progress_event_new(PROGRESS_EVENT_START);
progress_data_t*data=progres_data_new(46);
progress_emit(progress, event, data);

progress_tick(progress, value);

Increments progress by a given value.

boolprogress_tick (progress_t*progress, intvalue);

example

progress_tick(progress, 16);

progress_value(progress, value);

set progress value

boolprogress_value (progress_t*progress, intvalue);

example

progress_value(progress, 16);

progress_write(progress);

Draws the progress bar to stdout.

voidprogress_write (progress_t*progress);

example

progress_write(progress);
// progress [======------------------------------------------------------] 10% 0.0s

progress_free(progress);

Fress a progress_t * poiinter.

voidprogress_free (progress_t*progress);

example

progress_free(progress);

license

MIT