=begin pod

=NAME    Log
=VERSION 0.3.1
=AUTHOR  Patrick Spek <p.spek@tyil.nl>

=head1 Description

An interface for logging mechanisms in the Raku programming language to adhere
to. L<RFC5424|https://tools.ietf.org/html/rfc5424> 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
C<Log::Implementation> role.

	use Log::Implementation;

	unit class Log::Custom is Log::Implementation {
		…
	}

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

Throughout your library, you can use any of the 8 methods that a C<Log>
implementation must support:

=item C<emergency>
=item C<alert>
=item C<critical>
=item C<error>
=item C<warning>
=item C<notice>
=item C<info>
=item C<debug>

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::instance;

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::instance> variable, the C<Log> module doesn't set it to anything.

	$Log::instance = Log::Simple.new;

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::instance.add-output($*ERR);

You can specify a minimum log level for each output, and optionally a Callable
to act as filter.

	$Log::instance.add-output($*ERR, Log::Level::Debug, filter => sub (%payload) {
		%payload<message> ~~ /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<them>.

=head5 C<RAKU_LOG_CLASS>

When set, the class name defined in this environment variable must be used to
populate the C<$Log::instance> variable. This can be implemented using a
C<require> statement and use of the I<defined-or> operator.

	$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::instance.add-output($*ERR, %*ENV<RAKU_LOG_LEVEL> // Log::Level::Info);

=head1 Installation

Install this module through L<zef|https://github.com/ugexe/zef>:

=begin code :lang<sh>
zef install Log
=end code

=head1 Documentation

Documentation is written as L<Pod6|https://docs.raku.org/language/pod>
documents, and can be read with the
L<C<p6doc>|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<C<App::Rakuman>|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