diff options
Diffstat (limited to 'README.rakudoc')
| -rw-r--r-- | README.rakudoc | 47 |
1 files changed, 25 insertions, 22 deletions
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 <p.spek@tyil.nl> =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<Log::Implementation> 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<Log> exports an C<our> level C<$instance> variable. +This should be set in the main application, and used (preferably using C<with>) +in modules. =head3 For library developers @@ -44,33 +47,33 @@ implementation must support: =item C<info> =item C<debug> -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<Log> 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<with> 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<Log> 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<Log> 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<Log> should work. +your application. However, the application must also set up the +C<$Log::instance> variable, the C<Log> 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<IO::Handle> objects. -To send all logging to C<STDERR>, add C<$*ERR> as output. +You should probably also add one or more outputs. These must be C<IO::Handle> +objects. To send all logging to C<STDERR>, 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<message> ~~ /Foo/ # Only send messages containing "Foo" }); @@ -82,17 +85,17 @@ to allow the user to customize the logging into what works for I<them>. =head5 C<RAKU_LOG_CLASS> 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<require> -statement and use of the I<defined-or> operator. +populate the C<$Log::instance> variable. This can be implemented using a +C<require> statement and use of the I<defined-or> operator. - $*LOG = (require ::(%*ENV<RAKU_LOG_CLASS> // 'Log::Simple')).new; + $Log::instance = (require ::(%*ENV<RAKU_LOG_CLASS> // 'Log::Simple')).new; =head5 C<RAKU_LOG_LEVEL> When set, this should override the log level used in the application. This is easily implemented using the I<defined-or> operator in your code. - $*LOG.add-output($*ERR, %*ENV<RAKU_LOG_LEVEL> // Log::Level::Info); + $Log::instance.add-output($*ERR, %*ENV<RAKU_LOG_LEVEL> // Log::Level::Info); =head1 Installation |