=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