Documentation: how to use ARTClientOptions.logHandler

[ben-xD]

Could we document how to set a custom log handler in the README?

In Ably Java, I just have to implement the Log interface:

public interface LogHandler {
        void println(int severity, String tag, String msg, Throwable tr);
    }

In Ably-Cocoa:
The interface of ARTLog is

ably-cocoa/Source/ARTLog.h

Lines 31 to 41 in 24f7c2d

	@interface ARTLog (Shorthand)
	- (void)verbose:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2);
	- (void)verbose:(const char *)fileName line:(NSUInteger)line message:(NSString *)message, ... NS_FORMAT_FUNCTION(3,4);
	- (void)debug:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2);
	- (void)debug:(const char *)fileName line:(NSUInteger)line message:(NSString *)message, ... NS_FORMAT_FUNCTION(3,4);
	- (void)info:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2);
	- (void)warn:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2);
	- (void)error:(NSString *)format, ... NS_FORMAT_FUNCTION(1,2);
	@end

And the implementation of this interface is

ably-cocoa/Source/ARTLog.m

Lines 64 to 222 in 24f7c2d

	@implementation ARTLog {
	NSMutableArray<ARTLogLine *> *_captured;
	NSMutableArray<ARTLogLine *> *_history;
	NSUInteger _historyLines;
	dispatch_queue_t _queue;
	}
	- (instancetype)init {
	return [self initCapturingOutput:true];
	}
	- (instancetype)initCapturingOutput:(BOOL)capturing {
	return [self initCapturingOutput:true historyLines:100];
	}
	- (instancetype)initCapturingOutput:(BOOL)capturing historyLines:(NSUInteger)historyLines {
	if (self = [super init]) {
	// Default
	self->_logLevel = ARTLogLevelWarn;
	if (capturing) {
	self->_captured = [[NSMutableArray alloc] init];
	}
	_history = [[NSMutableArray alloc] init];
	_historyLines = historyLines;
	_queue = dispatch_queue_create("io.ably.log", DISPATCH_QUEUE_SERIAL);
	}
	return self;
	}
	- (void)log:(NSString *const)message withLevel:(const ARTLogLevel)level {
	dispatch_sync(_queue, ^{
	ARTLogLine *logLine = [[ARTLogLine alloc] initWithDate:[NSDate date] level:level message:message];
	if (level >= self.logLevel) {
	NSLog(@"%@", [logLine toString]);
	if (self->_captured) {
	[self->_captured addObject:logLine];
	}
	}
	if (self->_historyLines > 0) {
	[self->_history insertObject:logLine atIndex:0];
	if (self->_history.count > self->_historyLines) {
	[self->_history removeLastObject];
	}
	}
	});
	}
	- (void)logWithError:(ARTErrorInfo *)error {
	[self log:error.message withLevel:ARTLogLevelError];
	}
	- (NSArray<ARTLogLine *> *)history {
	return _history;
	}
	- (NSArray *)captured {
	if (!_captured) {
	[ARTException raise:NSInternalInconsistencyException format:@"tried to get captured output in non-capturing instance; use initCapturingOutput:true if you want captured output."];
	}
	return _captured;
	}
	- (ARTLog *)verboseMode {
	self.logLevel = ARTLogLevelVerbose;
	return self;
	}
	- (ARTLog *)debugMode {
	self.logLevel = ARTLogLevelDebug;
	return self;
	}
	- (ARTLog *)warnMode {
	self.logLevel = ARTLogLevelWarn;
	return self;
	}
	- (ARTLog *)infoMode {
	self.logLevel = ARTLogLevelInfo;
	return self;
	}
	- (ARTLog *)errorMode {
	self.logLevel = ARTLogLevelError;
	return self;
	}
	- (void)verbose:(NSString *)format, ... {
	if (self.logLevel <= ARTLogLevelVerbose) {
	va_list args;
	va_start(args, format);
	[self log:[[NSString alloc] initWithFormat:format arguments:args]
	withLevel:ARTLogLevelVerbose];
	va_end(args);
	}
	}
	- (void)verbose:(const char *)fileName line:(NSUInteger)line message:(NSString *)message, ... {
	if (self.logLevel <= ARTLogLevelVerbose) {
	va_list args;
	va_start(args, message);
	[self log:[[NSString alloc] initWithFormat:[NSString stringWithFormat:@"(%@:%lu) %@", [[NSString stringWithUTF8String:fileName] lastPathComponent], (unsigned long)line, message] arguments:args]
	withLevel:ARTLogLevelVerbose];
	va_end(args);
	}
	}
	- (void)debug:(NSString *)format, ... {
	if (self.logLevel <= ARTLogLevelDebug) {
	va_list args;
	va_start(args, format);
	[self log:[[NSString alloc] initWithFormat:format arguments:args]
	withLevel:ARTLogLevelDebug];
	va_end(args);
	}
	}
	- (void)debug:(const char *)fileName line:(NSUInteger)line message:(NSString *)message, ... {
	if (self.logLevel <= ARTLogLevelDebug) {
	va_list args;
	va_start(args, message);
	[self log:[[NSString alloc] initWithFormat:[NSString stringWithFormat:@"(%@:%lu) %@", [[NSString stringWithUTF8String:fileName] lastPathComponent], (unsigned long)line, message] arguments:args]
	withLevel:ARTLogLevelDebug];
	va_end(args);
	}
	}
	- (void)info:(NSString *)format, ... {
	if (self.logLevel <= ARTLogLevelInfo) {
	va_list args;
	va_start(args, format);
	[self log:[[NSString alloc] initWithFormat:format arguments:args]
	withLevel:ARTLogLevelInfo];
	va_end(args);
	}
	}
	- (void)warn:(NSString *)format, ... {
	if (self.logLevel <= ARTLogLevelWarn) {
	va_list args;
	va_start(args, format);
	[self log:[[NSString alloc] initWithFormat:format arguments:args]
	withLevel:ARTLogLevelWarn];
	va_end(args);
	}
	}
	- (void)error:(NSString *)format, ... {
	if (self.logLevel <= ARTLogLevelError) {
	va_list args;
	va_start(args, format);
	[self log:[[NSString alloc] initWithFormat:format arguments:args]
	withLevel:ARTLogLevelError];
	va_end(args);
	}
	}
	@end

┆Issue is synchronized with this Jira Story by Unito