aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPatrick Spek <p.spek@tyil.nl>2020-07-15 14:04:01 +0200
committerPatrick Spek <p.spek@tyil.nl>2020-07-15 14:04:01 +0200
commitc59d3dff38e26eee0c4eedb653b38e745b150ba5 (patch)
tree4d515c61bc2efee0d647cacff365188a4ad44945
parent086d7f4d351fdb3ad46dbab1c47d49d7f97d5741 (diff)
Update documentation to use $Log::instanceHEADv0.3.1master
-rw-r--r--META6.json4
-rw-r--r--README.rakudoc47
-rw-r--r--lib/Log.rakumod26
-rw-r--r--lib/Log/Implementation.rakumod4
-rw-r--r--lib/Log/Level.rakumod2
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 <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
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 <p.spek@tyil.nl>
=head1 Description
@@ -30,17 +30,17 @@ C<Log::Simple>, C<Log::Colored>, or C<Log::JSON>. The C<Log> 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<Log> you use, it C<must> be set in the C<$*LOG>
-dynamic variable. This makes it available to all the libraries that are used in
-the program. You C<should> set it as early as possible.
+Whatever implementation of C<Log> you use, it C<must> be set in the
+C<$Log::instance> variable. This makes it available to all the libraries that
+are used in the program. You C<should> 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<with> flow control statement.
=begin code :lang<raku>
-.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<must> be implemented.
+There are 8 log levels, each represented by a method calls to invoke them. All
+of these I<must> be implemented.
=item C<multi method emergency (Str:D $) { * }>
-=item C<multi method emergency (Str:D $, *@) { * }>
=item C<multi method alert (Str:D $) { * }>
-=item C<multi method alert (Str:D $, *@) { * }>
=item C<multi method critical (Str:D $) { * }>
-=item C<multi method critical (Str:D $, *@) { * }>
=item C<multi method error (Str:D $) { * }>
-=item C<multi method error (Str:D $, *@) { * }>
=item C<multi method warning (Str:D $) { * }>
-=item C<multi method warning (Str:D $, *@) { * }>
=item C<multi method notice (Str:D $) { * }>
=item C<multi method info (Str:D $) { * }>
-=item C<multi method info (Str:D $, *@) { * }>
-=item C<multi method notice (Str:D $, *@) { * }>
=item C<multi method debug (Str:D $0 { * }>
-=item C<multi method debug (Str:D $, *@) { * }>
Additionally, the following configuration method I<must> 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 <p.spek@tyil.nl>
=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 <p.spek@tyil.nl>
=head1 Description