Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Message(3)	      User Contributed Perl Documentation      Log::Message(3)

NAME
       Log::Message - A	generic	message	storing	mechanism;

SYNOPSIS
	   use Log::Message private => 0, config => '/our/cf_file';

	   my $log = Log::Message->new(	   private => 1,
					   level   => 'log',
					   config  => '/my/cf_file',
				      );

	   $log->store('this is	my first message');

	   $log->store(	   message => 'message #2',
			   tag	   => 'MY_TAG',
			   level   => 'carp',
			   extra   => ['this is	an argument to the handler'],
		      );

	   my @last_five_items = $log->retrieve(5);

	   my @items = $log->retrieve( tag     => qr/my_tag/i,
				       message => qr/\d/,
				       remove  => 1,
				     );

	   my @items = $log->final( level => qr/carp/, amount => 2 );

	   my $first_error = $log->first()

	   # croak with	the last error on the stack
	   $log->final->croak;

	   # empty the stack
	   $log->flush();

DESCRIPTION
       Log::Message is a generic message storage mechanism.  It	allows you to
       store messages on a stack -- either shared or private --	and assign
       meta-data to it.	 Some meta-data	will automatically be added for	you,
       like a timestamp	and a stack trace, but some can	be filled in by	the
       user, like a tag	by which to identify it	or group it, and a level at
       which to	handle the message (for	example, log it, or die	with it)

       Log::Message also provides a powerful way of searching through items by
       regexes on messages, tags and level.

Hierarchy
       There are 4 modules of interest when dealing with the Log::Message::*
       modules:

       Log::Message
	   Log::Message	provides a few methods to manipulate the stack it
	   keeps.  It has the option of	keeping	either a private or a public
	   stack.  More	on this	below.

       Log::Message::Item
	   These are individual	message	items, which are objects that contain
	   the user message as well as the meta-data described above.  See the
	   Log::Message::Item manpage to see how to extract this meta-data and
	   how to work with the	Item objects.  You should never	need to	create
	   your	own Item objects, but knowing about their methods and
	   accessors is	important if you want to write your own	handlers. (See
	   below)

       Log::Message::Handlers
	   These are a collection of handlers that will	be called for a	level
	   that	is used	on a Log::Message::Item	object.	 For example, if a
	   message is logged with the 'carp' level, the	'carp' handler from
	   Log::Message::Handlers will be called.  See the
	   Log::Message::Handlers manpage for more explanation about how
	   handlers work, which	one are	available and how to create your own.

       Log::Message::Config
	   Per Log::Message object, there is a configuration required that
	   will	fill in	defaults if the	user did not specify arguments to
	   override them (like for example what	tag will be set	if none	was
	   provided), Log::Message::Config handles the creation	of these
	   configurations.

	   Configuration can be	specified in 4 ways:

	   o   As a configuration file when you	"use Log::Message"

	   o   As arguments when you "use Log::Message"

	   o   As a configuration file when you	create a new Log::Message
	       object.	(The config will then only apply to that object	if you
	       marked it as private)

	   o   As arguments when you create a new Log::Message object.

	       You should never	need to	use the	Log::Message::Config module
	       yourself, as this is transparently done by Log::Message,	but
	       its manpage does	provide	an explanation of how you can create a
	       config file.

Options
       When using Log::Message,	or creating a new Log::Message object, you can
       supply various options to alter its behaviour.  Of course, there	are
       sensible	defaults should	you choose to omit these options.

       Below an	explanation of all the options and how they work.

       config
	   The path to a configuration file to be read.	 See the manpage of
	   Log::Message::Config	for the	required format

	   These options will be overridden by any explicit arguments passed.

       private
	   Whether to create, by default, private or shared objects.  If you
	   choose to create shared objects, all	Log::Message objects will use
	   the same stack.

	   This	means that even	though every module may	make its own $log
	   object they will still be sharing the same error stack on which
	   they	are putting errors and from which they are retrieving.

	   This	can be useful in big projects.

	   If you choose to create a private object, then the stack will of
	   course be private to	this object, but it will still fall back to
	   the shared config should no private config or overriding arguments
	   be provided.

       verbose
	   Log::Message	makes use of another module to validate	its arguments,
	   which is called Params::Check, which	is a lightweight, yet powerful
	   input checker and parser. (See the Params::Check manpage for
	   details).

	   The verbose setting will control whether this module	will generate
	   warnings if something improper is passed as input, or merely
	   silently returns undef, at which point Log::Message will generate a
	   warning.

	   It's	best to	just leave this	at its default value, which is '1'

       tag The tag to add to messages if none was provided. If neither your
	   config, nor any specific arguments supply a tag, then Log::Message
	   will	set it to 'NONE'

	   Tags	are useful for searching on or grouping	by. For	example, you
	   could tag all the messages you want to go to	the user as 'USER
	   ERROR' and all those	that are only debug information	with 'DEBUG'.

	   At the end of your program, you could then print all	the ones
	   tagged 'USER	ERROR' to STDOUT, and those marked 'DEBUG' to a	log
	   file.

       level
	   "level" describes what action to take when a	message	is logged.
	   Just	like "tag", Log::Message will provide a	default	(which is
	   'log') if neither your config file, nor any explicit	arguments are
	   given to override it.

	   See the Log::Message::Handlers manpage to see what handlers are
	   available by	default	and what they do, as well as to	how to add
	   your	own handlers.

       remove
	   This	indicates whether or not to automatically remove the messages
	   from	the stack when you've retrieved	them.  The default setting
	   provided by Log::Message is '0': do not remove.

       chrono
	   This	indicates whether messages should always be fetched in
	   chronological order or not.	This simply means that you can choose
	   whether, when retrieving items, the item most recently added	should
	   be returned first, or the one that had been added most long ago.

	   The default is to return the	newest ones first

Methods
   new
       This creates a new Log::Message object; The parameters it takes are
       described in the	"Options" section below	and let	it just	be repeated
       that you	can use	these options like this:

	   my $log = Log::Message->new(	%options );

       as well as during "use" time, like this:

	   use Log::Message option1 => value, option2 => value

       There are but 3 rules to	keep in	mind:

       o   Provided arguments take precedence over a configuration file.

       o   Arguments to	new take precedence over options provided at "use"
	   time

       o   An object marked private will always	have an	empty stack to begin
	   with

   store
       This will create	a new Item object and store it on the stack.

       Possible	arguments you can give to it are:

       message
	   This	is the only argument that is required. If no other arguments
	   are given, you may even leave off the "message" key.	The argument
	   will	then automatically be assumed to be the	message.

       tag The tag to add to this message. If not provided, Log::Message will
	   look	in your	configuration for one.

       level
	   The level at	which this message should be handled. If not provided,
	   Log::Message	will look in your configuration	for one.

       extra
	   This	is an array ref	with arguments passed to the handler for this
	   message, when it is called from store();

	   The handler will receive them as a normal list

       store() will return true	upon success and undef upon failure, as	well
       as issue	a warning as to	why it failed.

   retrieve
       This will retrieve all message items matching the criteria specified
       from the	stack.

       Here are	the criteria you can discriminate on:

       tag A regex to which the	tag must adhere. For example "qr/\w/".

       level
	   A regex to which the	level must adhere.

       message
	   A regex to which the	message	must adhere.

       amount
	   Maximum amount of errors to return

       chrono
	   Return in chronological order, or not?

       remove
	   Remove items	from the stack upon retrieval?

       In scalar context it will return	the first item matching	your criteria
       and in list context, it will return all of them.

       If an error occurs while	retrieving, a warning will be issued and undef
       will be returned.

   first
       This is a shortcut for retrieving the first item(s) stored on the
       stack. It will default to only retrieving one if	called with no
       arguments, and will always return results in chronological order.

       If you only supply one argument,	it is assumed to be the	amount you
       wish returned.

       Furthermore, it can take	the same arguments as "retrieve" can.

   last
       This is a shortcut for retrieving the last item(s) stored on the	stack.
       It will default to only retrieving one if called	with no	arguments, and
       will always return results in reverse chronological order.

       If you only supply one argument,	it is assumed to be the	amount you
       wish returned.

       Furthermore, it can take	the same arguments as "retrieve" can.

   flush
       This removes all	items from the stack and returns them to the caller

SEE ALSO
       Log::Message::Item, Log::Message::Handlers, Log::Message::Config

AUTHOR
       This module by Jos Boumans <kane@cpan.org>.

Acknowledgements
       Thanks to Ann Barcomb for her suggestions.

COPYRIGHT
       This module is copyright	(c) 2002 Jos Boumans <kane@cpan.org>.  All
       rights reserved.

       This library is free software; you may redistribute and/or modify it
       under the same terms as Perl itself.

perl v5.24.1			  2013-04-25		       Log::Message(3)

NAME | SYNOPSIS | DESCRIPTION | Hierarchy | Options | Methods | SEE ALSO | AUTHOR | Acknowledgements | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Message&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help