First round of dead file removal

obsolete/breakpad/common/mac/GTMLogger.h

-//
-//  GTMLogger.h
-//
-//  Copyright 2007-2008 Google Inc.
-//
-//  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.
-//
-
-// Key Abstractions
-// ----------------
-// 
-// This file declares multiple classes and protocols that are used by the 
-// GTMLogger logging system. The 4 main abstractions used in this file are the
-// following:
-//
-//   * logger (GTMLogger) - The main logging class that users interact with. It
-//   has methods for logging at different levels and uses a log writer, a log
-//   formatter, and a log filter to get the job done.
-// 
-//   * log writer (GTMLogWriter) - Writes a given string to some log file, where
-//   a "log file" can be a physical file on disk, a POST over HTTP to some URL,
-//   or even some in-memory structure (e.g., a ring buffer).
-//
-//   * log formatter (GTMLogFormatter) - Given a format string and arguments as
-//   a va_list, returns a single formatted NSString. A "formatted string" could
-//   be a string with the date prepended, a string with values in a CSV format,
-//   or even a string of XML.
-//
-//   * log filter (GTMLogFilter) - Given a formatted log message as an NSString
-//   and the level at which the message is to be logged, this class will decide
-//   whether the given message should be logged or not. This is a flexible way
-//   to filter out messages logged at a certain level, messages that contain
-//   certain text, or filter nothing out at all. This gives the caller the
-//   flexibility to dynamically enable debug logging in Release builds.
-//
-// This file also declares some classes to handle the common log writer, log
-// formatter, and log filter cases. Callers can also create their own writers, 
-// formatters, and filters and they can even build them on top of the ones
-// declared here. Keep in mind that your custom writer/formatter/filter may be
-// called from multiple threads, so it must be thread-safe.
-
-#import <Foundation/Foundation.h>
-#import "GTMDefines.h"
-
-// Predeclaration of used protocols that are declared later in this file.
-@protocol GTMLogWriter, GTMLogFormatter, GTMLogFilter;
-
-#if MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_5
-#define CHECK_FORMAT_NSSTRING(a, b) __attribute__((format(__NSString__, a, b)))
-#else
-#define CHECK_FORMAT_NSSTRING(a, b)
-#endif
-
-// GTMLogger
-//
-// GTMLogger is the primary user-facing class for an object-oriented logging
-// system. It is built on the concept of log formatters (GTMLogFormatter), log
-// writers (GTMLogWriter), and log filters (GTMLogFilter). When a message is
-// sent to a GTMLogger to log a message, the message is formatted using the log
-// formatter, then the log filter is consulted to see if the message should be
-// logged, and if so, the message is sent to the log writer to be written out.
-// 
-// GTMLogger is intended to be a flexible and thread-safe logging solution. Its
-// flexibility comes from the fact that GTMLogger instances can be customized
-// with user defined formatters, filters, and writers. And these writers,
-// filters, and formatters can be combined, stacked, and customized in arbitrary
-// ways to suit the needs at hand. For example, multiple writers can be used at
-// the same time, and a GTMLogger instance can even be used as another
-// GTMLogger's writer. This allows for arbitrarily deep logging trees.
-// 
-// A standard GTMLogger uses a writer that sends messages to standard out, a
-// formatter that smacks a timestamp and a few other bits of interesting
-// information on the message, and a filter that filters out debug messages from
-// release builds. Using the standard log settings, a log message will look like
-// the following:
-//
-//   2007-12-30 10:29:24.177 myapp[4588/0xa07d0f60] [lvl=1] foo=<Foo: 0x123>
-// 
-// The output contains the date and time of the log message, the name of the
-// process followed by its process ID/thread ID, the log level at which the
-// message was logged (in the previous example the level was 1:
-// kGTMLoggerLevelDebug), and finally, the user-specified log message itself (in
-// this case, the log message was @"foo=%@", foo).
-// 
-// Multiple instances of GTMLogger can be created, each configured their own
-// way.  Though GTMLogger is not a singleton (in the GoF sense), it does provide
-// access to a shared (i.e., globally accessible) GTMLogger instance. This makes
-// it convenient for all code in a process to use the same GTMLogger instance.
-// The shared GTMLogger instance can also be configured in an arbitrary, and
-// these configuration changes will affect all code that logs through the shared
-// instance.
-
-//
-// Log Levels
-// ----------
-// GTMLogger has 3 different log levels: Debug, Info, and Error. GTMLogger
-// doesn't take any special action based on the log level; it simply forwards
-// this information on to formatters, filters, and writers, each of which may
-// optionally take action based on the level. Since log level filtering is
-// performed at runtime, log messages are typically not filtered out at compile
-// time.  The exception to this rule is that calls to the GTMLoggerDebug() macro
-// *ARE* filtered out of non-DEBUG builds. This is to be backwards compatible
-// with behavior that many developers are currently used to. Note that this
-// means that GTMLoggerDebug(@"hi") will be compiled out of Release builds, but
-// [[GTMLogger sharedLogger] logDebug:@"hi"] will NOT be compiled out.
-// 
-// Standard loggers are created with the GTMLogLevelFilter log filter, which
-// filters out certain log messages based on log level, and some other settings.
-// 
-// In addition to the -logDebug:, -logInfo:, and -logError: methods defined on
-// GTMLogger itself, there are also C macros that make usage of the shared
-// GTMLogger instance very convenient. These macros are:
-//
-//   GTMLoggerDebug(...)
-//   GTMLoggerInfo(...)
-//   GTMLoggerError(...)
-//
-// Again, a notable feature of these macros is that GTMLogDebug() calls *will be
-// compiled out of non-DEBUG builds*.
-//
-// Standard Loggers
-// ----------------
-// GTMLogger has the concept of "standard loggers". A standard logger is simply
-// a logger that is pre-configured with some standard/common writer, formatter,
-// and filter combination. Standard loggers are created using the creation
-// methods beginning with "standard". The alternative to a standard logger is a
-// regular logger, which will send messages to stdout, with no special
-// formatting, and no filtering.
-//
-// How do I use GTMLogger?
-// ----------------------
-// The typical way you will want to use GTMLogger is to simply use the
-// GTMLogger*() macros for logging from code. That way we can easily make
-// changes to the GTMLogger class and simply update the macros accordingly. Only
-// your application startup code (perhaps, somewhere in main()) should use the
-// GTMLogger class directly in order to configure the shared logger, which all
-// of the code using the macros will be using. Again, this is just the typical
-// situation.
-// 
-// To be complete, there are cases where you may want to use GTMLogger directly,
-// or even create separate GTMLogger instances for some reason. That's fine,
-// too.
-//
-// Examples
-// --------
-// The following show some common GTMLogger use cases.
-//
-// 1. You want to log something as simply as possible. Also, this call will only
-//    appear in debug builds. In non-DEBUG builds it will be completely removed.
-//
-//      GTMLoggerDebug(@"foo = %@", foo);
-//
-// 2. The previous example is similar to the following. The major difference is 
-//    that the previous call (example 1) will be compiled out of Release builds
-//    but this statement will not be compiled out.
-//
-//      [[GTMLogger sharedLogger] logDebug:@"foo = %@", foo];
-//
-// 3. Send all logging output from the shared logger to a file. We do this by
-//    creating an NSFileHandle for writing associated with a file, and setting 
-//    that file handle as the logger's writer.
-//
-//      NSFileHandle *f = [NSFileHandle fileHandleForWritingAtPath:@"/tmp/f.log"
-//                                                          create:YES];
-//      [[GTMLogger sharedLogger] setWriter:f];
-//      GTMLoggerError(@"hi");  // This will be sent to /tmp/f.log
-//
-// 4. Create a new GTMLogger that will log to a file. This example differs from
-//    the previous one because here we create a new GTMLogger that is different
-//    from the shared logger.
-//
-//      GTMLogger *logger = [GTMLogger standardLoggerWithPath:@"/tmp/temp.log"];
-//      [logger logInfo:@"hi temp log file"];
-//
-// 5. Create a logger that writes to stdout and does NOT do any formatting to
-//    the log message. This might be useful, for example, when writing a help
-//    screen for a command-line tool to standard output.
-//      
-//      GTMLogger *logger = [GTMLogger logger];
-//      [logger logInfo:@"%@ version 0.1 usage", progName];
-//
-// 6. Send log output to stdout AND to a log file. The trick here is that 
-//    NSArrays function as composite log writers, which means when an array is 
-//    set as the log writer, it forwards all logging messages to all of its
-//    contained GTMLogWriters.
-//
-//      // Create array of GTMLogWriters
-//      NSArray *writers = [NSArray arrayWithObjects:
-//          [NSFileHandle fileHandleForWritingAtPath:@"/tmp/f.log" create:YES],
-//          [NSFileHandle fileHandleWithStandardOutput], nil];
-//      
-//      GTMLogger *logger = [GTMLogger standardLogger];
-//      [logger setWriter:writers];
-//      [logger logInfo:@"hi"];  // Output goes to stdout and /tmp/f.log
-//
-// For futher details on log writers, formatters, and filters, see the
-// documentation below.
-//
-// NOTE: GTMLogger is application level logging.  By default it does nothing
-// with _GTMDevLog/_GTMDevAssert (see GTMDefines.h).  An application can choose
-// to bridge _GTMDevLog/_GTMDevAssert to GTMLogger by providing macro
-// definitions in its prefix header (see GTMDefines.h for how one would do
-// that).
-//
-@interface GTMLogger : NSObject {
- @private
-  id<GTMLogWriter> writer_;
-  id<GTMLogFormatter> formatter_;
-  id<GTMLogFilter> filter_;
-}
-
-//
-// Accessors for the shared logger instance
-//
-
-// Returns a shared/global standard GTMLogger instance. Callers should typically
-// use this method to get a GTMLogger instance, unless they explicitly want
-// their own instance to configure for their own needs. This is the only method
-// that returns a shared instance; all the rest return new GTMLogger instances.
-+ (id)sharedLogger;
-
-// Sets the shared logger instance to |logger|. Future calls to +sharedLogger
-// will return |logger| instead.
-+ (void)setSharedLogger:(GTMLogger *)logger;
-
-//
-// Creation methods
-//
-
-// Returns a new autoreleased GTMLogger instance that will log to stdout, using
-// the GTMLogStandardFormatter, and the GTMLogLevelFilter filter.
-+ (id)standardLogger;
-
-// Same as +standardLogger, but logs to stderr.
-+ (id)standardLoggerWithStderr;
-
-// Returns a new standard GTMLogger instance with a log writer that will
-// write to the file at |path|, and will use the GTMLogStandardFormatter and
-// GTMLogLevelFilter classes. If |path| does not exist, it will be created.
-+ (id)standardLoggerWithPath:(NSString *)path;
-
-// Returns an autoreleased GTMLogger instance that will use the specified
-// |writer|, |formatter|, and |filter|.
-+ (id)loggerWithWriter:(id<GTMLogWriter>)writer
-             formatter:(id<GTMLogFormatter>)formatter
-                filter:(id<GTMLogFilter>)filter;
-
-// Returns an autoreleased GTMLogger instance that logs to stdout, with the
-// basic formatter, and no filter. The returned logger differs from the logger
-// returned by +standardLogger because this one does not do any filtering and
-// does not do any special log formatting; this is the difference between a
-// "regular" logger and a "standard" logger.
-+ (id)logger;
-
-// Designated initializer. This method returns a GTMLogger initialized with the
-// specified |writer|, |formatter|, and |filter|. See the setter methods below
-// for what values will be used if nil is passed for a parameter.
-- (id)initWithWriter:(id<GTMLogWriter>)writer
-           formatter:(id<GTMLogFormatter>)formatter
-              filter:(id<GTMLogFilter>)filter;
-
-//
-// Logging  methods
-//
-
-// Logs a message at the debug level (kGTMLoggerLevelDebug).
-- (void)logDebug:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
-// Logs a message at the info level (kGTMLoggerLevelInfo).
-- (void)logInfo:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
-// Logs a message at the error level (kGTMLoggerLevelError).
-- (void)logError:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
-// Logs a message at the assert level (kGTMLoggerLevelAssert).
-- (void)logAssert:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
-
-
-//
-// Accessors
-//
-
-// Accessor methods for the log writer. If the log writer is set to nil,  
-// [NSFileHandle fileHandleWithStandardOutput] is used.
-- (id<GTMLogWriter>)writer;
-- (void)setWriter:(id<GTMLogWriter>)writer;
-
-// Accessor methods for the log formatter. If the log formatter is set to nil,
-// GTMLogBasicFormatter is used. This formatter will format log messages in a
-// plain printf style.
-- (id<GTMLogFormatter>)formatter;
-- (void)setFormatter:(id<GTMLogFormatter>)formatter;
-
-// Accessor methods for the log filter. If the log filter is set to nil,
-// GTMLogNoFilter is used, which allows all log messages through.
-- (id<GTMLogFilter>)filter;
-- (void)setFilter:(id<GTMLogFilter>)filter;
-
-@end  // GTMLogger
-
-
-// Helper functions that are used by the convenience GTMLogger*() macros that 
-// enable the logging of function names.
-@interface GTMLogger (GTMLoggerMacroHelpers)
-- (void)logFuncDebug:(const char *)func msg:(NSString *)fmt, ...
-  CHECK_FORMAT_NSSTRING(2, 3);
-- (void)logFuncInfo:(const char *)func msg:(NSString *)fmt, ...
-  CHECK_FORMAT_NSSTRING(2, 3);
-- (void)logFuncError:(const char *)func msg:(NSString *)fmt, ...
-  CHECK_FORMAT_NSSTRING(2, 3);
-- (void)logFuncAssert:(const char *)func msg:(NSString *)fmt, ...
-  CHECK_FORMAT_NSSTRING(2, 3);
-@end  // GTMLoggerMacroHelpers
-
-
-// Convenience macros that log to the shared GTMLogger instance. These macros
-// are how users should typically log to GTMLogger. Notice that GTMLoggerDebug()
-// calls will be compiled out of non-Debug builds.
-#define GTMLoggerDebug(...)  \
-  [[GTMLogger sharedLogger] logFuncDebug:__func__ msg:__VA_ARGS__]
-#define GTMLoggerInfo(...)   \
-  [[GTMLogger sharedLogger] logFuncInfo:__func__ msg:__VA_ARGS__]
-#define GTMLoggerError(...)  \
-  [[GTMLogger sharedLogger] logFuncError:__func__ msg:__VA_ARGS__]
-#define GTMLoggerAssert(...) \
-  [[GTMLogger sharedLogger] logFuncAssert:__func__ msg:__VA_ARGS__]
-
-// If we're not in a debug build, remove the GTMLoggerDebug statements. This
-// makes calls to GTMLoggerDebug "compile out" of Release builds
-#ifndef DEBUG
-#undef GTMLoggerDebug
-#define GTMLoggerDebug(...) do {} while(0)
-#endif
-
-// Log levels.
-typedef enum {
-  kGTMLoggerLevelUnknown,
-  kGTMLoggerLevelDebug,
-  kGTMLoggerLevelInfo,
-  kGTMLoggerLevelError,
-  kGTMLoggerLevelAssert,
-} GTMLoggerLevel;
-
-
-//
-//   Log Writers
-//
-
-// Protocol to be implemented by a GTMLogWriter instance.
-@protocol GTMLogWriter <NSObject>
-// Writes the given log message to where the log writer is configured to write.
-- (void)logMessage:(NSString *)msg level:(GTMLoggerLevel)level;
-@end  // GTMLogWriter
-
-
-// Simple category on NSFileHandle that makes NSFileHandles valid log writers.
-// This is convenient because something like, say, +fileHandleWithStandardError
-// now becomes a valid log writer. Log messages are written to the file handle
-// with a newline appended.
-@interface NSFileHandle (GTMFileHandleLogWriter) <GTMLogWriter>
-// Opens the file at |path| in append mode, and creates the file with |mode| 
-// if it didn't previously exist.
-+ (id)fileHandleForLoggingAtPath:(NSString *)path mode:(mode_t)mode;
-@end  // NSFileHandle
-
-
-// This category makes NSArray a GTMLogWriter that can be composed of other
-// GTMLogWriters. This is the classic Composite GoF design pattern. When the
-// GTMLogWriter -logMessage:level: message is sent to the array, the array
-// forwards the message to all of its elements that implement the GTMLogWriter
-// protocol.
-//
-// This is useful in situations where you would like to send log output to
-// multiple log writers at the same time. Simply create an NSArray of the log
-// writers you wish to use, then set the array as the "writer" for your 
-// GTMLogger instance.
-@interface NSArray (GTMArrayCompositeLogWriter) <GTMLogWriter>
-@end  // GTMArrayCompositeLogWriter
-
-
-// This category adapts the GTMLogger interface so that it can be used as a log
-// writer; it's an "adapter" in the GoF Adapter pattern sense.
-//
-// This is useful when you want to configure a logger to log to a specific
-// writer with a specific formatter and/or filter. But you want to also compose
-// that with a different log writer that may have its own formatter and/or 
-// filter.
-@interface GTMLogger (GTMLoggerLogWriter) <GTMLogWriter>
-@end  // GTMLoggerLogWriter
-
-
-//
-//   Log Formatters
-//
-
-// Protocol to be implemented by a GTMLogFormatter instance.
-@protocol GTMLogFormatter <NSObject>
-// Returns a formatted string using the format specified in |fmt| and the va
-// args specified in |args|.
-- (NSString *)stringForFunc:(NSString *)func
-                 withFormat:(NSString *)fmt
-                     valist:(va_list)args
-                      level:(GTMLoggerLevel)level;
-@end  // GTMLogFormatter
-
-
-// A basic log formatter that formats a string the same way that NSLog (or 
-// printf) would. It does not do anything fancy, nor does it add any data of its
-// own.
-@interface GTMLogBasicFormatter : NSObject <GTMLogFormatter>
-@end  // GTMLogBasicFormatter
-
-
-// A log formatter that formats the log string like the basic formatter, but
-// also prepends a timestamp and some basic process info to the message, as
-// shown in the following sample output.
-//   2007-12-30 10:29:24.177 myapp[4588/0xa07d0f60] [lvl=1] log mesage here
-@interface GTMLogStandardFormatter : GTMLogBasicFormatter {
- @private
-  NSDateFormatter *dateFormatter_;  // yyyy-MM-dd HH:mm:ss.SSS
-  NSString *pname_;
-  pid_t pid_;
-}
-@end  // GTMLogStandardFormatter
-
-
-//
-//   Log Filters
-//
-
-// Protocol to be imlemented by a GTMLogFilter instance.
-@protocol GTMLogFilter <NSObject>
-// Returns YES if |msg| at |level| should be filtered out; NO otherwise.
-- (BOOL)filterAllowsMessage:(NSString *)msg level:(GTMLoggerLevel)level;
-@end  // GTMLogFilter
-
-
-// A log filter that filters messages at the kGTMLoggerLevelDebug level out of
-// non-debug builds. Messages at the kGTMLoggerLevelInfo level are also filtered
-// out of non-debug builds unless GTMVerboseLogging is set in the environment or
-// the processes's defaults. Messages at the kGTMLoggerLevelError level are
-// never filtered.
-@interface GTMLogLevelFilter : NSObject <GTMLogFilter>
-@end  // GTMLogLevelFilter
-
-
-// A simple log filter that does NOT filter anything out;
-// -filterAllowsMessage:level will always return YES. This can be a convenient
-// way to enable debug-level logging in release builds (if you so desire).
-@interface GTMLogNoFilter : NSObject <GTMLogFilter>
-@end  // GTMLogNoFilter