/ 
Log-ger-Manual-0.010
River stage one • 1 direct dependent • 1 total dependent
/ Log::ger::Manual::Internals

NAME

Log::ger::Manual::Internals - Log::ger internals

VERSION

version 0.010

DESCRIPTION

When an importer package does this:

use Log::ger;

Basically all Log::ger does is construct logging routines and install them to importer's package (target), e.g. log_warn, log_debug, log_is_debug and so on. Log::ger also records the target name. When a reinit is requested (e.g. due to a change of log level or outputs), Log::ger will again construct logging routines and install them to each target, replacing the old routines.

In addition to installing routines to a package, Log::ger can also target a hash or an object (which is basically the same as installing to a package, but the routines will expect to be called as object methods instead of plain subroutines, i.e. they expect the first argument to be the object).

GLOSSARY

Formatter

A routine that takes arguments supplied by the user to the logger routine (e.g. log_warn("blah", $args, ...) and converts it to the message (usually string) that is sent to the output (or the layouter, if there is one).

Output

Log routine

Is routine

Layouter

A routine that takes the formatted message (usually a string) and converts it to the final message string that is sent to output.

Plugin

A Perl module that supplies hooks.

Target

Phase

Hook

Hook priority

Init

The process of constructing logger routines and installing them to targets.

Logger routine

Level

Composite output

Category

Category level

HOOKS AND PLUGINS

Hooks are how Log::ger provides its flexibility. At various times (phases), Log::ger will turn to running hooks to get some behavior or result. For example when wanting to construct a logging routine or formatting routine or before/after installing logging routines. Plugins, which are modules in the Log::ger::{Plugin,Output,Format,Filter,...} namespaces, can supply these hooks.

Hooks are stored in the %Global_Hooks variable, where the key is phase name and the value an array of hook records. Each hook record is in the form of:

[$key, $prio, $coderef]

where $key is (plugin) package name, $prio is a number between 0-100 (the lower the number, the higher the priority and the earlier it is run), $coderef is the actual hook routine. A plugin is supposed to put only at most one hook per phase.

A hook routine is passed a hash argument and is expected to return an array:

[$result, $flow_control]

By default each hook will be executed in order of its priority. $flow_control can be set to 1 by a hook to stop immediately after this hook instead of continuing to the next. Some phases will nevertheless stop after the first hook that returns non-undef $result. A hook that returns undef is effectively declining and causing Log::ger to move to the next hook in the chain.

Aguments received by hook: target (str, can be package if installing to a package, or hash or object), target_arg (str, when target is package, will be the package name; when target is hash will be the hash; when target is object will be the object's package), init_args (hash, arguments passed to Log::ger when importing, e.g. {category => 'My::Package'}; it also serves as a per-target stash which survives reinit, by convention you can put stuffs here under keys that start with _). In some phases, hook will receive more arguments (see phase documentation below).

Available phases:

  • create_formatter

  • create_routine_names

    Used to construct routine names. Hook must return this:

    [{
  log_subs    => [ [NAME, STR_LEVEL], ... ],
  is_subs     => [ [NAME, STR_LEVEL], ... ],
  log_methods => [ [NAME, STR_LEVEL], ... ],
  is_methods  => [ [NAME, STR_LEVEL], ... ],
}]

  • create_log_routine

    Used to create "log_level" routines. Run for each level. Extra arguments received by hook: level (numeric level), str_level.

  • create_is_routine

    Used to create "log_is_level" routines. Run for each level. Extra Arguments received by hooks: level (numeric level), str_level.

  • before_install_routines

    Extra arguments received by hooks: routines which is in the form of:

    [
  [$coderef, $name, $level, $flags],
  ...
]

    where $flags has this bits: 1 is set if routine is a "log_LEVEL" routine instead of a "log_is_LEVEL" routine, 2 is set if routine is expected to be called as a method instead of a subroutine.

  • after_install_routines

    Extra arguments received by hooks: routines.

Aside from the global hooks, there are also per-target hooks, which are stored in %Per_Package_Hooks, %Per_Hash_Hooks, %Per_Object_Hooks.

TARGETS

Log::ger can install logger routines to a package, or an object (which is similar to installing to a package), or a hash (usually for testing).

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by perlancar@cpan.org.

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