// Copyright 2012 United States Government, as represented by the Secretary of Defense, Under
// Secretary of Defense (Personnel & Readiness).
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
// in compliance with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under the License
// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
// or implied. See the License for the specific language governing permissions and limitations under
// the License.
/// @module logger
/// @requires vwf/configuration
define( [ "vwf/configuration" ], function( configuration ) {
var TRACE = 1,
DEBUG = 2,
INFO = 3,
WARN = 4,
ERROR = 5,
FATAL = 6;
var exports = {
levels: {
trace: TRACE,
debug: DEBUG,
info: INFO,
warn: WARN,
error: ERROR,
// fatal: FATAL,
},
label: undefined,
context: undefined,
level: WARN,
for: function( label, context, level ) {
return Object.create( this ).configure( label, context, level );
},
configure: function( label, context, level ) {
var proto = Object.getPrototypeOf( this ) !== Object.prototype ?
Object.getPrototypeOf( this ) : undefined;
this.label = combined_label( proto && proto.label, label );
this.context = context || proto && proto.context;
this.level = { name: "warn", number: WARN }; // default
switch( level ) {
case "trace": case "TRACE": this.level = { name: "trace", number: TRACE }; break;
case "debug": case "DEBUG": this.level = { name: "debug", number: DEBUG }; break;
case "info": case "INFO": this.level = { name: "info", number: INFO }; break;
case "warn": case "WARN": this.level = { name: "warn", number: WARN }; break;
case "error": case "ERROR": this.level = { name: "error", number: ERROR }; break;
// case "fatal": case "FATAL": this.level = { name: "fatal", number: FATAL }; break;
default: proto && delete this.level; break; // inherit from the prototype
}
return this;
},
/// Log a message and open a group if the log threshold is "trace" or below.
traceg: function( /* ... */ ) {
TRACE >= this.level.number &&
log.call( this, arguments, console && console.group, console );
},
/// Log a message and open a group if the log threshold is "debug" or below.
debugg: function( /* ... */ ) {
DEBUG >= this.level.number &&
log.call( this, arguments, console && console.group, console );
},
/// Log a message and open a group if the log threshold is "info" or below.
infog: function( /* ... */ ) {
INFO >= this.level.number &&
log.call( this, arguments, console && console.group, console );
},
/// Close a group if the log threshold is "trace" or below.
traceu: function() {
TRACE >= this.level.number &&
log.call( this, arguments, console && console.groupEnd, console );
},
/// Close a group if the log threshold is "debug" or below.
debugu: function() {
DEBUG >= this.level.number &&
log.call( this, arguments, console && console.groupEnd, console );
},
/// Close a group if the log threshold is "info" or below.
infou: function() {
INFO >= this.level.number &&
log.call( this, arguments, console && console.groupEnd, console );
},
/// Log a message if the log threshold is "trace" or below.
trace: function( /* ... */ ) {
TRACE >= this.level.number &&
log.call( this, arguments, console && console.debug, console ); // not console.trace(), which would log the stack
},
/// Log a message if the log threshold is "debug" or below.
debug: function( /* ... */ ) {
DEBUG >= this.level.number &&
log.call( this, arguments, console && console.debug, console );
},
/// Log a message if the log threshold is "info" or below.
info: function( /* ... */ ) {
INFO >= this.level.number &&
log.call( this, arguments, console && console.info, console );
},
/// Log a message if the log threshold is "warn" or below.
warn: function( /* ... */ ) {
WARN >= this.level.number &&
log.call( this, arguments, console && console.warn, console );
},
/// Log a message if the log threshold is "error" or below.
error: function( /* ... */ ) {
ERROR >= this.level.number &&
log.call( this, arguments, console && console.error, console );
},
/// Log a message.
log: function( /* ... */ ) {
log.call( this, arguments, console && console.log, console );
},
// Log with an extra one-time label. Equivalent to this.logger.for( label ).log( ... ),
// etc., but without the overhead of creating a new logger.
/// Log a message with an extra one-time label and open a group if the log threshold is
/// "trace" or below.
tracegx: function( /* label, ... */ ) {
TRACE >= this.level.number &&
log.call( this, arguments, console && console.group, console, true );
},
/// Log a message with an extra one-time label and open a group if the log threshold is
/// "debug" or below.
debuggx: function( /* label, ... */ ) {
DEBUG >= this.level.number &&
log.call( this, arguments, console && console.group, console, true );
},
/// Log a message with an extra one-time label and open a group if the log threshold is
/// "info" or below.
infogx: function( /* label, ... */ ) {
INFO >= this.level.number &&
log.call( this, arguments, console && console.group, console, true );
},
/// Log a message with an extra one-time label if the log threshold is "trace" or below.
tracex: function( /* ... */ ) {
TRACE >= this.level.number &&
log.call( this, arguments, console && console.debug, console, true ); // not console.trace(), which would log the stack
},
/// Log a message with an extra one-time label if the log threshold is "debug" or below.
debugx: function( /* label, ... */ ) {
DEBUG >= this.level.number &&
log.call( this, arguments, console && console.debug, console, true );
},
/// Log a message with an extra one-time label if the log threshold is "info" or below.
infox: function( /* label, ... */ ) {
INFO >= this.level.number &&
log.call( this, arguments, console && console.info, console, true );
},
/// Log a message with an extra one-time label if the log threshold is "warn" or below.
warnx: function( /* label, ... */ ) {
WARN >= this.level.number &&
log.call( this, arguments, console && console.warn, console, true );
},
/// Log a message with an extra one-time label if the log threshold is "error" or below.
errorx: function( /* label, ... */ ) {
ERROR >= this.level.number &&
log.call( this, arguments, console && console.warn, console, true );
},
/// Log a message with an extra one-time label.
logx: function( /* label, ... */ ) {
log.call( this, arguments, console && console.log, console, true );
},
};
/// Log a message to the console. Normalize the arguments list and invoke the appender function.
///
/// @param {Array} args
/// An Array-like list of arguments passed to a log function. normalize describes the formats
/// supported.
/// @param {Function} appender
/// A Firebug-like log function that logs its arguments, such as window.console.log.
/// @param {Object} context
/// The *this* object for the appender, such as window.console.
/// @param {Boolean} [extra]
/// If true, interpret args[0] as a one-time label that extends the logger's output prefix.
function log( args, appender, context, extra ) { // invoke with *this* as the logger module
// Normalize the arguments and log the message. Don't log a message if normalize() returned
// undefined (because a generator function didn't return a result).
if ( args = /* assignment! */ normalize.call( this, args, extra ) ) {
appender && appender.apply( context, args );
}
}
/// Normalize the arguments provided to a log function. The arguments may take one of the
/// following forms:
///
/// A series of values, or a function that generates the values:
///
/// [ value, value, ... ]
/// [ function( name, number ) { return [ value, value, ... ] }, context ]
///
/// For a generator function, an optional context argument provides the function's *this*
/// context. The logger's default context will be used if the context argument is no provided.
/// The log threshold name and number ("info" and 3, for example) are passed as arguments to the
/// function.
///
/// No message will be logged if a generator function returns undefined. Since the function will
/// only be called if the message type exceeds the log threshold, logger calls may be used to
/// control program behavior based on the log level:
///
/// this.logger.debug( function( name, number ) {
/// debugControls.visible = true; // returns undefined, so no message
/// } );
///
/// When *extra* is truthy, the first argument is interpreted as a one-time label that extends
/// the logger's output prefix:
///
/// [ "label", value, value, ... ]
/// [ "label", function( name, number ) { return [ value, value, ... ] }, context ]
///
/// The arguments are normalized into a list of values ready to pass to the appender:
///
/// [ value, value, ... ]
///
/// @param {Array} args
/// An Array-like list of arguments passed to one of the log functions.
/// @param {Boolean} [extra]
/// If true, interpret args[0] as a one-time label that extends the logger's output prefix.
function normalize( args, extra ) { // invoke with *this* as the logger module
// Record the extra one-time label if one is provided. We leave it in the arguments list so
// that we don't convert Arguments to an Array if it isn't necessary.
if ( extra && ( typeof args[0] == "string" || args[0] instanceof String ) ) {
var label = args[0];
var start = 1;
} else {
var label = undefined;
var start = 0;
}
// If a generator function is provided (instead of a series of values), call it to get the
// arguments list.
if ( typeof args[ start ] == "function" || args[ start ] instanceof Function ) {
// Call the function using the provided context or this logger's context. We expect the
// function to return an array of values, a single value, or undefined.
args = args[ start ].call( args[ start+1 ] || this.context, this.level.name, this.level.number );
// Convert a single value to an Array. An Array remains an Array. Leave undefined
// unchanged.
if ( args !== undefined && ( typeof args != "object" || ! ( args instanceof Array ) ) ) {
args = [ args ];
}
} else {
// Remove the extra one-time label.
if ( start > 0 ) {
args = Array.prototype.slice.call( args, start );
}
}
// Add the prefix label to the arguments list and return. But return undefined if a
// generator didn't return a result.
return args ? prefixed_arguments( this.label, label, args ) : undefined;
}
/// Update an arguments list to prepend "<label>: " to the output.
function prefixed_arguments( label, extra, args ) {
if ( label || extra ) {
if ( args.length == 0 ) {
return [ combined_label( label, extra ) ]; // just show the module and function name when there are no additional arguments
} else if ( typeof args[0] == "string" || args[0] instanceof String ) {
return [ combined_label( label, extra ) + ": " + args[0] ].concat( Array.prototype.slice.call( args, 1 ) ); // concatenate when the first field is a string so that it may remain a format string
} else {
return [ combined_label( label, extra ) + ":" ].concat( args ); // otherwise insert a new first field
}
} else {
return args;
}
}
/// Generate a new label from a parent label and an extra part.
function combined_label( label, extra ) {
// Combine with "." unless the extension provides its own separator.
var separator = extra && extra.match( /^[0-9A-Za-z]/ ) ? "." : "";
// Concatenate and return.
if ( label && extra ) {
return label + separator + extra;
} else if ( extra ) {
return extra;
} else if ( label ) {
return label;
} else {
return undefined;
}
}
// Get the initial level setting from the configuration module, and update the level when the
// configuration changes.
// TODO: should be done somewhere else; the logger isn't bound to VWF and shouldn't have a dependency on the configuration module.
exports.configure( undefined, undefined, configuration.active["log-level"] || "warn" );
configuration.changed( function( active ) {
exports.configure( undefined, undefined, active["log-level"] || "warn" );
}, this );
// Return the module.
return exports;
} );