NAME
    FirePHP::Dispatcher - sends log messages to a FirePHP console

SYNOPSIS
     use FirePHP::Dispatcher;

     my $fire_php = FirePHP::Dispatcher->new(
       $reference_to_http_headers_of_current_request
     );

     $fire_php->log( 'Hello world' );

     $fire_php->start_group( 'Levels:' );
     $fire_php->info ( 'Log informational message' );
     $fire_php->warn ( 'Log warning message' );
     $fire_php->error( 'Log error message' );
     $fire_php->end_group;

     $fire_php->start_group( 'Propably empty:' );
     $fire_php->dismiss_group;

     $fire_php->finalize;

DESCRIPTION
    FirePHP::Dispatcher implements the basic interface for logging to a
    FirePHP console. It is no logger on its own but rather a basic API that
    can be used by front-end loggers to divert or copy messages to a FirePHP
    console.

GENERAL METHODS
  $class->new( $http_headers )
    Creates a new instance of "FirePHP::Dispatcher" and binds it to the
    HTTP::Headers object given as parameter.

    Returns: a new "FirePHP::Dispatcher" object

  $self->finalize
    Add the needed protocol headers and meta infos to the HTTP::Headers
    object if anything has been logged to it. Without "finalize", FirePHP
    will ignore all messages.

LOGGING METHODS
  $self->log( $message )
    Log a plain message to the FirePHP console

  $self->info( $message )
    Log a informational message to the FirePHP console

    Returns: Return value

  $self->warn( $message )
    Log a warning message to the FirePHP console

  $self->error( $message )
    Log a error message to the FirePHP console

TABLE METHODS
  $self->table( $label, $table )
    Prints the FirePHP::SimpleTable or Text::SimpleTable object to the
    FirePHP console

GROUPING METHODS
  $self->start_group( $name )
    Starts a new, collapsable logging group named $name. Nesting groups is
    entirly possible.

  $self->dismiss_group
    Dismisses the current group. In later versions this will most propable
    delete contained messages. Right now just a warning is issued and the
    current group is closed with "end_group".

  $self->end_group
    Closes the current group and reenter the parent group if available.

  $self->end_or_dismiss_group
    Close the current group if it containes messages, otherwise just dismiss
    it.

INTERNAL METHODS
  $self->format_message( $attr, $message )
    Renders the message with the given attributs into a message string that
    is understood by FirePHP. In version 0.2 of the FirePHP protocol this
    means just an ordered JSON dump.

  $self->next_message_header
    Iterator for FirePHP headers. Calling it advances the internal message
    cursor so ensure that you either fill it or rollback the message.

    Returns: the next header field name for messages

  $self->rollback_last_message
    Rolls back the last message and decreases the message cursor. This can
    be used to dismiss groups and delete recent messages from the stack.

    CAVEAT: currently doesn't work correctly for multi-part messages that
    contain more than 5000 characters.

  %headers = $self->build_message_headers( $message )
    Builds the full header structure for the given message string
    automatically splitting it into multipart messages when the character
    limit of 5000 is reached. The message cursor will be advanced
    accordingly.

    Returns: a hash containing all HTTP headers representing the given
    message

  $self->send_headers( $message )
    Just a small wrapper that builds and sends all headers for the given
    message.

ACCESSORS
  $self->http_headers
    The bound HTTP::Headers object

  $self->message_index
    The number of messages already send (actually the message header cursor,
    you are responsible to ensure this is correct if you don't use the
    logging or iterator functions provided by this class)

  $self->stash
    A hasref that can be used by clients to store information about this
    logging session

  $self->json
    The "JSON" parser in use to format messages

  $self->group_stack
    Internal stack used to track groups

DEVELOPER NOTES
  PROTOCOL NOTES
    Header: X-Wf-1-[ STRUCTURE TYPE INDEX ]-1-[ MESSAGE INDEX ]

    Structure type index: 1 - LOG ( and most others? ) 2 - DUMP

    Content: [TOTAL LENGTH] \| \[ \{ [JSON MESSAGE PARAMS] \} \]

    Json message params: Type: LOG|TRACE|EXCEPTION|TABLE|DUMP

  EXAMPLE PURE HTTP SESSION
     $http_headers->push_header(
       'X-Wf-Protocol-1'     => 'http://meta.wildfirehq.org/' .
         'Protocol/JsonStream/0.2',
       'X-Wf-1-Plugin-1'     => 'http://meta.firephp.org/' .
         'Wildfire/Plugin/FirePHP/Library-FirePHPCore/0.2.0',
       'X-Wf-1-Structure-1'  => 'http://meta.firephp.org/' .
         'Wildfire/Structure/FirePHP/FirebugConsole/0.1',
     );

     $http_headers->push_header(
       'X-Wf-1-1-1-1' => '30|[{"Type":"LOG"},"Hell|\\',
       'X-Wf-1-1-1-2' => '|o Wo|\\',
       'X-Wf-1-1-1-3' => '|rld"]|',
     );

     $http_headers->push_header(
       'X-Wf-1-1-1-4' => '43|[{"Type":"GROUP_START","Label":"Foo"},null]|',
     );

     $http_headers->push_header(
       'X-Wf-1-1-1-6' => '33|[{"Type":"LOG"},"Hell|\\',
       'X-Wf-1-1-1-7' => '|o Wo|\\',
       'X-Wf-1-1-1-8' => '|rld!!!"]|',
     );

     $http_headers->push_header(
       'X-Wf-1-1-1-9' => '33|[{"Type":"LOG"},"Hell|\\',
       'X-Wf-1-1-1-10' => '|o again!!!"]|',
     );

     $http_headers->header(
       'X-Wf-1-1-1-11' => '27|[{"Type":"GROUP_END"},null]|',
     );

     $http_headers->header(
       'X-Wf-1-Structure-2'  => 'http://meta.firephp.org/' .
         'Wildfire/Structure/FirePHP/Dump/0.1',
     );

     $http_headers->push_header(
       'X-Wf-1-2-1-12' => '24|{"Dump":{"i":10,"j":20}}|',
     );

     $http_headers->header('X-Wf-1-Index', 12 );

SEE ALSO
    <http://www.firephp.org>, HTTP::Headers

AUTHOR
    Sebastian Willert, "willert@cpan.org"

COPYRIGHT AND LICENSE
    Copyright 2009 by Sebastian Willert <willert@cpan.org>

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

