From c59d3dff38e26eee0c4eedb653b38e745b150ba5 Mon Sep 17 00:00:00 2001 From: Patrick Spek Date: Wed, 15 Jul 2020 14:04:01 +0200 Subject: Update documentation to use $Log::instance --- README.rakudoc | 47 +++++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 22 deletions(-) (limited to 'README.rakudoc') diff --git a/README.rakudoc b/README.rakudoc index f446d83..0b26c52 100644 --- a/README.rakudoc +++ b/README.rakudoc @@ -1,7 +1,7 @@ =begin pod =NAME Log -=VERSION 0.0.0 +=VERSION 0.3.1 =AUTHOR Patrick Spek =head1 Description @@ -20,15 +20,18 @@ application. =head2 Usage -Any class that wants to handle logging in Raku can implement the Log interface. +Any class that wants to handle logging in Raku can implement the +C role. - use Log; + use Log::Implementation; - unit class Log::Custom is Log { + unit class Log::Custom is Log::Implementation { … } -To do the actual logging, the C<$*LOG> dynamic variable is to be used. +To do the actual logging, C exports an C level C<$instance> variable. +This should be set in the main application, and used (preferably using C) +in modules. =head3 For library developers @@ -44,33 +47,33 @@ implementation must support: =item C =item C -There's no guarantee that C<$*LOG> is populated, since developers may not -implement it for any number of reasons. Luckily, Raku has a terse way to work +There's no guarantee that C is implemented in an application, for any +reason of the application's developer. Luckily, Raku has a terse way to work with this reality, using the C control flow statement. - .info('This is an informational message') with $*LOG; + .info('This is an informational message') with $Log::instance; -If C<$*LOG> is defined, C<.info> will be called on it. Otherwise, this -statement is skipped altogether. This allows application developers to decide -if they want any logging, and which implementation to use of the C class. +If C<$Log::instance> is defined, C<.info> will be called on it. Otherwise, this +statement is skipped. This allows application developers to decide if they want +any logging, and which C implementation to use. =head3 For application developers Much like library developers, you can use the same methods to add logging to -your application. However, the application must also set up the C<$*LOG> -variable. Any implementation of C should work. +your application. However, the application must also set up the +C<$Log::instance> variable, the C module doesn't set it to anything. - my $*LOG = Log::Simple.new; + $Log::instance = Log::Simple.new; -You should also add one or more outputs. These must be C objects. -To send all logging to C, add C<$*ERR> as output. +You should probably also add one or more outputs. These must be C +objects. To send all logging to C, add C<$*ERR> as output. - $*LOG.add-output($*ERR); + $Log::instance.add-output($*ERR); You can specify a minimum log level for each output, and optionally a Callable to act as filter. - $*LOG.add-output($*ERR, Log::Level::Debug, filter => sub (%payload) { + $Log::instance.add-output($*ERR, Log::Level::Debug, filter => sub (%payload) { %payload ~~ /Foo/ # Only send messages containing "Foo" }); @@ -82,17 +85,17 @@ to allow the user to customize the logging into what works for I. =head5 C When set, the class name defined in this environment variable must be used to -populate the C<$*LOG> variable. This can be implemented using a C -statement and use of the I operator. +populate the C<$Log::instance> variable. This can be implemented using a +C statement and use of the I operator. - $*LOG = (require ::(%*ENV // 'Log::Simple')).new; + $Log::instance = (require ::(%*ENV // 'Log::Simple')).new; =head5 C When set, this should override the log level used in the application. This is easily implemented using the I operator in your code. - $*LOG.add-output($*ERR, %*ENV // Log::Level::Info); + $Log::instance.add-output($*ERR, %*ENV // Log::Level::Info); =head1 Installation -- cgit v1.1