{ "content": [ { "type": "text", "text": "# Log::Dispatch (perldoc)\n\n## NAME\n\nLog::Dispatch - Dispatches messages to one or more outputs\n\n## SYNOPSIS\n\nuse Log::Dispatch;\n# Simple API\n#\nmy $log = Log::Dispatch->new(\noutputs => [\n[ 'File', minlevel => 'debug', filename => 'logfile' ],\n[ 'Screen', minlevel => 'warning' ],\n],\n);\n$log->info('Blah, blah');\n# More verbose API\n#\nmy $log = Log::Dispatch->new();\n$log->add(\nLog::Dispatch::File->new(\nname => 'file1',\nminlevel => 'debug',\nfilename => 'logfile'\n)\n);\n$log->add(\nLog::Dispatch::Screen->new(\nname => 'screen',\nminlevel => 'warning',\n)\n);\n$log->log( level => 'info', message => 'Blah, blah' );\nmy $sub = sub { my %p = @; return reverse $p{message}; };\nmy $reversingdispatcher = Log::Dispatch->new( callbacks => $sub );\n\n## DESCRIPTION\n\nThis module manages a set of Log::Dispatch::* output objects that can be logged to via a unified\ninterface.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **OUTPUT CLASSES**\n- **LOG LEVELS**\n- **SUBCLASSING**\n- **RELATED MODULES** (9 subsections)\n- **SEE ALSO**\n- **SUPPORT**\n- **SOURCE**\n- **DONATIONS**\n- **AUTHOR**\n- **CONTRIBUTORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Log::Dispatch", "section": "", "mode": "perldoc", "summary": "Log::Dispatch - Dispatches messages to one or more outputs", "synopsis": "use Log::Dispatch;\n# Simple API\n#\nmy $log = Log::Dispatch->new(\noutputs => [\n[ 'File', minlevel => 'debug', filename => 'logfile' ],\n[ 'Screen', minlevel => 'warning' ],\n],\n);\n$log->info('Blah, blah');\n# More verbose API\n#\nmy $log = Log::Dispatch->new();\n$log->add(\nLog::Dispatch::File->new(\nname => 'file1',\nminlevel => 'debug',\nfilename => 'logfile'\n)\n);\n$log->add(\nLog::Dispatch::Screen->new(\nname => 'screen',\nminlevel => 'warning',\n)\n);\n$log->log( level => 'info', message => 'Blah, blah' );\nmy $sub = sub { my %p = @; return reverse $p{message}; };\nmy $reversingdispatcher = Log::Dispatch->new( callbacks => $sub );", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 35, "subsections": [] }, { "name": "DESCRIPTION", "lines": 12, "subsections": [] }, { "name": "METHODS", "lines": 133, "subsections": [] }, { "name": "OUTPUT CLASSES", "lines": 44, "subsections": [] }, { "name": "LOG LEVELS", "lines": 16, "subsections": [] }, { "name": "SUBCLASSING", "lines": 13, "subsections": [] }, { "name": "RELATED MODULES", "lines": 1, "subsections": [ { "name": "Log::Dispatch::DBI", "lines": 2 }, { "name": "Log::Dispatch::FileRotate", "lines": 2 }, { "name": "Log::Dispatch::File::Stamped", "lines": 2 }, { "name": "Log::Dispatch::Jabber", "lines": 2 }, { "name": "Log::Dispatch::Tk", "lines": 2 }, { "name": "Log::Dispatch::Win32EventLog", "lines": 2 }, { "name": "Log::Log4perl", "lines": 4 }, { "name": "Log::Dispatch::Config", "lines": 3 }, { "name": "Log::Agent", "lines": 3 } ] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "DONATIONS", "lines": 15, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "CONTRIBUTORS", "lines": 48, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "Log::Dispatch - Dispatches messages to one or more outputs\n", "subsections": [] }, "VERSION": { "content": "version 2.70\n", "subsections": [] }, "SYNOPSIS": { "content": "use Log::Dispatch;\n\n# Simple API\n#\nmy $log = Log::Dispatch->new(\noutputs => [\n[ 'File', minlevel => 'debug', filename => 'logfile' ],\n[ 'Screen', minlevel => 'warning' ],\n],\n);\n\n$log->info('Blah, blah');\n\n# More verbose API\n#\nmy $log = Log::Dispatch->new();\n$log->add(\nLog::Dispatch::File->new(\nname => 'file1',\nminlevel => 'debug',\nfilename => 'logfile'\n)\n);\n$log->add(\nLog::Dispatch::Screen->new(\nname => 'screen',\nminlevel => 'warning',\n)\n);\n\n$log->log( level => 'info', message => 'Blah, blah' );\n\nmy $sub = sub { my %p = @; return reverse $p{message}; };\nmy $reversingdispatcher = Log::Dispatch->new( callbacks => $sub );\n", "subsections": [] }, "DESCRIPTION": { "content": "This module manages a set of Log::Dispatch::* output objects that can be logged to via a unified\ninterface.\n\nThe idea is that you create a Log::Dispatch object and then add various logging objects to it\n(such as a file logger or screen logger). Then you call the \"log\" method of the dispatch object,\nwhich passes the message to each of the objects, which in turn decide whether or not to accept\nthe message and what to do with it.\n\nThis makes it possible to call single method and send a message to a log file, via email, to the\nscreen, and anywhere else, all with very little code needed on your part, once the dispatching\nobject has been created.\n", "subsections": [] }, "METHODS": { "content": "This class provides the following methods:\n\nLog::Dispatch->new(...)\nThis method takes the following parameters:\n\n* outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )\n\nThis parameter is a reference to a list of lists. Each inner list consists of a class name\nand a set of constructor params. The class is automatically prefixed with 'Log::Dispatch::'\nunless it begins with '+', in which case the string following '+' is taken to be a full\nclassname. e.g.\n\noutputs => [ [ 'File', minlevel => 'debug', filename => 'logfile' ],\n[ '+My::Dispatch', minlevel => 'info' ] ]\n\nFor each inner list, a new output object is created and added to the dispatcher (via the\n\"add()\" method).\n\nSee \"OUTPUT CLASSES\" for the parameters that can be used when creating an output object.\n\n* callbacks( \\& or [ \\&, \\&, ... ] )\n\nThis parameter may be a single subroutine reference or an array reference of subroutine\nreferences. These callbacks will be called in the order they are given and passed a hash\ncontaining the following keys:\n\n( message => $logmessage, level => $loglevel )\n\nIn addition, any key/value pairs passed to a logging method will be passed onto your\ncallback.\n\nThe callbacks are expected to modify the message and then return a single scalar containing\nthat modified message. These callbacks will be called when either the \"log\" or \"logto\"\nmethods are called and will only be applied to a given message once. If they do not return\nthe message then you will get no output. Make sure to return the message!\n\n$dispatch->clone()\nThis returns a *shallow* clone of the original object. The underlying output objects and\ncallbacks are shared between the two objects. However any changes made to the outputs or\ncallbacks that the object contains are not shared.\n\n$dispatch->log( level => $, message => $ or \\& )\nSends the message (at the appropriate level) to all the output objects that the dispatcher\ncontains (by calling the \"logto\" method repeatedly).\n\nThe level can be specified by name or by an integer from 0 (debug) to 7 (emergency).\n\nThis method also accepts a subroutine reference as the message argument. This reference will be\ncalled only if there is an output that will accept a message of the specified level.\n\n$dispatch->debug (message), info (message), ...\nYou may call any valid log level (including valid abbreviations) as a method with a single\nargument that is the message to be logged. This is converted into a call to the \"log\" method\nwith the appropriate level.\n\nFor example:\n\n$log->alert('Strange data in incoming request');\n\ntranslates to:\n\n$log->log( level => 'alert', message => 'Strange data in incoming request' );\n\nIf you pass an array to these methods, it will be stringified as is:\n\nmy @array = ('Something', 'bad', 'is', 'here');\n$log->alert(@array);\n\n# is equivalent to\n\n$log->alert(\"@array\");\n\nYou can also pass a subroutine reference, just like passing one to the \"log()\" method.\n\n$dispatch->loganddie( level => $, message => $ or \\& )\nHas the same behavior as calling \"log()\" but calls \"diewithmessage()\" at the end.\n\nYou can throw exception objects by subclassing this method.\n\nIf the \"carplevel\" parameter is present its value will be added to the current value of\n$Carp::CarpLevel.\n\n$dispatch->logandcroak( level => $, message => $ or \\& )\nA synonym for \"$dispatch-\"loganddie()>.\n\n$dispatch->logto( name => $, level => $, message => $ )\nSends the message only to the named object. Note: this will not properly handle a subroutine\nreference as the message.\n\n$dispatch->addcallback( $code )\nAdds a callback (like those given during construction). It is added to the end of the list of\ncallbacks. Note that this can also be called on individual output objects.\n\n$dispatch->removecallback( $code )\nRemove the given callback from the list of callbacks. Note that this can also be called on\nindividual output objects.\n\n$dispatch->callbacks()\nReturns a list of the callbacks in a given output.\n\n$dispatch->levelisvalid( $string )\nReturns true or false to indicate whether or not the given string is a valid log level. Can be\ncalled as either a class or object method.\n\n$dispatch->wouldlog( $string )\nGiven a log level, returns true or false to indicate whether or not anything would be logged for\nthat log level.\n\n$dispatch->is$level\nThere are methods for every log level: \"isdebug()\", \"iswarning()\", etc.\n\nThis returns true if the logger will log a message at the given level.\n\n$dispatch->add( Log::Dispatch::* OBJECT )\nAdds a new output object to the dispatcher. If an object of the same name already exists, then\nthat object is replaced, with a warning if $^W is true.\n\n$dispatch->remove($)\nRemoves the output object that matches the name given to the remove method. The return value is\nthe object being removed or undef if no object matched this.\n\n$dispatch->outputs()\nReturns a list of output objects.\n\n$dispatch->output( $name )\nReturns the output object of the given name. Returns undef or an empty list, depending on\ncontext, if the given output does not exist.\n\n$dispatch->diewithmessage( message => $, carplevel => $ )\nThis method is used by \"loganddie\" and will either die() or croak() depending on the value of\n\"message\": if it's a reference or it ends with a new line then a plain die will be used,\notherwise it will croak.\n", "subsections": [] }, "OUTPUT CLASSES": { "content": "An output class - e.g. Log::Dispatch::File or Log::Dispatch::Screen - implements a particular\nway of dispatching logs. Many output classes come with this distribution, and others are\navailable separately on CPAN.\n\nThe following common parameters can be used when creating an output class. All are optional.\nMost output classes will have additional parameters beyond these, see their documentation for\ndetails.\n\n* name ($)\n\nA name for the object (not the filename!). This is useful if you want to refer to the object\nlater, e.g. to log specifically to it or remove it.\n\nBy default a unique name will be generated. You should not depend on the form of generated\nnames, as they may change.\n\n* minlevel ($)\n\nThe minimum logging level this object will accept. Required.\n\n* maxlevel ($)\n\nThe maximum logging level this object will accept. By default the maximum is the highest\npossible level (which means functionally that the object has no maximum).\n\n* callbacks( \\& or [ \\&, \\&, ... ] )\n\nThis parameter may be a single subroutine reference or an array reference of subroutine\nreferences. These callbacks will be called in the order they are given and passed a hash\ncontaining the following keys:\n\n( message => $logmessage, level => $loglevel )\n\nThe callbacks are expected to modify the message and then return a single scalar containing\nthat modified message. These callbacks will be called when either the \"log\" or \"logto\"\nmethods are called and will only be applied to a given message once. If they do not return\nthe message then you will get no output. Make sure to return the message!\n\n* newline (0|1)\n\nIf true, a callback will be added to the end of the callbacks list that adds a newline to\nthe end of each message. Default is false, but some output classes may decide to make the\ndefault true.\n", "subsections": [] }, "LOG LEVELS": { "content": "The log levels that Log::Dispatch uses are taken directly from the syslog man pages (except that\nI expanded them to full words). Valid levels are:\n\ndebug\ninfo\nnotice\nwarning\nerror\ncritical\nalert\nemergency\n\nAlternately, the numbers 0 through 7 may be used (debug is 0 and emergency is 7). The syslog\nstandard of 'err', 'crit', and 'emerg' is also acceptable. We also allow 'warn' as a synonym for\n'warning'.\n", "subsections": [] }, "SUBCLASSING": { "content": "This module was designed to be easy to subclass. If you want to handle messaging in a way not\nimplemented in this package, you should be able to add this with minimal effort. It is generally\nas simple as subclassing Log::Dispatch::Output and overriding the \"new\" and \"logmessage\"\nmethods. See the Log::Dispatch::Output docs for more details.\n\nIf you would like to create your own subclass for sending email then it is even simpler. Simply\nsubclass Log::Dispatch::Email and override the \"sendemail\" method. See the Log::Dispatch::Email\ndocs for more details.\n\nThe logging levels that Log::Dispatch uses are borrowed from the standard UNIX syslog levels,\nexcept that where syslog uses partial words (\"err\") Log::Dispatch also allows the use of the\nfull word as well (\"error\").\n", "subsections": [] }, "RELATED MODULES": { "content": "", "subsections": [ { "name": "Log::Dispatch::DBI", "content": "Written by Tatsuhiko Miyagawa. Log output to a database table.\n" }, { "name": "Log::Dispatch::FileRotate", "content": "Written by Mark Pfeiffer. Rotates log files periodically as part of its usage.\n" }, { "name": "Log::Dispatch::File::Stamped", "content": "Written by Eric Cholet. Stamps log files with date and time information.\n" }, { "name": "Log::Dispatch::Jabber", "content": "Written by Aaron Straup Cope. Logs messages via Jabber.\n" }, { "name": "Log::Dispatch::Tk", "content": "Written by Dominique Dumont. Logs messages to a Tk window.\n" }, { "name": "Log::Dispatch::Win32EventLog", "content": "Written by Arthur Bergman. Logs messages to the Windows event log.\n" }, { "name": "Log::Log4perl", "content": "An implementation of Java's log4j API in Perl. Log messages can be limited by fine-grained\ncontrols, and if they end up being logged, both native Log4perl and Log::Dispatch appenders can\nbe used to perform the actual logging job. Created by Mike Schilli and Kevin Goess.\n" }, { "name": "Log::Dispatch::Config", "content": "Written by Tatsuhiko Miyagawa. Allows configuration of logging via a text file similar (or so\nI'm told) to how it is done with log4j. Simpler than Log::Log4perl.\n" }, { "name": "Log::Agent", "content": "A very different API for doing many of the same things that Log::Dispatch does. Originally\nwritten by Raphael Manfredi.\n" } ] }, "SEE ALSO": { "content": "Log::Dispatch::ApacheLog, Log::Dispatch::Email, Log::Dispatch::Email::MailSend,\nLog::Dispatch::Email::MailSender, Log::Dispatch::Email::MailSendmail,\nLog::Dispatch::Email::MIMELite, Log::Dispatch::File, Log::Dispatch::File::Locked,\nLog::Dispatch::Handle, Log::Dispatch::Output, Log::Dispatch::Screen, Log::Dispatch::Syslog\n", "subsections": [] }, "SUPPORT": { "content": "Bugs may be submitted at .\n\nI am also usually active on IRC as 'autarch' on \"irc://irc.perl.org\".\n", "subsections": [] }, "SOURCE": { "content": "The source code repository for Log-Dispatch can be found at\n.\n", "subsections": [] }, "DONATIONS": { "content": "If you'd like to thank me for the work I've done on this module, please consider making a\n\"donation\" to me via PayPal. I spend a lot of free time creating free software, and would\nappreciate any support you'd care to offer.\n\nPlease note that I am not suggesting that you must do this in order for me to continue working\non this particular software. I will continue to do so, inasmuch as I have in the past, for as\nlong as it interests me.\n\nSimilarly, a donation made in this way will probably not make me work on this software much\nmore, unless I get so many donations that I can consider working on free software full time\n(let's all have a chuckle at that together).\n\nTo donate, log into PayPal and send money to autarch@urth.org, or use the button at\n.\n", "subsections": [] }, "AUTHOR": { "content": "Dave Rolsky \n", "subsections": [] }, "CONTRIBUTORS": { "content": "* Anirvan Chatterjee \n\n* Carsten Grohmann \n\n* Doug Bell \n\n* Graham Knop \n\n* Graham Ollis \n\n* Gregory Oschwald \n\n* hartzell \n\n* Joelle Maslak \n\n* Johann Rolschewski \n\n* Jonathan Swartz \n\n* Karen Etheridge \n\n* Kerin Millar \n\n* Kivanc Yazan \n\n* Konrad Bucheli \n\n* Michael Schout \n\n* Olaf Alders \n\n* Olivier Mengué \n\n* Rohan Carly \n\n* Ross Attrill \n\n* Salvador Fandiño \n\n* Sergey Leschenko \n\n* Slaven Rezic \n\n* Steve Bertrand \n\n* Whitney Jackson \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is Copyright (c) 2020 by Dave Rolsky.\n\nThis is free software, licensed under:\n\nThe Artistic License 2.0 (GPL Compatible)\n\nThe full text of the license can be found in the LICENSE file included with this distribution.\n", "subsections": [] } } } }