__END__
=pod

=head1 NAME

Log::Any::Adapter::Development -- Manual for developing new Log::Any adapters

=head1 VERSION

version 0.10

=head1 SYNOPSIS

The adapter module:

   package Log::Any::Adapter::YAL;
   use strict;
   use warnings;
   use Log::Any::Adapter::Util qw(make_method);
   use base qw(Log::Any::Adapter::Base);
   
   # Optionally initialize object
   #
   sub init {
       my ($self) = @_;

       $self->{attr} = ...;
   }
   
   # Create logging methods: debug, info, etc.
   #
   foreach my $method ( Log::Any->logging_methods() ) {
       make_method($method, sub { ... });
   }
   
   # Create detection methods: is_debug, is_info, etc.
   #
   foreach my $method ( Log::Any->detection_methods() ) {
       make_method($method, sub { ... });
   }

and the application:

   Log::Any->set_adapter('YAL');

=head1 DESCRIPTION

This document describes how to implement a new Log::Any adapter.

The easiest way to start is to look at the source of existing adapters, such as
L<Log::Any::Adapter::Log4perl|Log::Any::Adapter::Log4perl> and
L<Log::Any::Adapter::Dispatch|Log::Any::Adapter::Dispatch>.

=head1 NAMING

If you are going to publicly release your adapter, call it
'Log::Any::Adapter::I<something>' so that users can use it with

    Log::Any->set_adapter(I<something>);

If it's an internal driver, you can call it whatever you like and use it like

    Log::Any->set_adapter('+My::Log::Adapter');

=head1 BASE CLASS

All adapters must directly or indirectly inherit from
L<Log::Any::Adapter::Base|Log::Any::Adapter::Base>.

=head1 METHODS

=head2 Constructor

The constructor (C<new>) is provided by
L<Log::Any::Adapter::Base|Log::Any::Adapter::Base>. It will:

=over

=item *

place any adapter arguments into a hash, along with the category

=item *

bless the hash into your subclass

=item *

call L</init> which may be optionally provided by your subclass

=back

At this point, overriding the default constructor is not supported. Hopefully
it will not be needed.

The constructor is called whenever a log object is requested. e.g. If the
application initializes Log::Any like so:

    Log::Any->set_adapter('Log::YAL', yal_object => $yal, depth => 3);

and then a class requests a logger like so:

    package Foo;
    use Log::Any qw($log);

Then C<$log> will be populated with the return value of:

    Log::Any::Adapter::Yal->new(yal_object => $yal, depth => 3, category => 'Foo');

This is memoized, so if the same category should be requested again (e.g.
through a separate C<get_logger> call, the same object will be returned.
Therefore, you should try to avoid anything non-deterministic in your L</init>
function.

=head2 Required methods

The following methods have no default implementation, and MUST be defined by
your subclass:

=over

=item debug ($msg)

=item info ($msg)

=item notice ($msg)

=item warning ($msg)

=item error ($msg)

=item critical ($msg)

=item alert ($msg)

=item emergency ($msg)

These methods log a message at the specified level.

To help generate these methods programmatically, you can get a list of the sub
names with #__METHOD

    Log::Any->logging_methods

=item is_debug ()

=item is_info ()

=item is_notice ()

=item is_warning ()

=item is_error ()

=item is_critical ()

=item is_alert ()

=item is_emergency ()

These methods return a boolean indicating whether the specified level is
active.

To help generate these methods programmatically, you can get a list of the sub
names with #__METHOD

    Log::Any->detection_methods

=back

=head2 Optional methods

The following methods have no default implementation but MAY be provided by
your subclass:

=over

=item init ()

This is called after the adapter object is created and blessed into your class.
It will be a hash containing the parameters that were passed to new(). Perform
any necessary validation or initialization here.

=back

=head2 Support methods

The following methods are useful for defining adapters:

=over

=item delegate_method_to_slot ($slot, $method, $adapter_method)

Handle the specified $method by calling $adapter_method on the object contained
in $self->{$slot}.

See L<Log::Any::Adapter::Dispatch|Log::Any::Adapter::Dispatch> and
L<Log::Any::Adapter::Log4perl|Log::Any::Adapter::Log4perl> for examples of
usage.

=item Log::Any->logging_methods

Returns a list of logging methods: debug, info, etc.

=item Log::Any->detection_methods

Returns a list of detection methods: is_debug, is_info, etc.

=item Log::Any->logging_and_detection_methods

Returns a combined list of logging and detection methods.

=back

=head1 SEE ALSO

L<Log::Any>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut