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