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 --- META6.json | 4 ++-- README.rakudoc | 47 ++++++++++++++++++++++-------------------- lib/Log.rakumod | 26 ++++++++--------------- lib/Log/Implementation.rakumod | 4 ++-- lib/Log/Level.rakumod | 2 +- 5 files changed, 39 insertions(+), 44 deletions(-) diff --git a/META6.json b/META6.json index 40f7068..419ba10 100644 --- a/META6.json +++ b/META6.json @@ -14,5 +14,5 @@ "Log::Level": "lib/Log/Level.rakumod" }, "source-url": "https://home.tyil.nl/git/raku/Log/", - "version": "0.3.0" -} \ No newline at end of file + "version": "0.3.1" +} 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 diff --git a/lib/Log.rakumod b/lib/Log.rakumod index 9a9004e..790d517 100644 --- a/lib/Log.rakumod +++ b/lib/Log.rakumod @@ -12,7 +12,7 @@ our $instance; =begin pod =NAME Log -=VERSION 0.3.0 +=VERSION 0.3.1 =AUTHOR Patrick Spek =head1 Description @@ -30,17 +30,17 @@ C, C, or C. The C role itself only helps in ensuring the interfaces are the same, allowing easy replacement of the implementation if ever needed in the future. -Whatever imlementation of C you use, it C be set in the C<$*LOG> -dynamic variable. This makes it available to all the libraries that are used in -the program. You C set it as early as possible. +Whatever implementation of C you use, it C be set in the +C<$Log::instance> variable. This makes it available to all the libraries that +are used in the program. You C set it as early as possible. -Because it must be using the C<$*LOG> variable, module developers around the -ecosystem can rely on it for their logging needs. However, not every +Because it must be using the C<$Log::instance> variable, module developers +around the ecosystem can rely on it for their logging needs. However, not every application will implement this, and that needs to be accounted for, too. For this, make use of Raku's C flow control statement. =begin code :lang -.notice('This is a log message') with $*LOG; +.notice('This is a log message') with $Log::instance; =end code This can be used freely and safely, throughout all modules. Any application @@ -59,25 +59,17 @@ unit class Log::Custom is Log; =head3 Methods -There are 8 log levels, each with two method calls to invoke them. All of these -I be implemented. +There are 8 log levels, each represented by a method calls to invoke them. All +of these I be implemented. =item C -=item C =item C -=item C =item C -=item C =item C -=item C =item C -=item C =item C =item C -=item C -=item C =item C -=item C Additionally, the following configuration method I be implemented. diff --git a/lib/Log/Implementation.rakumod b/lib/Log/Implementation.rakumod index 65f2513..4d1d637 100644 --- a/lib/Log/Implementation.rakumod +++ b/lib/Log/Implementation.rakumod @@ -32,8 +32,8 @@ multi method add-output (IO::Handle:D $, Int() $ where Log::Level::Emergency ≤ =begin pod -=NAME Log::Abstract -=VERSION 0.3.0 +=NAME Log::Implementation +=VERSION 0.3.1 =AUTHOR Patrick Spek =begin LICENSE diff --git a/lib/Log/Level.rakumod b/lib/Log/Level.rakumod index 4c9618a..0f1a51a 100644 --- a/lib/Log/Level.rakumod +++ b/lib/Log/Level.rakumod @@ -16,7 +16,7 @@ enum Log::Level < =begin pod =NAME Log::Level -=VERSION 0.3.0 +=VERSION 0.3.8 =AUTHOR Patrick Spek =head1 Description -- cgit v1.1