/ 
Log-Funlog-0.8.0.1
River stage zero No dependents
/ Log::Funlog

NAME

Log::Funlog - Log module with fun inside!

SYNOPSIS

use Log::Funlog;
*my_sub=Log::Funlog->new(
	parameter => value,
	...
);

my_sub(priority,string,string, ... );

DESCRIPTION

This is a Perl module intended ton manage the logs you want to do from your Perl scripts.

It should be easy to use, and provide all the functions you should want.

Just initialise the module, then use is as if it was an ordinary function!

When you want to log something, just write:

your-sub-log(priority,"what"," I ","wanna log")

then the module will analyse if the priority if higher enough (seeing verbose option). If it is, your log will be written with the format you decided.

Funlog.pm may export an 'error' function: it logs your message with a priority of 1 and with an specific (parametrable) string. You can use it when you want to highlight error messages in your logs.

Parameters are: header, error_header, cosmetic, verbose, file, daemon, fun and caller

verbose is mandatory.

NOTE NOTE NOTE: Interface (header) is subject to change!

MANDATORIES OPTION

verbose

Should be of the form 'n/m', where n<m.

n is the wanted verbosity of your script, m if the maximum verbosity of your script.

Everything that is logged with a priority more than nwill not be logged.

0 if you do not want anything to be printed (??? what for ???)

The common way to define n is to take it from the command line with Getopt:

 use Getopt::Long;
 use Log::Funlog;
 &GetOptions("verbose",\$verbose);
 *Log=Log::Funlog(
	[...]
	verbose => "$verbose/5",
	[...]
	)

This option is backward compatible with 0.7.x.x versions.

NON MANDATORIES OPTIONS

Pattern specifying the header of your logs.

The fields are made like this: %<letter><delimiter1><delimiter2><same_letter>

The letter is, for now:

s: stack of the calling sub
d: date
p: name of the prog
l: verbosity level

delimiter is what you want, but MUST BE one character long (replacement regexp is s/\%<letter>(.?)(.?)<letter>/$1<field>$2/ ). delimiter1 will be put before the field once expanded, delimiter2 after.

Example: '%dd %p::p %l[]l %s{}s ' should produce something like:

Wed Sep 22 18:50:34 2004 :gna.pl: [x    ] {sub1} Something happened

If no header is specified, no header will be written, and you would have:

Something happened

NOTE NOTE NOTE: The fields are subject to change!

daemon

1 if the script should be a daemon. (default is 0: not a daemon)

When daemon=1, Log::Funlog write to file instead of STDERR

If you specify daemon, you must specify file

The common way to do is the same that with verbose: with Getopt

file

File to write logs to.

MUST be specified if you specify daemon

1 if you want the current date being printed in the logs.

The date is printed like: Thu Aug 14 13:56:56 2003

cosmetic

An alphanumeric char to indicate the log level in your logs.

There will be as many as these chars as the log level of the string being logged. See EXAMPLE

Should be something like 'x', or '*', or '!', but actually no test are performed to verify that there is only one caracter...

error_header

Header you want to see in the logs when you call the error function.

Default is '## Oops! ##'.

fun

Probs of fun in your logs.

Should be: 0<fun<=100

See the sources of Log::Funlog if you want to change the sentences

caller 1 if you want the name of the subroutine which is logging.

'all' if you want the stack of subs

Of course, nothing will happen if no header is specified, nor %s in the header ...

EXAMPLE

Here is an example with almost all of the options enabled:

 $ vi gna.pl
 #!/usr/bin/perl -w
 use Log::Funlog qw( error );
 *Log=Log::Funlog->new(
		file => "zou.log",		#name of the file
		verbose => "3/5",			#verbose 3 out of 5
		daemon => 0,			#I am not a daemon
		cosmetic => 'x',		#crosses for the level
		fun => 10,			#10% of fun (que je passe autour de moi)
		error_header => 'Groumpf... ',  #Header for true errors
		header => '%d [ %p ] [ %l ] ',	#The header
		caller => 1);			#and I want the name of the last sub

 Log(1,"I'm logged...");
 Log(3,"Me too...");
 Log(4,"Me not!");          #because 4>verbose
 sub ze_sub {
	$hop=1;
	Log(1,"One","two",$hop,"C"."++");
	error("oups!");
 }
 ze_sub;
 error("Zut");
 
 :wq
 
 $ ./gna.pl
 Wed Sep 22 18:50:34 2004 [ gna.pl ] [ x     ] I'm logged...
 Wed Sep 22 18:50:34 2004 [ gna.pl ] [ xxx   ] Me too...
 Wed Sep 22 18:50:34 2004 [ gna.pl ] [ x     ] Onetwo1C++
 Wed Sep 22 18:50:34 2004 [ gna.pl ] [ x     ] Groumpf...  oups!
 Wed Sep 22 18:50:34 2004 [ gna.pl ] [ x     ] Groumpf...  Zut

BUGS

Hopefully none :)

DISCUSSION

As you can see, the 'new' routine return a pointer to a sub. It's the easiest way I found to make this package as easy as possible to use.

I guess that calling the sub each time you want to log something (and even if it won't print anything due to the too low level of the priority given) is not really fast...

Especially if you look at the code, and you see all the stuffs the module do before printing something.

But in fact, I tried to make it rather fast, that mean that if the module try to know as fast as possible if it will write something.

If you want a really fast routine of log, please propose me a way to do it, or do it yourself, or do not log :)

HISTORY

I'm doing quite a lot of Perl scripts, and I wanted the scripts talk to me. So I searched a log routine.

As I didn't found it on the web, and I wanted something more 'personnal' than syslog (I didn't want my script write to syslog), I started to write a very little routine, that I copied to all the scripts I made.

As I copied this routine, I added some stuff to match my needs; I wanted something rather fast, easy to use, easy to understand (even for me :P ), quite smart and ... a little bit funny :)

The I wrote this module, that I 'use Log::Funlog' in each of my scripts.

CHANGELOG

See Changelog

AUTHOR

Gabriel Guillon

korsani@free.fr

LICENCE

GPL

Let me know if you have added some features, or removed some bugs ;)