NAME

       Log::Report::Dispatcher::File - send messages to a file or file-handle

INHERITANCE

        Log::Report::Dispatcher::File
          is a Log::Report::Dispatcher

SYNOPSIS

        dispatcher Log::Report::Dispatcher::File => 'stderr'
          , to => \*STDERR, accept => 'NOTICE-';

        # close a dispatcher
        dispatcher close => 'stderr';

        # let dispatcher open and close the file
        dispatcher FILE => 'mylog', to => '/var/log/mylog'
          , charset => 'utf-8';
        ...
        dispatcher close => 'mylog';  # will close file

        # open yourself, then also close yourself
        open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog'
            or fault "...";
        dispatcher FILE => 'mylog', to => \*OUT;
        ...
        dispatcher close => 'mylog';
        close OUT;

        # dispatch into a scalar
        my $output = '';
        open $outfile, '>', \$output;
        dispatcher FILE => 'into-scalar', to => \$outfile;
        ...
        dispatcher close => 'into-scalar';
        print $output;

DESCRIPTION

       This basic file logger accepts an file-handle or filename as destination.

       See documentation in the base class.

METHODS

       See documentation in the base class.

   Constructors
       See documentation in the base class.

       $obj->close()
           Only when initiated with a FILENAME, the file will be closed.  In any other case,
           nothing will be done.

       Log::Report::Dispatcher::File->new(TYPE, NAME, OPTIONS)
            -Option       --Defined in             --Default
             accept         Log::Report::Dispatcher  depend on mode
             charset        Log::Report::Dispatcher  LOCALE
             format_reason  Log::Report::Dispatcher  'LOWERCASE'
             locale         Log::Report::Dispatcher  <system locale>
             mode           Log::Report::Dispatcher  'NORMAL'
             replace                                 false
             to                                      <required>

           accept => REASONS
           charset => CHARSET
           format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
           locale => LOCALE
           mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
           replace => BOOLEAN
             Only used in combination with a FILENAME: throw away the old file if it exists.
             Probably you wish to append to existing information.

             Use the LOCALE setting by default, which is LC_CTYPE or LC_ALL or LANG (in that
             order).  If these contain a character-set which Perl understands, then that is used,
             otherwise silently ignored.

           to => FILENAME|FILEHANDLE|OBJECT
             You can either specify a FILENAME, which is opened in append mode with autoflush on.
             Or pass any kind of FILE-HANDLE or some OBJECT which implements a "print()" method.
             You probably want to have autoflush enabled on your FILE-HANDLES.

             When cleaning-up the dispatcher, the file will only be closed in case of a FILENAME.

   Accessors
       See documentation in the base class.

       $obj->filename()
           Returns the name of the opened file, or "undef" in case this dispatcher was started
           from a file-handle or file-object.

       $obj->isDisabled()
           See "Accessors" in Log::Report::Dispatcher

       $obj->mode()
           See "Accessors" in Log::Report::Dispatcher

       $obj->name()
           See "Accessors" in Log::Report::Dispatcher

       $obj->needs()
           See "Accessors" in Log::Report::Dispatcher

       $obj->type()
           See "Accessors" in Log::Report::Dispatcher

   Logging
       See documentation in the base class.

       $obj->collectLocation()
       Log::Report::Dispatcher::File->collectLocation()
           See "Logging" in Log::Report::Dispatcher

       $obj->collectStack([MAXDEPTH])
       Log::Report::Dispatcher::File->collectStack([MAXDEPTH])
           See "Logging" in Log::Report::Dispatcher

       $obj->log(HASH-of-OPTIONS, REASON, MESSAGE)
           See "Logging" in Log::Report::Dispatcher

       $obj->stackTraceLine(OPTIONS)
       Log::Report::Dispatcher::File->stackTraceLine(OPTIONS)
           See "Logging" in Log::Report::Dispatcher

       $obj->translate(HASH-of-OPTIONS, REASON, MESSAGE)
           See "Logging" in Log::Report::Dispatcher

DETAILS

       See documentation in the base class.

SEE ALSO

       This module is part of Log-Report distribution version 0.998, built on October 22, 2013.
       Website: http://perl.overmeer.net/log-report/

LICENSE

       Copyrights 2007-2013 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://www.perl.com/perl/misc/Artistic.html