|Did you know ...||Search Documentation:|
|Pack progress_bar -- prolog/progress_bar.pl|
progress_bar makes available a DCG rule (e.g. simple_progress_bar, simple_spinner) that is to be used as part of the prolog messaging system to print the progress of a used defined process (see https://www.swi-prolog.org/pldoc/man?section=printmsg). Note that the term 'process' denotes an abstract task a user wishes to complete (i.e. it doens't refer to a separate thread)
The message is meant to be called repeatedly while the user- process progresses (i.e. it is part of the user processing loop). To this end the DCG rule (e.g. simple_progress_bar) should be provided: the current state (=Index), with respect to the total denoting completion (=Total). Additional information may be provided to allow informing the user about the processing (see example below). Note the spinner//10 doesn't define a Total (it does define Index) and therefore it's progress with respect to completion is unknown. When the user-process finishes, the user should call spinner_end//0 to end the spinner.
Under the hood, the DCG rules formats the message according to a specific layout (see progress_bar//12, and spinner//10 for details). simple_progress_bar//2, default_progress_bar//4, fancy_progress_bar//7 are specialisations of progress_bar//12 defaulting some of its values (similarily for spinner). While the user-process progresses, the DCG rule is called repeatedly (i.e. as part of the user defined loop). Every message is prefixed with a 'carriage-return only' character ('\r'), which effectively resets the last printed message, and creates the animation effect.
The example below illustrates the use of simple_progress_bar//2 within
user_defined_predicate to visually portray
advancement whilte iterating elements within the forall/2 loop. Within the forall-loop print_message/2 calls the DGC
rule my_application_does_stuff//2 to format to pre-process the message passed to default_progress_bar//4.
user_defined_predicate(...) :- ... length(Items,Total), forall(nth1(Index,Items,Item), ( print_message(informational,my_application_does_stuff(Index,Total) % do something with Item ), ... my_application_does_stuff(Index,Total) --> Percentage is (Index/Total) * 100, format(string(OutroText),"[~0f%]",[Percentage]), default_progress_bar(Index,Total,"Processing",OutroText).
The layout of the spinner message is setup according to the following schema:
SLL TL SLR SCL TC SCR SRL TR SRR
SLL stands for Spinner-Left-Left,
TL stands for Text-Left,
SLR stands for Spinner-Left-Right
The other abreviation follow the same schema
Progressis an possitive integer that represents advancement of a task (it is assumed to grow 1 with every call)
TLis a left-aligned text or message,
TCis a center-aligned text or message,
TRis a right-aligned text or message
SRRare atoms represent a spinner Id (e.g. 'classic', 'dots', .. ). Noting 'none' denotes absence of a spinner
As the termination of a spinner us unnknown a newline should be emmited when done, this can be done using end_spinner.
The layout of the bar is setup according to the following schema:
Intro [Start+++++++++++++++><---------End] Outro
'Intro'in the schema) represents the text or message that is printed before the bar
'[') defined the character used to render the left boundary of the bar
'Start') is a text or message printed at the right side of the StartMarker, provided there is sufficient space
'+') is the charcater used to render the advancement completed
'>') is a text or message that is printed (provided there is space) at the left side ('i.e done') of the current advancement
'<') is a text or message that is printed (provided there is space) at the right side (i.e. todo') of the current advancement
'-') is the character used to render the advacement that remains to be made
'End') is a text or message printed at the left side of the EndMarker, provided there is sufficient space
']') defined the character used to render the right boundary of the bar
'Outro') represents the text or message that is printed after the bar