| Title: | Flexible and Customisable Logging System |
|---|---|
| Description: | A comprehensive logging framework for R applications that provides hierarchical logging levels, database integration, and contextual logging capabilities. The package supports 'SQLite' storage for persistent logs, provides colour-coded console output for better readability, includes parallel processing support, and implements structured error reporting with 'JSON' formatting. |
| Authors: | Dereck Mezquita [aut, cre] |
| Maintainer: | Dereck Mezquita <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.1 |
| Built: | 2025-02-16 04:46:21 UTC |
| Source: | https://github.com/dereckmezquita/stenographer |
Concatenates vector elements into a single string. Unlike 'paste0', it handles single-element vectors without adding a trailing separator.
collapse(vector, collapse = " ")collapse(vector, collapse = " ")
vector |
A character vector to be concatenated |
collapse |
String to use as separator between elements (default: " ") |
A character string containing the concatenated elements
# Multiple elements collapse(c("a", "b", "c"), ", ") # Returns "a, b, c" # Single element - no trailing separator collapse("a", ", ") # Returns "a" # With default separator collapse(c("Hello", "World")) # Returns "Hello World" # Empty vector collapse(character(0), ", ") # Returns character(0)# Multiple elements collapse(c("a", "b", "c"), ", ") # Returns "a, b, c" # Single element - no trailing separator collapse("a", ", ") # Returns "a" # With default separator collapse(c("Hello", "World")) # Returns "Hello World" # Empty vector collapse(character(0), ", ") # Returns character(0)
Defines standard logging levels for controlling message output granularity. Use as a configuration for the 'Stenographer' class to control which messages are logged.
A list with four integer elements:
(-1) Disables all logging
(0) Logs only errors
(1) Logs errors and warnings
(2) Logs all messages
LogLevelLogLevel
An object of class list of length 4.
# Check logging levels LogLevel$OFF # -1 LogLevel$ERROR # 0 LogLevel$WARNING # 1 LogLevel$INFO # 2# Check logging levels LogLevel$OFF # -1 LogLevel$ERROR # 0 LogLevel$WARNING # 1 LogLevel$INFO # 2
Enables message output from forked processes during parallel computation using the system's echo command. Primarily designed for use with 'parallel' 'future' and 'future.apply' parallel processing.
messageParallel(...)messageParallel(...)
... |
Arguments to be concatenated into a single character string for printing |
Invisible NULL, called for its side effect of printing
This function may have significant resource overhead when used frequently or with large amounts of output. Use sparingly in performance-critical code.
# Basic usage messageParallel("Hello World") # Multiple arguments are concatenated messageParallel("Hello", " ", "World") if (requireNamespace("future", quietly = TRUE)) { future::plan(future::multisession) f <- future::future({ messageParallel("Message from parallel process") }) future::value(f) future::plan(future::sequential) }# Basic usage messageParallel("Hello World") # Multiple arguments are concatenated messageParallel("Hello", " ", "World") if (requireNamespace("future", quietly = TRUE)) { future::plan(future::multisession) f <- future::future({ messageParallel("Message from parallel process") }) future::value(f) future::plan(future::sequential) }
Provides a flexible logging system with support for multiple output destinations, customisable formatting, and contextual logging. Features include:
* Multiple log levels (ERROR, WARNING, INFO) * File-based logging * Database logging support * Customisable message formatting * Contextual data attachment * Coloured console output
Getlog level (read-only)
Getlog level (read-only)
new()
Create a new Stenographer instance
Stenographer$new( level = LogLevel$INFO, file_path = NULL, db_conn = NULL, table_name = "LOGS", print_fn = function(x) cat(x, "\n"), format_fn = function(level, msg) msg, context = list() )
levelThe minimum log level to output. Default is LogLevel$INFO.
file_pathCharacter; the path to a file to save log entries to. Default is NULL.
db_connDBI connection object; an existing database connection. Default is NULL.
table_nameCharacter; the name of the table to log to in the database. Default is "LOGS".
print_fnFunction; custom print function to use for console output. Should accept a single character string as input. Default uses cat with a newline.
format_fnFunction; custom format function to modify the log message. Should accept level and msg as inputs and return a formatted string.
contextList; initial context for the logger. Default is an empty list.
A new 'Stenographer' object.
set_level()
Update the minimum logging level
Stenographer$set_level(level)
levelNew log level (see 'LogLevel')
update_context()
Add or update contextual data
Stenographer$update_context(new_context)
new_contextList of context key-value pairs
clear_context()
Remove all contextual data
Stenographer$clear_context()
get_context()
Retrieve current context data
Stenographer$get_context()
List of current context
error()
Log an error message
Stenographer$error(msg, data = NULL, error = NULL)
msgError message text
dataOptional data to attach
errorOptional error object
warn()
Log a warning message
Stenographer$warn(msg, data = NULL)
msgWarning message text
dataOptional data to attach
info()
Log an informational message
Stenographer$info(msg, data = NULL)
msgInfo message text
dataOptional data to attach
clone()
The objects of this class are cloneable with this method.
Stenographer$clone(deep = FALSE)
deepWhether to make a deep clone.
# Create a basic Stenographer steno <- Stenographer$new() steno$info("This is an info message") steno$warn("This is a warning") steno$error("This is an error") # Disable all logging steno$set_level(LogLevel$OFF) steno$info("This won't be logged") steno$warn("This won't be logged either") steno$error("This also won't be logged") # Create a logger with custom settings, message formatting, and context custom_steno <- Stenographer$new( level = LogLevel$WARNING, file_path = tempfile("log_"), print_fn = function(x) message(paste0("Custom: ", x)), format_fn = function(level, msg) paste0("Hello prefix: ", msg), context = list(program = "MyApp") ) custom_steno$info("This won't be logged") custom_steno$warn("This will be logged with a custom prefix") # Change log level and update context custom_steno$set_level(LogLevel$INFO) custom_steno$update_context(list(user = "John")) custom_steno$info("Now this will be logged with a custom prefix and context")# Create a basic Stenographer steno <- Stenographer$new() steno$info("This is an info message") steno$warn("This is a warning") steno$error("This is an error") # Disable all logging steno$set_level(LogLevel$OFF) steno$info("This won't be logged") steno$warn("This won't be logged either") steno$error("This also won't be logged") # Create a logger with custom settings, message formatting, and context custom_steno <- Stenographer$new( level = LogLevel$WARNING, file_path = tempfile("log_"), print_fn = function(x) message(paste0("Custom: ", x)), format_fn = function(level, msg) paste0("Hello prefix: ", msg), context = list(program = "MyApp") ) custom_steno$info("This won't be logged") custom_steno$warn("This will be logged with a custom prefix") # Change log level and update context custom_steno$set_level(LogLevel$INFO) custom_steno$update_context(list(user = "John")) custom_steno$info("Now this will be logged with a custom prefix and context")
Captures the printed output of a data.frame or an R object (coerced to a data.frame) as a single string with preserved formatting. Useful for error messages, logging, and string-based output.
tableToString(obj)tableToString(obj)
obj |
An R object that can be coerced to a data.frame |
A character string containing the formatted table output with newlines
# Basic usage with a data.frame df <- data.frame( numbers = 1:3, letters = c("a", "b", "c") ) str_output <- tableToString(df) cat(str_output) # Using in error messages df <- data.frame(value = c(10, 20, 30)) if (any(df$value > 25)) { msg <- sprintf( "Values exceed threshold:\n%s", tableToString(df) ) message(msg) }# Basic usage with a data.frame df <- data.frame( numbers = 1:3, letters = c("a", "b", "c") ) str_output <- tableToString(df) cat(str_output) # Using in error messages df <- data.frame(value = c(10, 20, 30)) if (any(df$value > 25)) { msg <- sprintf( "Values exceed threshold:\n%s", tableToString(df) ) message(msg) }
Check if an object is a valid log level
valid_log_level(x)valid_log_level(x)
x |
Object to check |
Logical
Finds the positions (row and column indices) of values in a data.frame that match specified criteria. This function is useful for locating particular values within large datasets.
valueCoordinates(df, value = NA, eq_fun = value_check)valueCoordinates(df, value = NA, eq_fun = value_check)
df |
A data.frame to search |
value |
The target value to find (default: NA) |
eq_fun |
A comparison function that takes two parameters: the current value from the data.frame and the target value. Returns TRUE for matches. Default uses internal value_check function; handles NA values. |
A data.frame with two columns:
Column indices where matches were found
Row indices where matches were found
Results are sorted by column, then by row.
# Sample data.frame df <- data.frame( a = c(1, NA, 3), b = c(NA, 2, NA), c = c(3, 2, 1) ) # Find NA positions valueCoordinates(df) # Find positions of value 2 valueCoordinates(df, 2) # Find positions where values exceed 2 valueCoordinates(df, 2, function(x, y) x > y) # Find positions of values in range [1,3] valueCoordinates(df, c(1, 3), function(x, y) x >= y[1] & x <= y[2])# Sample data.frame df <- data.frame( a = c(1, NA, 3), b = c(NA, 2, NA), c = c(3, 2, 1) ) # Find NA positions valueCoordinates(df) # Find positions of value 2 valueCoordinates(df, 2) # Find positions where values exceed 2 valueCoordinates(df, 2, function(x, y) x > y) # Find positions of values in range [1,3] valueCoordinates(df, c(1, 3), function(x, y) x >= y[1] & x <= y[2])