Class and Namespace LrLogger

This class provides a mechanism for writing debug output that can be viewed with an external log viewer application.

Use the imported namespace as a constructor; access the functions through the created objects.

Common applications for viewing debug output are:

  • DebugView (available for download from Microsoft)
  • WinDBG (available for download from Microsoft)
  • Microsoft Developer Studio
  • Console (built-in application on Mac OS: look in /Applications/Utilities)
  • Xcode

Configure loggers using the config.lua file as follows:

  • Create an entry for each logger of interest by specifying loggers.loggerName = {...}
  • Arguments in the table include logLevel and a string "fatal", "error", "warn", "info", "debug", or "trace".
  • For each valid log level, you can add an entry to modify the behavior of log messages for that level. For example, to log to a file, add the entry trace = 'logfile',
  • To specify an action for all log levels, add the entry action = 'logfile',

Summary

LrLogger( name )
Creates a new logger or finds and returns an existing one.
logger:debug( ... )
Feeds log output through the action function defined for 'debug' messages.
logger:debugf( format, ... )
Feeds log output through the action function defined for 'debug' messages, using string.format to prepare the output.
logger:disable()
Disables all log output from this logger.
logger:enable( actions )
Enables specific log output from this logger.
logger:error( ... )
Feeds log output through the action function defined for 'error' messages.
logger:errorf( format, ... )
Feeds log output through the action function defined for 'error' messages, using string.format to prepare the output.
logger:fatal( ... )
Feeds log output through the action function defined for 'fatal' messages.
logger:fatalf( format, ... )
Feeds log output through the action function defined for 'fatal' messages, using string.format to prepare the output.
logger:info( ... )
Feeds log output through the action function defined for 'info' messages.
logger:infof( format, ... )
Feeds log output through the action function defined for 'info' messages, using string.format to prepare the output.
logger:quick( ... )
Creates optimized versions of specified log functions for use in tight loops.
logger:quickf( ... )
Creates optimized versions of specified log functions for use in tight loops.
logger:trace( ... )
Feeds log output through the action function defined for 'trace' messages.
logger:tracef( format, ... )
Feeds log output through the action function defined for 'trace' messages, using string.format to prepare the output.
logger:type()
Reports the type of this object.
logger:warn( ... )
Feeds log output through the action function defined for 'warn' messages.
logger:warnf( format, ... )
Feeds log output through the action function defined for 'warn' messages, using string.format to prepare the output.

Functions

LrLogger( name )
Creates a new logger or finds and returns an existing one. Loggers are silent until configured with LrLogger:enable().

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. name
(optional, string) A name for this logger.

Return value

(LrLogger) An LrLogger object.
  • If name matches an existing logger, returns that LrLogger object.
  • If name does not match any existing logger, returns a new, named LrLogger object.
  • If name is nil, returns an application-wide "default" LrLogger object.
logger:debug( ... )
Feeds log output through the action function defined for 'debug' messages.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
Data to be printed, of any type; tostring() is called on all values.
logger:debugf( format, ... )
Feeds log output through the action function defined for 'debug' messages, using string.format to prepare the output.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. format
(string) formatting instructions (see Lua's string.format for details)
2. ...
Arguments to string.format required by format string
logger:disable()
Disables all log output from this logger. Equivalent to logger:enable( false ).

First supported in version 1.3 of the Lightroom SDK.

logger:enable( actions )
Enables specific log output from this logger.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. actions
(string, function, or table) What action to take for each log action type. For each of the action types, this must be either a function that takes a string (the log message), or one of the following strings:
  • print: print to console log
  • traceback: print to console log with stack traceback
  • logfile: print to a log file named for the logger. This log file is written to your ~/Documents folder in Mac OS, or to your My Documents folder in Windows.

As a shortcut, you can pass a single string or function, which is applied to all of the log output from this logger.

logger:error( ... )
Feeds log output through the action function defined for 'error' messages.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
Data to be printed, of any type; tostring() is called on all values.
logger:errorf( format, ... )
Feeds log output through the action function defined for 'error' messages, using string.format to prepare the output.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. format
(string) formatting instructions (see Lua's string.format for details)
2. ...
Arguments to string.format required by format string
logger:fatal( ... )
Feeds log output through the action function defined for 'fatal' messages.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
Data to be printed, of any type; tostring() is called on all values.
logger:fatalf( format, ... )
Feeds log output through the action function defined for 'fatal' messages, using string.format to prepare the output.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. format
(string) formatting instructions (see Lua's string.format for details)
2. ...
Arguments to string.format required by format string
logger:info( ... )
Feeds log output through the action function defined for 'info' messages.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
Data to be printed, of any type; tostring() is called on all values.
logger:infof( format, ... )
Feeds log output through the action function defined for 'info' messages, using string.format to prepare the output.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. format
(string) formatting instructions (see Lua's string.format for details)
2. ...
Arguments to string.format required by format string
logger:quick( ... )
Creates optimized versions of specified log functions for use in tight loops. This version avoids the overhead of the method lookup, and is reduced to a no-op function when logging is disabled. For example: 
 local warn, info = logger:quick( 'warn', 'info' )
 warn( 'something bad happened' )

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
(one or more strings) The names of log functions to optimize.

Return value

(one or more functions) The optimized functions.
logger:quickf( ... )
Creates optimized versions of specified log functions for use in tight loops. This version avoids the overhead of the method lookup, and is reduced to a no-op function when logging is disabled. Unlike the functions returned by logger:quick, these functions take string.format instructions. For example: 
 local warnf, infof = logger:quickf( 'warn', 'info' )
 warnf( 'something %s happened', 'bad' )

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. ...
(one or more strings) The names of log functions to optimize.

Return value

(one or more functions) The optimized functions.
logger:trace( ... )
Feeds log output through the action function defined for 'trace' messages.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
Data to be printed, of any type; tostring() is called on all values.
logger:tracef( format, ... )
Feeds log output through the action function defined for 'trace' messages, using string.format to prepare the output.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. format
(string) formatting instructions (see Lua's string.format for details)
2. ...
Arguments to string.format required by format string
logger:type()
Reports the type of this object.

First supported in version 4.1 of the Lightroom SDK.

Return value

(string) 'LrLogger'.
logger:warn( ... )
Feeds log output through the action function defined for 'warn' messages.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. ...
Data to be printed, of any type; tostring() is called on all values.
logger:warnf( format, ... )
Feeds log output through the action function defined for 'warn' messages, using string.format to prepare the output.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. format
(string) formatting instructions (see Lua's string.format for details)
2. ...
Arguments to string.format required by format string