Nuggit Logging Library
Activity is autoamtically logged to root .nuggit/nuggit_log.txt in a parseable format as required.
If logger is iniitalized with a verbose flag, all entires will be echoed to stdout.
File logging will be performed only if started with a critical flag of 1 (ie: $log->start(1)). This allows non-critical commands to utilize the same log and make usage of the verbose flag to output details to stdout.
In the future, additional verbosity levels may be implemented to allow greater control.
Log Format
Log file is a (mostly) CSV file with the following format:
Script execution is logged as timestamp, command NOTE: For nuggit, current working dir is irrelevant if within a nuggit repo.
These columns will be blank for any additional entries for a given script. Other entries may include:
A general message, prepended with ",,\t" such that the first 2 columns are empty and a tab improves readability when viewed directly.
For all other cases, remaining columns will follow in a title,value form, for example a git add command may show: CWD, current/rel/path, CMD, git add myfile
Any git commands that may affect working state should be logged as noted above with "nuggit_log" function.
Usage
# Create logger object PRIOR to any manipulation of @ARGV my $logger = Git::Nuggit::Log->new(root => $root_dir, verbose => $verbose);
# After parsing args, call start function to write initial entry # Pass an argument of 1 for critical commands (always log to file), 0 for others $logger->start(1);
# Log an explicit message $logger->log($msg);
# Log a command (automatically logs specified command and current working directory) $logger->cmd($cmd);
Function Reference
new
This is a singleton constructor. If called more than once, the original object shall be returned.
It is required to specify either root or file parameter.
Supported parameters:
- root
-
Root directory of Nuggit project. root or file parameter must be specified here or in start() if file logging is to be used.
- file
-
Name, including path, or log file to access. root or file parameter must be specified here or in start() if file logging is to be used.
- verbose
-
If set, all log commands will be output to stdout.
- file_verbose
-
Write to log file regardless of specified logging level of script
start
This function must be called before logging any additional details.
It accepts as input a log level, which is currently 0 or 1. If 1, data will be logged to the file. Additional log levels may be added in the future. If verbose flag is specified, all log output will be echoed to stdout.
If file logging is enabled, this function will open the log file for appending and record an initial command record.
This function returns a reference to it's self, allowing function chaining during initialization.
The following arguments are supported:
- level
-
0 for non-critical commands that will not be logged to file, 1 for commmands that should be logged.
- log_as_child
-
If this flag is set, initial log entry will be made as a command logged beneath the prior entry in the log file. This is intended for usage in cases where one script may invoke another in a separate execution context.
- verbose
-
If specified, set the verbose flag in the logger object to enable output to stdout.
clear
This function will clear the log file. If no argument is specified, the file will be deleted. Otherwise, the specified number of lines will be truncated.
log
Log the specified message
cmd
Log the speciied commmand. The current working directory will be included in the log entry.