/**
* Cross-browser support for logging in a web application.
*
* @author David I. Lehn <dlehn@digitalbazaar.com>
*
* Copyright (c) 2008-2013 Digital Bazaar, Inc.
*/
var forge = require('./forge');
require('./util');
/* LOG API */
module.exports = forge.log = forge.log || {};
/**
* Application logging system.
*
* Each logger level available as it's own function of the form:
* forge.log.level(category, args...)
* The category is an arbitrary string, and the args are the same as
* Firebug's console.log API. By default the call will be output as:
* 'LEVEL [category] <args[0]>, args[1], ...'
* This enables proper % formatting via the first argument.
* Each category is enabled by default but can be enabled or disabled with
* the setCategoryEnabled() function.
*/
// list of known levels
forge.log.levels = [
'none', 'error', 'warning', 'info', 'debug', 'verbose', 'max'];
// info on the levels indexed by name:
// index: level index
// name: uppercased display name
var sLevelInfo = {};
// list of loggers
var sLoggers = [];
/**
* Standard console logger. If no console support is enabled this will
* remain null. Check before using.
*/
var sConsoleLogger = null;
// logger flags
/**
* Lock the level at the current value. Used in cases where user config may
* set the level such that only critical messages are seen but more verbose
* messages are needed for debugging or other purposes.
*/
forge.log.LEVEL_LOCKED = (1 << 1);
/**
* Always call log function. By default, the logging system will check the
* message level against logger.level before calling the log function. This
* flag allows the function to do its own check.
*/
forge.log.NO_LEVEL_CHECK = (1 << 2);
/**
* Perform message interpolation with the passed arguments. "%" style
* fields in log messages will be replaced by arguments as needed. Some
* loggers, such as Firebug, may do this automatically. The original log
* message will be available as 'message' and the interpolated version will
* be available as 'fullMessage'.
*/
forge.log.INTERPOLATE = (1 << 3);
// setup each log level
for(var i = 0; i < forge.log.levels.length; ++i) {
var level = forge.log.levels[i];
sLevelInfo[level] = {
index: i,
name: level.toUpperCase()
};
}
/**
* Message logger. Will dispatch a message to registered loggers as needed.
*
* @param message message object
*/
forge.log.logMessage = function(message) {
var messageLevelIndex = sLevelInfo[message.level].index;
for(var i = 0; i < sLoggers.length; ++i) {
var logger = sLoggers[i];
if(logger.flags & forge.log.NO_LEVEL_CHECK) {
logger.f(message);
} else {
// get logger level
var loggerLevelIndex = sLevelInfo[logger.level].index;
// check level
if(messageLevelIndex <= loggerLevelIndex) {
// message critical enough, call logger
logger.f(logger, message);
}
}
}
};
/**
* Sets the 'standard' key on a message object to:
* "LEVEL [category] " + message
*
* @param message a message log object
*/
forge.log.prepareStandard = function(message) {
if(!('standard' in message)) {
message.standard =
sLevelInfo[message.level].name +
//' ' + +message.timestamp +
' [' + message.category + '] ' +
message.message;
}
};
/**
* Sets the 'full' key on a message object to the original message
* interpolated via % formatting with the message arguments.
*
* @param message a message log object.
*/
forge.log.prepareFull = function(message) {
if(!('full' in message)) {
// copy args and insert message at the front
var args = [message.message];
args = args.concat([] || message['arguments']);
// format the message
message.full = forge.util.format.apply(this, args);
}
};
/**
* Applies both preparseStandard() and prepareFull() to a message object and
* store result in 'standardFull'.
*
* @param message a message log object.
*/
forge.log.prepareStandardFull = function(message) {
if(!('standardFull' in message)) {
// FIXME implement 'standardFull' logging
forge.log.prepareStandard(message);
message.standardFull = message.standard;
}
};
// create log level functions
if(true) {
// levels for which we want functions
var levels = ['error', 'warning', 'info', 'debug', 'verbose'];
for(var i = 0; i < levels.length; ++i) {
// wrap in a function to ensure proper level var is passed
(function(level) {
// create function for this level
forge.log[level] = function(category, message/*, args...*/) {
// convert arguments to real array, remove category and message
var args = Array.prototype.slice.call(arguments).slice(2);
// create message object
// Note: interpolation and standard formatting is done lazily
var msg = {
timestamp: new Date(),
level: level,
category: category,
message: message,
'arguments': args
/*standard*/
/*full*/
/*fullMessage*/
};
// process this message
forge.log.logMessage(msg);
};
})(levels[i]);
}
}
/**
* Creates a new logger with specified custom logging function.
*
* The logging function has a signature of:
* function(logger, message)
* logger: current logger
* message: object:
* level: level id
* category: category
* message: string message
* arguments: Array of extra arguments
* fullMessage: interpolated message and arguments if INTERPOLATE flag set
*
* @param logFunction a logging function which takes a log message object
* as a parameter.
*
* @return a logger object.
*/
forge.log.makeLogger = function(logFunction) {
var logger = {
flags: 0,
f: logFunction
};
forge.log.setLevel(logger, 'none');
return logger;
};
/**
* Sets the current log level on a logger.
*
* @param logger the target logger.
* @param level the new maximum log level as a string.
*
* @return true if set, false if not.
*/
forge.log.setLevel = function(logger, level) {
var rval = false;
if(logger && !(logger.flags & forge.log.LEVEL_LOCKED)) {
for(var i = 0; i < forge.log.levels.length; ++i) {
var aValidLevel = forge.log.levels[i];
if(level == aValidLevel) {
// set level
logger.level = level;
rval = true;
break;
}
}
}
return rval;
};
/**
* Locks the log level at its current value.
*
* @param logger the target logger.
* @param lock boolean lock value, default to true.
*/
forge.log.lock = function(logger, lock) {
if(typeof lock === 'undefined' || lock) {
logger.flags |= forge.log.LEVEL_LOCKED;
} else {
logger.flags &= ~forge.log.LEVEL_LOCKED;
}
};
/**
* Adds a logger.
*
* @param logger the logger object.
*/
forge.log.addLogger = function(logger) {
sLoggers.push(logger);
};
// setup the console logger if possible, else create fake console.log
if(typeof(console) !== 'undefined' && 'log' in console) {
var logger;
if(console.error && console.warn && console.info && console.debug) {
// looks like Firebug-style logging is available
// level handlers map
var levelHandlers = {
error: console.error,
warning: console.warn,
info: console.info,
debug: console.debug,
verbose: console.debug
};
var f = function(logger, message) {
forge.log.prepareStandard(message);
var handler = levelHandlers[message.level];
// prepend standard message and concat args
var args = [message.standard];
args = args.concat(message['arguments'].slice());
// apply to low-level console function
handler.apply(console, args);
};
logger = forge.log.makeLogger(f);
} else {
// only appear to have basic console.log
var f = function(logger, message) {
forge.log.prepareStandardFull(message);
console.log(message.standardFull);
};
logger = forge.log.makeLogger(f);
}
forge.log.setLevel(logger, 'debug');
forge.log.addLogger(logger);
sConsoleLogger = logger;
} else {
// define fake console.log to avoid potential script errors on
// browsers that do not have console logging
console = {
log: function() {}
};
}
/*
* Check for logging control query vars.
*
* console.level=<level-name>
* Set's the console log level by name. Useful to override defaults and
* allow more verbose logging before a user config is loaded.
*
* console.lock=<true|false>
* Lock the console log level at whatever level it is set at. This is run
* after console.level is processed. Useful to force a level of verbosity
* that could otherwise be limited by a user config.
*/
if(sConsoleLogger !== null) {
var query = forge.util.getQueryVariables();
if('console.level' in query) {
// set with last value
forge.log.setLevel(
sConsoleLogger, query['console.level'].slice(-1)[0]);
}
if('console.lock' in query) {
// set with last value
var lock = query['console.lock'].slice(-1)[0];
if(lock == 'true') {
forge.log.lock(sConsoleLogger);
}
}
}
// provide public access to console logger
forge.log.consoleLogger = sConsoleLogger;