Seeking feedback on an API for a logging object.
Seeking feedback on an API for a logging object.
- Subject: Seeking feedback on an API for a logging object.
- From: James Quick <email@hidden>
- Date: Fri, 18 Jul 2003 13:42:45 -0400
I am designing on an object to provide, logging services.
These services will include:
Basic logging to a FileHandle,
Routing messages
Filtering messages
Providing target/action callback services to interested objects.
The logging object be a core component of a development tool framework.
Users of the framework, and other classes within the framework, will be
using
this object quite frequently. For this reason, I am interested in
providing a
very spare interface to it's functionality. I find that code used for
code verification,
including logging, debugging, and assertions, should be as transparent
as possible.
By transparent I mean both that the primitives are simple to use and
clear in function,
and that the syntax is simple and unobtrusive.
If the syntax is verbose, the developer has to read more text and
ignore some of it.
As in most other situations where information overload is a problem,
creating a
situation where selective inattention is encouraged is a bad idea. In
this context, the
less text present the better, so one can understand the intention more
readily even
when skimming the source quickly. Also, I believe that the most
commonly used form
should not have varying syntax. The syntax should cover all common
uses so that the
user does not have to remember, and use, a number of different method
signatures
depending on context.
Anyway, although the underlying interface to the logging object will be
exported,
and document, I think (for the above reasons) that a very spare syntax
for logging
statements should be the most common. My draft of this syntax is
implemented
by a method with a variable argument list led by an NSString. It looks
like:
- (void) log: (NSString *) messageFormat, ...;
The logging subsystem will most often be called with a 'reason' string
used for
classifying the purpose (or purposes) of a message. This reason string
may contain
tags from a predefined list in the framework, or user defined tags. A
dictionary
available to both the user and the logger will drive regex based
pattern matching to
determine what events are currently of interest to the user and what
actions to take
(remember it's more then just a logfile writer).
Since I consider a terse, easily readable format beneficial, my first
draft uses the first two
characters of a string to denote special handing by the log: method.
The initial character
"!" denotes that this string is a modifier token, not the stringFormat.
The two character
sequence "!:" denotes a reason token. The common interface to logging
is thus:
[logger log: @"!:TestClass,dealloc,Debug", @"Entering dealloc for
instance %lx", ];
[logger log: @"!:Foo,Verification,Notice", @"Foo instance variable
anInt = '%d'", x];
[logger log: @"!:TODO,MileStone.Panther", @"add support for getting baz
from a container."];
[logger pushreason: @"!:TestFoo.InstanceVars,VerboseNotice"];
[logger log: @"fooCount: %d", fooCount];
[logger log: @"fooPercent: %.2g", fooPercent];
oldReason = [logger popReason];
The user could also invoke:
- (void) log: (NSString *) reason message: (NSString *) messageFormat,
...;
- (void) logv: (NSString *) reason message: (NSString *) format args:
(va_list) argList;
Since this is highly subjective, and currently I have only my own
preference as a guide,
I would love to get some feedback on this.
Do you prefer the concise or the verbose syntax?
Do you think that reserving "!:" to denote a sequence of tags is both
clear and pretty?
I welcome any comments, criticism, or suggestions on an alternate
syntax.
p.s. I previously considers using a subclass of NSString to identify
reason tokens,
along with a macro for syntactic sugar like
[log: reason(@"Greeting"), @"hello %s", [name UTF8String]];
The additional layer of syntax was intrusive, when crafting reasons on
the fly.
Thanks for your time.
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.