From 8b3b434aaf1b4dc52f1278dac52d83de70b029df Mon Sep 17 00:00:00 2001
From: Patrick Spek
Date: Mon, 20 Apr 2020 10:53:22 +0200
Subject: Initial commit
---
README.rakudoc | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 126 insertions(+)
create mode 100644 README.rakudoc
(limited to 'README.rakudoc')
diff --git a/README.rakudoc b/README.rakudoc
new file mode 100644
index 0000000..f446d83
--- /dev/null
+++ b/README.rakudoc
@@ -0,0 +1,126 @@
+=begin pod
+
+=NAME Log
+=VERSION 0.0.0
+=AUTHOR Patrick Spek
+
+=head1 Description
+
+An interface for logging mechanisms in the Raku programming language to adhere
+to. L has been used as a reference
+point to decide which levels to support, and what naming conventions to use.
+
+=head2 Intention
+
+This module has been created to serve as an interface to which logging
+mechanisms in Raku can adhere. A standardized interface for handling logging
+will make it easier for all projects to get started with logging, while
+allowing application handlers to adjust all logging to suit their current
+application.
+
+=head2 Usage
+
+Any class that wants to handle logging in Raku can implement the Log interface.
+
+ use Log;
+
+ unit class Log::Custom is Log {
+ …
+ }
+
+To do the actual logging, the C<$*LOG> dynamic variable is to be used.
+
+=head3 For library developers
+
+Throughout your library, you can use any of the 8 methods that a C
+implementation must support:
+
+=item C
+=item C
+=item C
+=item C
+=item C
+=item C
+=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
+with this reality, using the C control flow statement.
+
+ .info('This is an informational message') with $*LOG;
+
+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.
+
+=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.
+
+ my $*LOG = 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.
+
+ $*LOG.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) {
+ %payload ~~ /Foo/ # Only send messages containing "Foo"
+ });
+
+=head4 Environment variables
+
+There are some environment variables that must be honored. These are intended
+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.
+
+ $*LOG = (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);
+
+=head1 Installation
+
+Install this module through L:
+
+=begin code :lang
+zef install Log
+=end code
+
+=head1 Documentation
+
+Documentation is written as L
+documents, and can be read with the
+L|https://modules.raku.org/dist/p6doc:github:perl6> module.
+
+=begin input
+p6doc Log
+=end input
+
+At your option, you can also use prettier readers, such as
+L|https://modules.raku.org/dist/App::Rakuman:cpan:TYIL>.
+
+=begin input
+rakuman Log
+=end input
+
+=head1 License
+
+This module is distributed under the terms of the LGPL-3.0-only.
+
+=end pod
--
cgit v1.1