Implementing std.log

[Jose Armando Garcia]

std.logging is still alive! After posting my first attempt at a
logging module I went back and spent a lot of time on how I could
improve the API. I would like to say that Andrei's std.log module had
a great influence on the final outcome. There are some aspect of
std.log's API that I really like. E.g. the ability to do fine grain
compile time configuration. I'll go into detail in a subsequent review
of std.log.

I also think that having competing logging module is a good thing.
This process will result in a better module for phobos and as a result
a better module for the user.

The best way to see what has changed is to look at the source code
(https://github.com/jsancio/phobos/blob/master/std/logging.d) and the
generated doc (http://jsancio.github.com/phobos/phobos/std_logging.html).
Here are some highlights:

1) I tried to minimize the amount of code the compiler has to generate
because of template. Template are only used when the module has/wants
to make compiled time decision. If you spot places where templates are
not needed please tell me.

2) Make logging decision as early as possible. Logging can be short
circuited by either the severity level, the verbose level or an user
defined condition. All those conditions are evaluated as soon as
possible and only when required. E.g. the module doesn't evaluate user
define condition if it already knows that it wont log because of the
severity.

3) A module should do one thing an do it well. This module does
logging so unlike std.log and glog it doesn't have built in mechanism
for doing 'every', 'when', 'first', etc. Instead the log and vlog
function provide a lazily evaluated bool parameter that the user can
use to perform condition logging. There are plenty of example of this
in the doc.

At the top of the doc I provided an example similar to std.log's
synopsis so you can compare the two APIs.

Disclaimer: This is a draft. Once we agree on the main API (log and
vlog). I will go back an finish the implementation, test and
documentation.

Enjoy! Let me know if you have any suggestions,
-Jose

On Wed, May 18, 2011 at 6:05 AM, Jacob Carlborg <doob at me.com> wrote:
> On 2011-05-17 22:15, Andrei Alexandrescu wrote:
>>
>> On 5/17/11 4:02 AM, Jacob Carlborg wrote:
>>>
>>> On 2011-05-16 02:05, Andrei Alexandrescu wrote:
>>>>
>>>> Thanks for your work.
>>>>
>>>> I think there's an important distinction to be made. There are two
>>>> "API"s being discussed. One is the client interface and the other is the
>>>> extensibility interface.
>>>>
>>>> Jose looked into both: he provided a client interface that has
>>>> formatting, levels, enabling, and such, and an extensibility interface
>>>> that essentially is a simple output stream.
>>>>
>>>> My library explores the client interface and leaves the extensibility
>>>> interface as an obvious piece of work that needs little agreement and
>>>> minimal design effort.
>>>>
>>>> Finally, your library keeps the client interface to a minimum and
>>>> focuses almost exclusively on the extensibility interface. In doing so,
>>>> it makes few choices that I disagree with. Allow me to share some
>>>> specific feedback.
>>>
>>> Note that my suggestion was just a simple and incomplete suggestion on
>>> how the API could look like. I only provided "info", "warning" and
>>> "error" methods as examples, I'm not saying the API should only have
>>> these three levels.
>>
>> [snip]
>>
>> I thought about this some more and I understand I sounded unfair. There
>> is a lot of merit and there are a lot of good ideas in your code (and of
>> course Jose's), which I didn't mention for the simple but cold reason
>> that negative feedback is more informative. But neglecting the merits is
>> a mistake as well. I'll incorporate some of the ideas you suggested in
>> the next pass through std.log.
>>
>>
>> Thanks,
>>
>> Andrei
>
> No hard feelings, I also have a tendency to just give negative feedback.
>
> --
> /Jacob Carlborg
>