Skip to contents

The function manages the log information for tasks that need to be linked to each other. While the information is stored as a data.frame, it is presented or saved as formatted character when asked to be presented (for instance when verbose is set to TRUE).

Usage

add_journal(journal, task, status, id, degree = 0, verbose = TRUE)

Arguments

journal

data.frame, journal to be amended. May be missing (see details).

task

character, description of the task. May be missing (see details).

status

character, description of how the task has been performed. May be missing (see details).

id

integer, row of the task to be amended. May be missing (see details).

degree

integer, indicates how deep is the task

verbose

logical, should a message be sent. Default to TRUE.

Value

a data frame of journal information.

Details

If the parameter 'journal' is missing, add_journal() creates an empty journal (a data.frame with the expected format). The data.frame have 5 columns: 'start', 'end', 'task', 'status', 'degree', and 'elapsed'.

If the parameter 'task' is not missing, and if no 'status' is given, add_journal() adds a new line to journal, and sets 'start' to current time, 'task' to given 'task'.

If the parameter 'status' is not missing, add_journal() try to find to which 'task' this is relevant. This can be done by giving explictly the 'id', or by giving the 'task'. If nothing is given, it is supposed that it corresponds with the the last task with missing 'status'. For found 'task', it sets 'status' to given 'status', 'end' to current time. 'elapsed' to the formatted difftime between 'end' and 'start' with floodam.data::fmt().

If verbose == TRUE, a message is sent. If 'task' is given, a new line is sent, but not ended by 'EOL'. When 'status' is given, message depend on what was sent just before. If the last message was announcing the start of the current task, it is completed with status and elapsed time. If not, a new line is sent with the whole information (start, task, status, elapsed). 'degree' is used to have some tabular formatting. The message sent is formatted by floodam.date:::format_journal().

Examples


add_journal()
#> [1] task    status  start   end     elapsed
#> <0 rows> (or 0-length row.names)
add_journal(status = "Nothing to be done...", verbose = FALSE)
#> Warning: Trying to add status information to an empty journal.
#> [1] task    status  start   end     elapsed
#> <0 rows> (or 0-length row.names)
{
journal = add_journal(
  task = sprintf(
    "maintain gaspar with floodam.data (%s)",
    utils::packageVersion("floodam.data")
  )
)
Sys.sleep(.1)
journal = add_journal(journal, task = "download_gaspar", degree = 1)
journal = add_journal(journal, task = "adapt_gaspar", degree = 1)
Sys.sleep(.1)
journal = add_journal(journal, task = "alert_gaspar", degree = 1)
journal = add_journal(journal, status = "Done", id = 2)
Sys.sleep(.1)
journal = add_journal(journal, status = "Done", task = "alert_gaspar")
journal = add_journal(journal, status = "Done")
journal = add_journal(journal, status = "Done")
journal
}
#> 
#> 2024-05-15 18:42:40: [1] maintain gaspar with floodam.data (0.9.43.0)...
#> 
#> 2024-05-15 18:42:41: [2] 	download_gaspar...
#> 
#> 2024-05-15 18:42:41: [3] 	adapt_gaspar...
#> 
#> 2024-05-15 18:42:41: [4] 	alert_gaspar...
#> 
#> 2024-05-15 18:42:41: [2] 	download_gaspar... Done [00:00:00:00.11]
#> 
#> 2024-05-15 18:42:41: [4] 	alert_gaspar... Done [00:00:00:00.11]
#> 
#> 2024-05-15 18:42:41: [3] 	adapt_gaspar... Done [00:00:00:00.22]
#> 
#> 2024-05-15 18:42:40: [1] maintain gaspar with floodam.data (0.9.43.0)... Done [00:00:00:00.33]
#>                 start                 end
#> 1 2024-05-15 18:42:40 2024-05-15 18:42:41
#> 2 2024-05-15 18:42:41 2024-05-15 18:42:41
#> 3 2024-05-15 18:42:41 2024-05-15 18:42:41
#> 4 2024-05-15 18:42:41 2024-05-15 18:42:41
#>                                           task status degree        elapsed
#> 1 maintain gaspar with floodam.data (0.9.43.0)   Done      0 00:00:00:00.33
#> 2                              download_gaspar   Done      1 00:00:00:00.11
#> 3                                 adapt_gaspar   Done      1 00:00:00:00.22
#> 4                                 alert_gaspar   Done      1 00:00:00:00.11