org.stekikun.dolmen.common

Class Bookkeeper

java.lang.Object

org.stekikun.dolmen.common.Bookkeeper

public final class Bookkeeper
extends Object

This is a utility class which helps keep track of a task, possibly split into several subtasks recursively. It keeps timings for the different subtasks and can display progress in a nice textual way.

For example, the following program:

  Bookkeeper bk = Bookkeeper.start(System.out, "Cooking meal");
  bk.done("Picked recipe");
  bk.infos("(Guacamole)");
  bk.enter("Gathering ingredients");
  bk.done("a ripe avocado");
  bk.done("a lime");
  bk.done("salt and pepper");
  bk.leave();
  bk.done("Found mortar and pestle");
  bk.infos("(in the cupboard)");
  bk.enter("Making the guacamole");
  bk.done("Mashed avocado");
  bk.done("Added lime juice");
  bk.leaveWith("Added seasonings");
  bk.done("Served with nachos!");
  bk.leave();
 

will produce something like this on the program's standard output:

 Cooking meal
 ├─ Picked recipe                       [1ms]
 │  (Guacamole)
 ├─ Gathering ingredients
 │  ├─ a ripe avocado                   [0ms]
 │  ├─ a lime                   [0ms]
 │  ├─ salt and pepper                  [0ms]
 │  └─ Done in 3ms
 ├─ Found mortar and pestle                     [0ms]
 │  (in the cupboard)
 ├─ Making the guacamole
 │  ├─ Mashed avocado                   [0ms]
 │  ├─ Added lime juice                 [0ms]
 │  ├─ Added seasonings                 [0ms]
 │  └─ Done in 1ms
 ├─ Served with nachos!                 [0ms]
 └─ Done in 5ms
 

A task can also be aborted at any time which results in something like this:

 Cooking meal
 ├─ Picked recipe                       [1ms]
 │  (Guacamole)
 ├─ Gathering ingredients
 │  ├─ a ripe avocado                   [0ms]
    ╧  could not found lime juice
 
 

 When the output will be displayed to an ANSI/VT-100
 terminal or emulator, it is possible to activate a colored
 mode that will take advantage of the output stream's text
 formatting capabilities.

Author:

Stéphane Lescuyer

Method Summary

Modifier and Type	Method and Description
void	aborted(String reason) Aborts the current task, and thus this bookkeeper's main task, for the given reason.
void	done(String task) Reports that the subtask task of the current task has been completed
void	enter(String task) Starts a new phase in the current task, called task, which will be split into several subtasks
void	infos(String infos) Adds some infos about the last completed subtask.
void	leave() Reports that the current task has been completed.
void	leaveWith(String task) This is equivalent to: done(task); leave(); In other words, this reports that the subtask task has been completed and that it was the last subtask of the current task.
static void	main(String[] args) A method to test Bookkeeper
void	problems(int n) Convenient wrapper around warn(String) to report on a certain number of problems found during the last completed subtask.
static Bookkeeper	start(PrintStream out, String mainTask) Same as start(out, mainTask, false).
static Bookkeeper	start(PrintStream out, String mainTask, boolean colorSupport)
void	warn(String infos) Adds some warnings about the last completed subtask.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

start

public static Bookkeeper start(PrintStream out,
                               String mainTask,
                               boolean colorSupport)

Parameters:

out -

mainTask -

colorSupport - whether out supports ANSI control sequences for text formatting

Returns:

a new bookkeeper for the task mainTask which will display progress on out

start

public static Bookkeeper start(PrintStream out,
                               String mainTask)

Same as start(out, mainTask, false).

Parameters:

out -

mainTask -

Returns:

a new bookkeeper for the task mainTask which will display progress on out

enter

public void enter(String task)

Starts a new phase in the current task, called task, which will be split into several subtasks

Parameters:

task -

done

public void done(String task)

Reports that the subtask task of the current task has been completed

Parameters:

task -

infos

public void infos(String infos)

Adds some infos about the last completed subtask.

Parameters:

infos -

warn

public void warn(String infos)

Adds some warnings about the last completed subtask.

Parameters:

infos -

problems

public void problems(int n)

Convenient wrapper around warn(String) to report on a certain number of problems found during the last completed subtask.

Parameters:

n -

aborted

public void aborted(String reason)

Aborts the current task, and thus this bookkeeper's main task, for the given reason. No more methods can be called on the Bookkeeper instance after this.

Parameters:

reason -

leave

public void leave()

Reports that the current task has been completed. Unless this was the main task, this means that the current task's parent will now become the current task.

leaveWith

public void leaveWith(String task)

This is equivalent to:

  done(task); leave();
 

In other words, this reports that the subtask task has been completed and that it was the last subtask of the current task.

Parameters:

task -

main

public static void main(String[] args)
                 throws InterruptedException

A method to test Bookkeeper

Parameters:

args -

Throws:

InterruptedException