This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Locale/PGetText, Next: Locale/PO, Prev: Locale/Msgcat, Up: Module List pure perl i18n routines *********************** NAME ==== PGetText - pure perl i18n routines SYNOPSIS ======== use Locale::PGetText; Locale::PGetText::setLocaleDir('/usr/local/perl/locale'); Locale::PGetText::setLanguage('ru-koi8r'); print gettext("Welcome!"), "\n"; DESCRIPTION =========== PGetText provides the same functionality as GNU gettext does, but it is written in pure perl and doesn't require any system locale stuff. *setLocaleDir()* sets directory where messages database is stored (there are no default and no domains). *setLanguage()* switches languages. *gettext()* retrieves message in local language corresponding to given message. SEE ALSO ======== MsgFormat(1) AUTHOR ====== Mike Shoyher ,  File: pm.info, Node: Locale/PO, Next: Locale/SubCountry, Prev: Locale/PGetText, Up: Module List Perl module for manipulating .po entries from GNU gettext ********************************************************* NAME ==== Locale::PO - Perl module for manipulating .po entries from GNU gettext SYNOPSIS ======== use Locale::PO; $po = new Locale::PO([-option=>value,...]) [$string =] $po->msgid([new string]); [$string =] $po->msgstr([new string]); [$string =] $po->comment([new string]); [$string =] $po->automatic([new string]); [$string =] $po->reference([new string]); [$value =] $po->fuzzy([value]); [$value =] $po->c_format([value]); print $po->dump; $quoted_string = $po->quote($string); $string = $po->dequote($quoted_string); $aref = Locale::PO->load_file_asarray(); $href = Locale::PO->load_file_ashash(); Locale::PO->save_file_fromarray(,$aref); Locale::PO->save_file_fromhash(,$href); DESCRIPTION =========== This module simplifies management of GNU gettext .po files and is an alternative to using emacs po-mode. It provides an object-oriented interface in which each entry in a .po file is a Locale::PO object. METHODS ======= new Create a new Locale::PO object to represent a po entry. You can optionally set the attributes of the entry by passing a list/hash of the form: -option=>value, -option=>value, etc. Where options are msgid, msgstr, comment, automatic, reference, fuzzy, and c-format. See accessor methods below. msgid Set or get the untranslated string from the object. msgstr Set or get the translated string from the object. comment Set or get translator comments from the object. automatic Set or get automatic comments from the object (inserted by emacs po-mode or xgettext). reference Set or get reference marking comments from the object (inserted by emacs po-mode or gettext). fuzzy Set or get the fuzzy flag on the object ("check this translation"). When setting, use 1 to turn on fuzzy, and 0 to turn it off. c_format Set or get the c-format or no-c-format flag on the object. This can take 3 values: 1 implies c-format, 0 implies no-c-format, and blank or undefined implies neither. dump Returns the entry as a string, suitable for output to a po file. quote Applies po quotation rules to a string, and returns the quoted string. The quoted string will have all existing double-quote characters escaped by backslashes, and will be enclosed in double quotes. dequote Returns a quoted po string to its natural form. load_file_asarray Given the filename of a po-file, reads the file and returns a reference to a list of Locale::PO objects corresponding to the contents of the file, in the same order. load_file_ashash Given the filename of a po-file, reads the file and returns a reference to a hash of Locale::PO objects corresponding to the contents of the file. The hash keys are the untranslated strings, so this is a cheap way to remove duplicates. The method will prefer to keep entries that have been translated. save_file_fromarray Given a filename and a reference to a list of Locale::PO objects, saves those objects to the file, creating a po-file. save_file_fromhash Given a filename and a reference to a hash of Locale::PO objects, saves those objects to the file, creating a po-file. The entries are sorted alphabetically by untranslated string. AUTHOR ====== Alan Schwartz, alansz@pennmush.org BUGS ==== If you load_file then save_file, the output file may have slight cosmetic differences from the input file (an extra blank line here or there). SEE ALSO ======== xgettext(1).  File: pm.info, Node: Locale/SubCountry, Next: Locale/gettext, Prev: Locale/PO, Up: Module List convert state, province, county etc. names to/from code ******************************************************* NAME ==== Locale::SubCountry - convert state, province, county etc. names to/from code SYNOPSIS ======== use Locale::SubCountry; $UK_counties = new Locale::SubCountry('GB'); print($UK_counties->full_name('DUMGAL')); # Dumfries & Galloway $country = 'AUSTRALIA'; @all_countries = &all_country_names; if ( grep(/$country/, @all_countries) ) { $australia = new Locale::SubCountry($country); } else { die "No data for $country"; } print($australia->code('New South Wales ')); # NSW print($australia->full_name('S.A.')); # South Australia $upper_case = 1; print($australia->full_name('Qld',$upper_case)); # QUEENSLAND print $australia->country; # AUSTRALIA print $australia->country_code; # AU print $australia->sub_country_type; # State @all_country_codes = &all_country_codes; %all_australian_states = $australia->full_name_code_hash; foreach $abbrev ( sort keys %australian_states ) { printf("%-3s : %s\n",$abbrev,%all_australian_states{$abbrev}); } %all_australian_codes = $australia->code_full_name_hash; @all_australian_states = $australia->all_full_names; @all_australian_codes = $australia->all_codes; REQUIRES ======== Perl 5.005 or above DESCRIPTION =========== This module allows you to convert the full name for a countries administrative region to the code commonly used for postal addressing. The reverse lookup can also be done. Sub countries are termed as states in the US and Australia, provinces in Canada and counties in the UK and Ireland. Additionally, names and codes for all sub countries in a country can be returned as either a hash or an array. METHODS ======= new --- The new method creates an instance of a sub country object. This must be called before any of the following methods are invoked. The method takes a single argument, the name of the country that contains the sub country that you want to work with. It may be specified either by the ISO 3166 two letter code or the full name. These are currently: AF - AFGHANISTAN DZ - ALGERIA AO - ANGOLA AR - ARGENTINA AM - ARMENIA AU - AUSTRALIA AT - AUSTRIA AZ - AZERBAIJAN BS - BAHAMAS BH - BAHRAIN BD - BANGLADESH BY - BELARUS BE - BELGIUM BZ - BELIZE BJ - BENIN BT - BHUTAN BO - BOLIVIA BA - BOSNIA AND HERZEGOVINA BW - BOTSWANA BR - BRAZIL BN - BRUNEI DARUSSALAM BG - BULGARIA BF - BURKINA FASO KH - CAMBODIA CM - CAMEROON CA - CANADA CV - CAPE VERDE CF - CENTRAL AFRICAN REPUBLIC TD - CHAD CL - CHILE CN - CHINA CO - COLOMBIA KM - COMOROS CO - CONGO CR - COSTA RICA CI - COTE D'IVOIRE HR - CROATIA CU - CUBA CY - CYPRUS CX - CZECH REPUBLIC CO - DEMOCRATIC REPUBLIC OF CONGO DK - DENMARK DJ - DJIBOUTI DO - DOMINICAN REPUBLIC EC - ECUADOR EG - EGYPT SV - EL SALVADOR QQ - EQUATORIAL GUINEA ER - ERITREA EE - ESTONIA ET - ETHIOPIA FJ - FIJI FR - FRANCE GA - GABON GM - GAMBIA GE - GEORGIA DE - GERMANY GH - GHANA GR - GREECE GT - GUATEMALA GN - GUINEA GW - GUINEA BISSAU GY - GUYANA HT - HAITI HN - HONDURAS HU - HUNGARY IE - ICELAND IN - INDIA ID - INDONESIA IN - IRAN (ISLAMIC REPUBLIC OF) IQ - IRAQ IE - IRELAND IT - ITALY JM - JAMAICA JP - JAPAN JO - JORDAN KZ - KAZAKHSTAN KE - KENYA KI - KIRIBATI KP - KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KR - KOREA, REPUBLIC OF KW - KUWAIT KG - KYRGYZSTAN LA - LAO PEOPLE'S DEMOCRATIC REPUBLIC LV - LATVIA LB - LEBANON LS - LESOTHO LR - LIBERIA LY - LIBYAN ARAB JAMAHIRIYA LT - LITHUANIA MG - MADAGASCAR MW - MALAWI MY - MALAYSIA MV - MALDIVES ML - MALI MH - MARSHALL ISLANDS MR - MAURITANIA MU - MAURITIUS MX - MEXICO FM - MICRONESIA (FEDERATED STATES OF) MD - MOLDOVA, REPUPLIC OF MN - MONGOLIA MA - MOROCCO MZ - MOZAMBIQUE MM - MYANMAR NA - NAMIBIA NL - NETHERLANDS NZ - NEW ZEALAND NI - NICARAGUA NE - NIGER NG - NIGERIA NO - NORWAY OM - OMAN PK - PAKISTAN PA - PANAMA PG - PAPUA NEW GUINEA PY - PARAGUAY PE - PERU PH - PHILIPPINES PL - POLAND PT - PORTUGAL QA - QATAR RO - ROMANIA RU - RUSSIA RW - RWANDA ST - SAO TOME AND PRINCIPE SA - SAUDI ARABIA SN - SENEGAL SL - SIERRA LEONE SK - SLOVAKIA SI - SLOVENIA SB - SOLOMON ISLANDS SO - SOMALIA ZA - SOUTH AFRICA ES - SPAIN LK - SRI LANKA SH - ST HELENA SD - SUDAN SR - SURINAME SZ - SWAZILAND SE - SWEDEN CH - SWITZERLAND SY - SYRIAN ARAB REPUBLIC TW - TAIWAN, PROVINCE OF CHINA TJ - TAJIKISTAN TZ - TANZANIA, UNITED REPUBLIC OF TH - THAILAND TG - TOGO TT - TRINIDAD AND TOBAGO TN - TUNISIA TR - TURKEY TM - TURKMENISTAN UG - UGANDA UA - UKRAINE AE - UNITED ARAB EMIRATES GB - UNITED KINGDOM US - UNITED STATES UM - UNITED STATES MINOR OUTLYING ISLANDS UY - URUGUAY UZ - UZBEKISTAN VU - VANUATU VE - VENEZUELA VN - VIET NAM WF - WALLIS AND FUTUNA ISLANDS YE - YEMEN YU - YUGOSLAVIA ZM - ZAMBIA ZW - ZIMBABWE All forms of upper/lower case are acceptable in the country's spelling. If a country name is supplied that the module doesn't recognise, it will die. country ------- Returns the current country of the sub country object country_code ------------ Returns the two lwttwr current country of the sub country object sub_country_type ---------------- Returns the current sub country type (state, county etc) for the sub country object, or 'unknown' if a value is not defined. Currently sub country types are defined for: Australia : State Canada : Province France : Department Germany : Lander Ireland : County UK : County USA : State code ---- The code method takes the full name of a sub country in the currently assigned country and returns the sub country's code. The full name can appear in mixed case. All white space and non alphabetic characters are ignored, except the single space used to separate sub country names such as "New South Wales". The code is returned as a capitalised string, or "unknown" if no match is found. full_name --------- The full_name method takes the code of a sub country in the currently assigned country and returns the sub country's full name. The code can appear in mixed case. All white space and non alphabetic characters are ignored. The full name is returned as a title cased string, such as "South Australia". If an optional argument is supplied and set to a true value, the full name is returned as an upper cased string. full_name_code_hash ------------------- Returns a hash of name/code pairs for the currently assigned country, keyed by sub country name. code_full_name_hash ------------------- Returns a hash of code/name pairs for the currently assigned country, keyed by sub country code. all_full_names -------------- Returns an array of sub country names for the currently assigned country, sorted alphabetically. all_codes --------- Returns an array of sub country codes for the currently assigned country, sorted alphabetically. all_country_names ----------------- Returns an array of all country names that this module can do lookups for, sorted alphabetically. This is implemented as a conventional subroutine rather than a method. This allows us to check if lookups can be done for a given country before actually creating the lookup object. all_country_codes ----------------- Returns an array of all country 2 leteer codes that this module can do lookups for, sorted alphabetically. This is implemented as a conventional subroutine rather than a method. This allows us to check if lookups can be done for a given country code before actually creating the lookup object. SEE ALSO ======== ISO 3166-2:1998, Standard for naming sub country codes Locale::Country Locale::US LIMITATIONS =========== If a sub country's full name contains the word 'and', it is represented by an ampersand, as in 'Dumfries & Galloway'. ISO 3166-2:1998 defines all sub country codes as being 2 letters. This works for USA, Canada etc. In Australia and the UK, this method of abbreviation is not widely accepted. For example, the ISO code for 'New South Wales' is 'NS', but 'NSW' is the only abbreviation that is actually used. I could add an enforce ISO-3166 flag if needed. The ISO 3166-2 standard romanizes the names of provinces and regions in non-latin script areas, such as Russia and South Korea. One Romanisation is given for each province name. For Russia, the BGN (1947) Romanization is used. The ISO 3166-2 standard for Italy lists alphabetic codes for provinces and numeric codes for the regions they belong to, both are listed. The following sub country names have more than one code, and may not return the correct code for that sub country. AZERBAIJAN : Länkäran; LA,LAN AZERBAIJAN : Säki; SA,SAK AZERBAIJAN : Susa; SS,SUS AZERBAIJAN : Yevlax; YE,YEV INDONESIA : Kalimantan Timur; KI,KT LAOS : Vientiane VI,VT MOLDOVA : Hahul; CA,CHL MOLDOVA : Bubasari; DU,DBI MOLDOVA : Hrhei; OR,OHI MOLDOVA : Coroca; SO,SOA MOLDOVA : Gngheni; UN,UGI MOZAMBIQUE : Maputo; MPM,L BUGS ==== COPYRIGHT ========= Copyright (c) 2000-1 Kim Ryan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html). AUTHOR ====== Locale::SubCountry was written by Kim Ryan in 2000. CREDITS ======= Alastair McKinstry provided nearly all the sub country codes and names. Terrence Brannon produced Locale::US, which was the starting point for this module. Some of the ideas in Geography::States were also used. Mark Summerfield and Guy Fraser provided the list of UK counties. Code/Sub country data. Comments (lines starting with #) and blank lines are ignored. Read in at start up by INIT subroutine. Format is: Country= Code= # from ISO 3166 format SubCountryType= # optional field, specify state, county etc CODE:Full Name CODE:Full Name CODE:Full Name ... Country= ...  File: pm.info, Node: Locale/gettext, Next: LockFile/Simple, Prev: Locale/SubCountry, Up: Module List message handling functions ************************** NAME ==== gettext - message handling functions SYNOPSIS ======== use Locale::gettext; use POSIX; # Needed for setlocale() setlocale(LC_MESSAGES, ""); textdomain("my_program"); print gettext("Welcome to my program"), "\n"; # (printed in the local language) DESCRIPTION =========== The gettext module permits access from perl to the gettext() family of functions for retrieving message strings from databases constructed to internationalize software. gettext(), dgettext(), and dcgettext() attempt to retrieve a string matching their msgid parameter within the context of the current locale. dcgettext() takes the message's category and the text domain as parameters while dcgettext() defaults to the LC_MESSAGES category and gettext() defaults to LC_MESSAGES and uses the current text domain. If the string is not found in the database, then msgid is returned. textdomain() sets the current text domain and returns the previously active domain. *bindtextdomain(domain, dirname)* instructs the retrieval functions to look for the databases belonging to domain domain in the directory `dirname' VERSION ======= 1.01. 1.00 was not under the Locale/ directory. SEE ALSO ======== gettext(3i), gettext(1), msgfmt(1) AUTHOR ====== Phillip Vandry  File: pm.info, Node: LockFile/Simple, Next: Log/Agent, Prev: Locale/gettext, Up: Module List simple file locking scheme ************************** NAME ==== LockFile::Simple - simple file locking scheme SYNOPSIS ======== use LockFile::Simple qw(lock trylock unlock); # Simple locking using default settings lock("/some/file") || die "can't lock /some/file\n"; warn "already locked\n" unless trylock("/some/file"); unlock("/some/file"); # Build customized locking manager object $lockmgr = LockFile::Simple->make(-format => '%f.lck', -max => 20, -delay => 1, -nfs => 1); $lockmgr->lock("/some/file") || die "can't lock /some/file\n"; $lockmgr->trylock("/some/file"); $lockmgr->unlock("/some/file"); $lockmgr->configure(-nfs => 0); # Using lock handles my $lock = $lockmgr->lock("/some/file"); $lock->release; DESCRIPTION =========== This simple locking scheme is not based on any file locking system calls such as flock() or `lockf()' but rather relies on basic file system primitives and properties, such as the atomicity of the write() system call. It is not meant to be exempt from all race conditions, especially over NFS. The algorithm used is described below in the ALGORITHM section. It is possible to customize the locking operations to attempt locking once every 5 seconds for 30 times, or delete stale locks (files that are deemed too ancient) before attempting the locking. ALGORITHM ========= The locking alogrithm attempts to create a *lockfile* using a temporarily redefined umask (leaving only read rights to prevent further create operations). It then writes the process ID (PID) of the process and closes the file. That file is then re-opened and read. If we are able to read the same PID we wrote, and only that, we assume the locking is successful. When locking over NFS, i.e. when the one of the potentially locking processes could access the *lockfile* via NFS, then writing the PID is not enough. We also write the hostname where locking is attempted to ensure the data are unique. CUSTOMIZING =========== Customization is only possible by using the object-oriented interface, since the configuration parameters are stored within the object. The object creation routine make can be given configuration parmeters in the form a "hash table list", i.e. a list of key/value pairs. Those parameters can later be changed via configure by specifying a similar list of key/value pairs. To benefit from the bareword quoting Perl offers, all the parameters must be prefixed with the - (minus) sign, as in `-format' for the format parameter.. However, when querying the object, the minus must be omitted, as in `$obj->format'. Here are the available configuration parmeters along with their meaning, listed in alphabetical order: autoclean When true, all locks are remembered and pending ones are automatically released when the process exits normally (i.e. whenever Perl calls the END routines). delay The amount of seconds to wait between locking attempts when the file appears to be already locked. Default is 2 seconds. efunc A function pointer to dereference when an error is to be reported. By default, it redirects to the logerr() routine if you have Log::Agent installed, to Perl's warn() function otherwise. You may set it explicitely to `\&LockFile::Simple::core_warn' to force the use of Perl's warn() function, or to undef to suppress logging. ext The locking extension that must be added to the file path to be locked to compute the *lockfile* path. Default is `.lock' (note that . is part of the extension and can therefore be changed). Ignored when format is also used. format Using this parmeter supersedes the ext parmeter. The formatting string specified is run through a rudimentary macro expansion to derive the *lockfile* path from the file to be locked. The following macros are available: %% A real % sign %f The full file path name %D The directory where the file resides %F The base name of the file %p The process ID (PID) The default is to use the locking extension, which itself is `.lock', so it is as if the format used was `%f.lock', but one could imagine things like `/var/run/%F.%p', i.e. the *lockfile* does not necessarily lie besides the locked file (which could even be missing). When locking, the locking format can be specified to supersede the object configuration itself. hold Maximum amount of seconds we may hold a lock. Past that amount of time, an existing *lockfile* is removed, being taken for a stale lock. Default is 3600 seconds. Specifying 0 prevents any forced unlocking. max Amount of times we retry locking when the file is busy, sleeping delay seconds between attempts. Defaults to 30. nfs A boolean flag, false by default. Setting it to true means we could lock over NFS and therefore the hostname must be included along with the process ID in the stamp written to the lockfile. stale A boolean flag, false by default. When set to true, we attempt to detect stale locks and break them if necessary. wafter Stands for *warn after*. It is the number of seconds past the first warning during locking time after which a new warning should be emitted. See warn and wmin below. Default is 20. warn A boolean flag, true by default. To suppress any warning, set it to false. wfunc A function pointer to dereference when a warning is to be issued. By default, it redirects to the logwarn() routine if you have Log::Agent installed, to Perl's warn() function otherwise. You may set it explicitely to `\&LockFile::Simple::core_warn' to force the use of Perl's warn() function, or to undef to suppress logging. wmin The minimal amount of time when waiting for a lock after which a first warning must be emitted, if warn is true. After that, a warning will be emitted every wafter seconds. Defaults to 15. Each of those configuration attributes can be queried on the object directly: $obj = LockFile::Simple->make(-nfs => 1); $on_nfs = $obj->nfs; Those are pure query routines, i.e. you cannot say: $obj->nfs(0); # WRONG $obj->configure(-nfs => 0); # Right to turn of the NFS attribute. That is because my OO background chokes at having querying functions with side effects. INTERFACE ========= The OO interface documented below specifies the signature and the semantics of the operations. Only the lock, `trylock' and unlock operation can be imported and used via a non-OO interface, with the exact same signature nonetheless. The interface contains all the attribute querying routines, one for each configuration parmeter documented in the CUSTOMIZING section above, plus, in alphabetical order: configure(*-key => value, -key2 => value2, ...*) Change the specified configuration parameters and silently ignore the invalid ones. lock(file, format) Attempt to lock the file, using the optional locking format if specified, otherwise using the default format scheme configured in the object, or by simply appending the ext extension to the file. If the file is already locked, sleep delay seconds before retrying, repeating try/sleep at most max times. If warning is configured, a first warning is emitted after waiting for wmin seconds, and then once every wafter seconds, via the wfunc routine. Before the first attempt, and if hold is non-zero, any existing *lockfile* is checked for being too old, and it is removed if found to be stale. A warning is emitted via the wfunc routine in that case, if allowed. Likewise, if stale is non-zero, a check is made to see whether any locking process is still around (only if the lock holder is on the same machine when NFS locking is configured). Should the locking process be dead, the *lockfile* is declared stale and removed. Returns a lock handle if the file has been successfully locked, which does not necessarily needs to be kept around. For instance: $obj->lock('ppp', '/var/run/ppp.%p'); $obj->unlock('ppp'); or, using OO programming: my $lock = $obj->lock('ppp', '/var/run/ppp.%p') ||; die "Can't lock for ppp\n"; $lock->relase; # The only method defined for a lock handle i.e. you don't even have to know which file was locked to release it, since there is a lock handle right there that knows enough about the lock parameters. lockfile(file, format) Simply compute the path of the *lockfile* that would be used by the lock procedure if it were passed the same parameters. make(*-key => value, -key2 => value2, ...*) The creation routine for the simple lock object. Returns a blessed hash reference. trylock(file, format) Same as lock except that it immediately returns false and does not sleep if the to-be-locked file is busy, i.e. already locked. Any stale locking file is removed, as lock would do anyway. Returns a lock hande if the file has been successfully locked. unlock(file) Unlock the file. BUGS ==== The algorithm is not bullet proof. It's only reasonably safe. Don't bet the integrity of a mission-critical database on it though. The sysopen() call should probably be used with the `O_EXCL|O_CREAT' flags to be on the safer side. Still, over NFS, this is not an atomic operation anyway. *BEWARE*: there is a race condition between the time we decide a lock is stale or too old and the time we unlink it. Don't use `-stale' and set `-hold' to 0 if you can't bear with that idea, but recall that this race only happens when something is already wrong. That does not make it right, nonetheless. ;-) AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== File::Flock(3).  File: pm.info, Node: Log/Agent, Next: Log/Agent/Caller, Prev: LockFile/Simple, Up: Module List logging agent ************* NAME ==== Log::Agent - logging agent SYNOPSIS ======== use Log::Agent; # in all reusable components logerr "error"; logtrc "notice:12", "notice that" if ...; logdie "log and die"; use Log::Agent; # in application's main logconfig(-prefix => $0); # simplest, uses default driver use Log::Agent; # another more complex example require Log::Agent::Driver::File; # logging made to file logconfig(-driver => Log::Agent::Driver::File->make( -prefix => $0, -showpid => 1, -channels => { 'error' => "$0.err", 'output' => "$0.out", 'debug' => "$0.dbg", }, ) ); DESCRIPTION =========== The `Log::Agent' module provides an abstract layer for logging and tracing, which is independant from the actual method used to physically perform those activities. It acts as an agent (hence the name) that collects the requests and delegates processing to a sublayer: the logging driver. The `Log::Agent' module is meant to be used in all reusable components, since they cannot know in advance how the application which ends up using them will perform its logging activities: either by emitting messages on stdout and errors on stderr, or by directing messages to logfiles, or by using syslog(3). The logging interface is common for all the logging drivers, and is therefore the result of a compromise between many logging schemes: any information given at this level must be either handled by all drivers, or may be ignored depending on the application's final choice. WARNING: THIS INTERFACE IS STILL SOMEWHAT ALPHA AND COULD STILL CHANGE DEPENDING ON THE FEEDBACK I SHALL GET FROM USERS AND FROM MY OWN EXPERIENCE USING IT, WITHOUT ANY BACKWARD COMPATIBILITY ASSURANCE. PRIORITIES AND LEVEL ==================== The `Log::Agent' module can use both priorities (as defined by syslog(3)) or logging levels, or either, in which case there is an implicit computation of the missing item (i.e. the level 4, for instance, corresponds to the "warning" priority, and vice-versa). See *Note Log/Agent/Priorities: Log/Agent/Priorities, for more details. A logging level is defined as being a threshold: any level lesser than or equal to that threshold will be logged. At the `Log::Agent' level, it is possible to define a trace level and a debug level. Only the messages below those levels (inclusive) will be handed out to the underlying driver for logging. They are used by the logtrc() and logdbg() routines, respectively. CHANNELS ======== The `Log::Agent' class defines three logging channels, which are error, output and debug. Depending on the driver used for logging, those channels are ignored (typically with syslog()) or may be implicitely defined (default logging, i.e. the one achieved by the Log::Agent::Driver::Default driver, remaps error and debug to stderr, output to stdout). INTERFACE ========= Anywhere a message is expected, it can be a single string, or a printf()-like format string followed by the required arguments. The special macro `%m' is handled directly by `Log::Agent' and is replaced by the string version of $!, which is the last error message returned by the last failing system call. NOTE: There should not be any trailing "\n" in the message strings, nor any embededed one, although this is not enforced. Remember that the main purpose of `Log::Agent' is to specify logging messages in a standard way! Therefore, most of the time, a "should" should be read as "must" and "should not" as "must not", which is the strongest interdiction form available in English, as far as I know. Here are valid message examples: "started since $time" "started since %s", $time "fork: %m" The follwing logging interface is made available to modules: logdbg priority, message Debug logging of message to the debug channel. You may specify any priority you want, i.e. a debug priority is not enforced here. You may even specify `"notice:4"' if you wish, to have the message logged if the debug level is set to 4 or less. If handed over to syslog(3), the message will nonetheless be logged at the notice priority. logtrc priority, message Trace logging of message to the output channel. Like logdbg() above, you are not restricted to the info priority. This routine checks the logging level (either explicit as in `"info:14"' or implicit as in `"notice"') against the trace level. logsay message Log the message at the notice priority to the output channel. The logging always takes place under the default `-trace' settings, but only if the routine is called, naturally. This means you can still say: logsay "some trace message" if $verbose; and control whether the message is emitted by using some external configuration for your module (e.g. by adding a -verbose flag to the creation routine of your class). logwarn message Log a warning message at the warning priority to the error channel. logcarp message Same as logwarn(), but issues a Carp::carp(3) call instead, which will warn from the perspective of the routine's caller. logerr message Log an error message at the error priority to the error channel. logdie message Log a fatal message at the critical priority to the error channel, and then dies. logconfess message Same as logdie(), but issues a Carp::confess(3) call instead. It is possible to configure the `Log::Agent' module via the `-confess' switch to automatically redirect a logdie() to logconfess(), which is invaluable during unit testing. logcroak message Same as logdie(), but issues a Carp::croak(3) call instead. It is possible to configure the `Log::Agent' module via the `-confess' switch to automatically redirect a logcroak() to logconfess(), which is invaluable during unit testing. Log::Agent::inited Returns true when `Log::Agent' was initialized, either explicitely via a logconfig() or implicitely via any logxxx() call. Modules sometimes wish to report errors from the perspective of their caller's caller, not really their caller. The following interface is therefore provided: logxcarp offset, message Same a logcarp(), but with an additional offset to be applied on the stack. To warn one level above your caller, set it to 1. logxcroak offset, message Same a logcroak(), but with an additional offset to be applied on the stack. To report an error one level above your caller, set it to 1. For applications that wish to implement a debug layer on top of `Log::Agent', the following routine is provided. Note that it is not imported by default, i.e. it needs to be explicitely mentionned at use time, since it is not meant to be used directly under regular usage. logwrite channel, priority, message Unconditionally write the message at the given priority on channel. The channel can be one of debug, error or output. At the application level, one needs to commit once and for all about the logging scheme to be used. This is done thanks to the logconfig() routine which takes the following switches, in alphabetical order: `-caller' => [ parameters ] Request that caller information (relative to the logxxx() call) be part of the log message. The given parameters are handed off to the creation routine of Log::Agent::Caller(3) and are documented there. I usually say something like: -caller => [ -display => '($sub/$line)' ] which I find informative enough. On occasion, I found myself using more complex sequences. `-confess' => flag When true, all logdie() calls will be automatically masqueraded as logconfess(). `-debug' => *priority or level* Sets the priority threshold (can be expressed as a string or a number, the string being mapped to a logging level as described above in PRIORITIES AND LEVEL) for logdbg() calls. Calls tagged with a level less than or equal to the given threshold will pass through, others will return prematurely without logging anything. `-driver' => *driver_object* This switch defines the driver object to be used, which must be an heir of the `Log::Agent::Driver' class. See `Log::Agent::Driver(3)' in this node for a list of the available drivers. `-level' => *priority or level* Specifies both `-debug' and `-trace' levels at the same time, to a common value. `-prefix' => name Defines the application name which will be pre-pended to all messages, followed by `": "' (a colon and a space). Using this switch alone will configure the default driver to use that prefix (stripped down to its basename component). When a driver object is used, the `-prefix' switch is kept at the `Log::Agent' level only and is not passed to the driver: it is up to the driver's creation routine to request the `-prefix'. Having this information in Log::Agent enables the module to die on critical errors with that error prefix, since it cannot rely on the logging driver for that, obviously. `-trace' => *priority or level* Same a `-debug' but applies to logsay(), logwarn(), logerr() and logtrc(). When unspecified, `Log::Agent' runs at the "notice" level. KNOWN LIMITATIONS ================= The following limitations exist in this early version. They might be addressed in future versions if they are perceived as annoying limitatons instead of being just documented ones. :-) * A module which calls logdie() may have its die trapped if called from within an eval(), but unfortunately, the value of $@ is unpredictable: it may be prefixed or not depending on the driver used. This is harder to fix as one might think of at first glance. * Some drivers lack customization and hardwire a few things that come from my personal taste, like the prefixing done when *duperr* is set in Log::Agent::Driver::File, or the fact that the debug and stderr channels are merged as one in the Log::Agent::Driver::Default driver. * When using logcroak() or logconfess(), the place where the call was made can still be visible when -caller is used, since the addition of the caller information to the message is done before calling the logging driver. Is this a problem? AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Driver(3), Carp(3).  File: pm.info, Node: Log/Agent/Caller, Next: Log/Agent/Channel, Prev: Log/Agent, Up: Module List formats caller information ************************** NAME ==== Log::Agent::Caller - formats caller information SYNOPSIS ======== Not intended to be used directly DESCRIPTION =========== This class handles caller information for Log::Agent services and is not meant to be used directly. This manpage therefore only documents the creation routine parameters that can be specified at the Log::Agent level via the `-caller' switch in the logconfig() routine. CALLER INFORMATION ENTITIES =========================== This class knows about four entities: package, filename, line and subroutine, which are to be understood within the context of the Log::Agent routine being called (e.g. a logwarn() routine), namely: package This is the package name where the call to the logwarn() routine was made. It can be specified as "pack" for short, or spelled out completely. filename This is the file where the call to the logwarn() routine was made. It can be specified as "file" for short, or spelled out completely. line This is the line number where the call to the logwarn() routine was made, in file filename. The name is short enough to be spelled out completely. subroutine This is the subroutine where the call to the logwarn() routine was made. If the call is made outside a subroutine, this will be empty. The name is long enough to warrant the "sub" abbreviation if you don't wish to spell it out fully. CREATION ROUTINE PARAMETERS =========================== The purpose of those parameters is to define how caller information entities (as defined by the previous section) will be formatted within the log message. `-display' => string Specifies a string with minimal variable substitution: only the caller information entities specified above, or their abbreviation, will be interpolated. For instance: -display => '($package::$sub/$line)' Don't forget to use simple quotes to avoid having Perl interpolate those as variables, or escape their leading `$' sign otherwise. Using this convention was deemed to more readable (and natural in Perl) than SGML entities such as "&pack;". Using this switch supersedes the `-info' and `-format' switches. `-format' => *printf format* Formatting instructions for the caller information entities listed by the `-info' switch. For instance: -format => "%s:%4d" if you have specified two entities in `-info'. The special formatting macro `%a' stands for all the entities specified by `-info' and is rendered by a string where values are separated by ":". `-info' => *"space separated list of parameters"* Specifies a list of caller information entities that are to be formated using the `-format' specification. For instance: -info => "pack sub line" would only report those three entites. `-postfix' => flag Whether the string resulting from the formatting of the caller information entities should be appended to the regular log message or not (i.e. prepended, which is the default). Separation from the remaining of the log message is a single space. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent(3), Log::Agent::Message(3).  File: pm.info, Node: Log/Agent/Channel, Next: Log/Agent/Channel/File, Prev: Log/Agent/Caller, Up: Module List ancestor class for all Log::Agent channels ****************************************** NAME ==== Log::Agent::Channel - ancestor class for all Log::Agent channels SYNOPSIS ======== @Log::Agent::Channel::XXX::ISA = qw(Log::Agent::Channel); DESCRIPTION =========== The `Log::Agent::Channel' class is the root class from which all `Log::Agent' channels inherit. It is a *deferred* class, meaning that it cannot be instantiated directly. All the deferred routines need to be implemented by its heirs to form a valid driver. Internally, the various `Log::Agent::Driver' objects create `Log::Agent::Channel' instances for each logging channel defined at driver creation time. The channels are therefore architecturally hidden within `Log::Agent', since this module only provides redefined mappings for the various logxxx() routines (logerr(), logwarn(), logdie(), etc...). However, this does not mean that channel classes cannot be used externally: the `Log::Agent::Logger' extension makes `Log::Agent::Channel' objects architecturally visible, thereby offering an application-level logging API that can be redirected to various places transparently for the application. CHANNEL LIST ============ The following channels are currently made available by `Log::Agent'. More channels can be defined by the `Log::Agent::Logger' extension: Log::Agent::Channel::File This channel writes logs to files, defined by their path or via a magical opening sequence such as "|cmd". Log::Agent::Channel::Handle This channel writes logs to an already opened descriptor, as specified by its file handle: an IO::Handle object, or a GLOB reference such as \*FILE. Log::Agent::Channel::Syslog This channel redirects logs to the syslogd(8) daemon, which will then handle the dispatching to various logfiles, based on its own configuration. INTERFACE ========= You need not read this section if you're only using `Log::Agent'. However, if you wish to implement another channel, then this section might be of interest. The following routines are *deferred* and therefore need to be defined by the heir: write($priority, $logstring) Emit the log entry held in $logstring, at priority $priority. A trailing "\n" is added to the $logstring, if needed (i.e. if the physical entity does not do it already, like syslog does). The $priority argument must be a valid syslog priority, i.e. one of the following strings: "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug". The $logstring may not really be a plain string. It can actually be a Log::Agent::Message object with an overloaded stringification routine, so the illusion should be complete. close Close the channel. make This is the creation routine. Its signature varies for each channel, naturally. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Channel::File(3), Log::Agent::Channel::Handle(3), Log::Agent::Channel::Syslog(3), Log::Agent::Logger(3).  File: pm.info, Node: Log/Agent/Channel/File, Next: Log/Agent/Channel/Handle, Prev: Log/Agent/Channel, Up: Module List file logging channel for Log::Agent *********************************** NAME ==== Log::Agent::Channel::File - file logging channel for Log::Agent SYNOPSIS ======== require Log::Agent::Channel::File; my $driver = Log::Agent::Channel::File->make( -prefix => "prefix", -stampfmt => "own", -showpid => 1, -magic_open => 0, -filename => "/tmp/output.err", -share => 1, ); DESCRIPTION =========== The file channel performs logging to a file, along with the necessary prefixing and stamping of the messages. Internally, the Log::Agent::Driver::File driver creates such objects for each logging channel defined at driver creation time. The creation routine make() takes the following arguments: `-filename' => file The file name where output should go. The file is opened in append mode and autoflushing is turned on. See also the `-magic_open' flag. `-magic_open' => flag When true, channel filenames beginning with '>' or '|' are opened using Perl's open(). Otherwise, sysopen() is used, in append mode. Default is false. `-no_newline' => flag When set to *true*, never append any "\n" (on Unix) or "\r\n" (on Windows) to log messages. Internally, Log::Agent relies on the channel to delimit logged lines appropriately, so this flag is not used. However, it might be useful for `Log::Agent::Logger' users. Default is false, meaning newline markers are systematically appended. `-no_prefixing' => flag When set to *true*, disable the prefixing logic entirely, i.e. the following options are ignored completely: `-prefix', `-showpid', `-no_ucfirst', `-stampfmt'. Default is false. `-no_ucfirst' => flag When set to *true*, don't upper-case the first letter of the log message entry when there's no prefix inserted before the logged line. When there is a prefix, a ":" character follows, and therefore the leading letter of the message should not be upper-cased anyway. Default is false, meaning uppercasing is performed. `-prefix' => prefix The application prefix string to prepend to messages. `-rotate' => object This sets a default logfile rotation policy. You need to install the additional `Log::Agent::Rotate' module to use this switch. object is the `Log::Agent::Rotate' instance describing the rotating policy for the channel. Only files which are not opened via a so-called *magic open* can be rotated. `-share' => flag When *true*, this flag records the channel in a global pool indexed by filenames. An existing file handle for the same filename may be then be shared amongst several file channels. However, you will get this message in the file Rotation for 'filename' may be wrong (shared with distinct policies) when a rotation policy different from the one used during the initial opening is given. Which policy will be used is unspecified, on purpose. `-showpid' => flag If set to true, the PID of the process will be appended within square brackets after the prefix, to all messages. Default is false. `-stampfmt' => (name | CODE) Specifies the time stamp format to use. By default, my "own" format is used. See *Note Log/Agent/Stamping: Log/Agent/Stamping, for a description of the available format names. You may also specify a CODE ref: that routine will be called every time we need to compute a time stamp. It should not expect any parameter, and should return a string. CAVEAT ====== Beware of chdir(). If your program uses chdir(), you should always specify logfiles by using absolute paths, otherwise you run the risk of having your relative paths become invalid: there is no anchoring done at the time you specify them. This is especially true when configured for rotation, since the logfiles are recreated as needed and you might end up with many logfiles scattered throughout all the directories you chdir()ed to. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Logger(3), Log::Agent::Channel(3).  File: pm.info, Node: Log/Agent/Channel/Handle, Next: Log/Agent/Channel/Syslog, Prev: Log/Agent/Channel/File, Up: Module List I/O handle logging channel for Log::Agent ***************************************** NAME ==== Log::Agent::Channel::Handle - I/O handle logging channel for Log::Agent SYNOPSIS ======== require Log::Agent::Channel::Handle; my $driver = Log::Agent::Channel::Handle->make( -prefix => "prefix", -stampfmt => "own", -showpid => 1, -handle => \*FILE, ); DESCRIPTION =========== The handle channel performs logging to an already opened I/O handle, along with the necessary prefixing and stamping of the messages. The creation routine make() takes the following arguments: `-handle' => handle Specifies the I/O handle to use. It can be given as a GLOB reference, such as `\*FILE', or as an IO::Handle object. NOTE: Auto-flushing is not enabled on the handle. Even when the channel is closed, the handle is left as-is: we simply stop sending log messages to it. `-no_newline' => flag When set to *true*, never append any "\n" (on Unix) or "\r\n" (on Windows) to log messages. Internally, Log::Agent relies on the channel to delimit logged lines appropriately, so this flag is not used. However, it might be useful for `Log::Agent::Logger' users. Default is false, meaning newline markers are systematically appended. `-no_prefixing' => flag When set to *true*, disable the prefixing logic entirely, i.e. the following options are ignored completely: `-prefix', `-showpid', `-no_ucfirst', `-stampfmt'. Default is false. `-no_ucfirst' => flag When set to *true*, don't upper-case the first letter of the log message entry when there's no prefix inserted before the logged line. When there is a prefix, a ":" character follows, and therefore the leading letter of the message should not be upper-cased anyway. Default is false, meaning uppercasing is performed. `-prefix' => prefix The application prefix string to prepend to messages. `-showpid' => flag If set to true, the PID of the process will be appended within square brackets after the prefix, to all messages. Default is false. `-stampfmt' => (name | CODE) Specifies the time stamp format to use. By default, my "own" format is used. See *Note Log/Agent/Stamping: Log/Agent/Stamping, for a description of the available format names. You may also specify a CODE ref: that routine will be called every time we need to compute a time stamp. It should not expect any parameter, and should return a string. CAVEAT ====== Beware of chdir(). If your program uses chdir(), you should always specify logfiles by using absolute paths, otherwise you run the risk of having your relative paths become invalid: there is no anchoring done at the time you specify them. This is especially true when configured for rotation, since the logfiles are recreated as needed and you might end up with many logfiles scattered throughout all the directories you chdir()ed to. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Logger(3), Log::Agent::Channel(3).