http::proxy::bodyfilter::htmlparser(3pm) [debian man page]

HTTP::Proxy::BodyFilter::htmlparser(3pm)		User Contributed Perl Documentation		  HTTP::Proxy::BodyFilter::htmlparser(3pm)

NAME

       HTTP::Proxy::BodyFilter::htmlparser - Filter using HTML::Parser

SYNOPSIS

	   use HTTP::Proxy::BodyFilter::htmlparser;

	   # $parser is a HTML::Parser object
	   $proxy->push_filter(
	       mime	=> 'text/html',
	       response => HTTP::Proxy::BodyFilter::htmlparser->new( $parser );
	   );

DESCRIPTION

       The HTTP::Proxy::BodyFilter::htmlparser lets you create a filter based on the HTML::Parser object of your choice.

       This filter takes a HTML::Parser object as an argument to its constructor.  The filter is either read-only or read-write. A read-only
       filter will not allow you to change the data on the fly. If you request a read-write filter, you'll have to rewrite the response-body
       completely.

       With a read-write filter, you must recreate the whole body data. This is mainly due to the fact that the HTML::Parser has its own buffering
       system, and that there is no easy way to correlate the data that triggered the HTML::Parser event and its original position in the chunk
       sent by the origin server. See below for details.

       Note that a simple filter that modify the HTML text (not the tags) can be created more easily with HTTP::Proxy::BodyFilter::htmltext.

   Creating a HTML::Parser that rewrites pages
       A read-write filter is declared by passing "rw => 1" to the constructor:

	    HTTP::Proxy::BodyFilter::htmlparser->new( $parser, rw => 1 );

       To be able to modify the body of a message, a filter created with HTTP::Proxy::BodyFilter::htmlparser must rewrite it completely. The
       HTML::Parser object can update a special attribute named "output".  To do so, the HTML::Parser handler will have to request the "self"
       attribute (that is to say, require access to the parser itself) and update its "output" key.

       The following attributes are added to the HTML::Parser object by this filter:

       output
	   A string that will hold the data sent back by the proxy.

	   This string will be used as a replacement for the body data only if the filter is read-write, that is to say, if it was initialised
	   with "rw => 1".

	   Data should always be appended to "$parser->{output}".

       message
	   A reference to the HTTP::Message that triggered the filter.

       protocol
	   A reference to the HTTP::Protocol object.

METHODS

       This filter defines three methods, called automatically:

       filter()
	   The "filter()" method handles all the interactions with the HTML::Parser object.

       init()
	   Initialise the filter with the HTML::Parser object passed to the constructor.

       will_modify()
	   This method returns a boolean value that indicates to the system if it will modify the data passing through. The value is actually the
	   value of the "rw" parameter passed to the constructor.

SEE ALSO

       HTTP::Proxy, HTTP::Proxy::Bodyfilter, HTTP::Proxy::BodyFilter::htmltext.

AUTHOR

       Philippe "BooK" Bruhat, <book@cpan.org>.

COPYRIGHT

       Copyright 2003-2006, Philippe Bruhat.

LICENSE

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

perl v5.12.4							    2011-07-03				  HTTP::Proxy::BodyFilter::htmlparser(3pm)

HTTP::Proxy::BodyFilter(3pm)				User Contributed Perl Documentation			      HTTP::Proxy::BodyFilter(3pm)

NAME

       HTTP::Proxy::BodyFilter - A base class for HTTP messages body filters

SYNOPSIS

	   package MyFilter;

	   use base qw( HTTP::Proxy::BodyFilter );

	   # a simple modification, that may break things
	   sub filter {
	       my ( $self, $dataref, $message, $protocol, $buffer ) = @_;
	       $$dataref =~ s/PERL/Perl/g;
	   }

	   1;

DESCRIPTION

       The HTTP::Proxy::BodyFilter class is used to create filters for HTTP request/response body data.

   Creating a BodyFilter
       A BodyFilter is just a derived class that implements some methods called by the proxy. Of all the methods presented below, only "filter()"
       must be defined in the derived class.

       filter()
	   The signature of the filter() method is the following:

	       sub filter {
		   my ( $self, $dataref, $message, $protocol, $buffer ) = @_;
		   ...
	       }

	   where $self is the filter object, $dataref is a reference to the chunk of body data received, $message is a reference to either a
	   HTTP::Request or a HTTP::Response object, and $protocol is a reference to the LWP::Protocol protocol object.

	   Note that this subroutine signature looks a lot like that of the call- backs of LWP::UserAgent (except that $message is either a
	   HTTP::Request or a HTTP::Response object).

	   $buffer is a reference to a buffer where some of the unprocessed data can be stored for the next time the filter will be called (see
	   "Using a buffer to store data for a later use" for details). Thanks to the built-in HTTP::Proxy::BodyFilter::* filters, this is rarely
	   needed.

	   It is possible to access the headers of the message with "$message->headers()". This HTTP::Headers object is the one that was sent to
	   the client (if the filter is on the response stack) or origin server (if the filter is on the request stack). Modifying it in the
	   filter() method is useless, since the headers have already been sent.

	   Since $dataref is a reference to the data string, the referent can be modified and the changes will be transmitted through the filters
	   that follows, until the data reaches its recipient.

	   A HTTP::Proxy::BodyFilter object is a blessed hash, and the base class reserves only hash keys that start with "_hpbf".

       new()
	   The constructor is defined for all subclasses. Initialisation tasks (if any) for subclasses should be done in the "init()" method (see
	   below).

       init()
	   This method is called by the "new()" constructeur to perform all initisalisation tasks. It's called once in the filter lifetime.

	   It receives all the parameters passed to "new()".

       begin()
	   Some filters might require initialisation before they are able to handle the data. If a "begin()" method is defined in your subclass,
	   the proxy will call it before sending data to the "filter()" method.

	   It's called once per HTTP message handled by the filter, before data processing begins.

	   The method signature is as follows:

	       sub begin {
		   my ( $self, $message ) = @_
		   ...
	       }

       end()
	   Some filters might require finalisation after they are finished handling the data. If a "end()" method is defined in your subclass, the
	   proxy will call it after it has finished sending data to the "filter()" method.

	   It's called once per HTTP message handled by the filter, after all data processing is done.

	   This method does not expect any parameters.

       will_modify()
	   This method return a boolean value that indicate if the filter will modify the body data on the fly.

	   The default implementation returns a true value.

   Using a buffer to store data for a later use
       Some filters cannot handle arbitrary data: for example a filter that basically lowercases tag name will apply a simple regex such as
       "s/<s*(w+)([^>]*)>/<L$1E$2>/g".  But the filter will fail is the chunk of data contains a tag that is cut before the final ">".

       It would be extremely complicated and error-prone to let each filter (and its author) do its own buffering, so the HTTP::Proxy architecture
       handles this too. The proxy passes to each filter, each time it is called, a reference to an empty string ($buffer in the above signature)
       that the filter can use to store some data for next run.

       When the reference is "undef", it means that the filter cannot store any data, because this is the very last run, needed to gather all the
       data left in all buffers.

       It is recommended to store as little data as possible in the buffer, so as to avoid (badly) reproducing what
       HTTP::Proxy::BodyFilter::complete does.

       In particular, you have to remember that all the data that remains in the buffer after the last piece of data is received from the origin
       server will be sent back to your filter in one big piece.

   The store and forward approach
       HTTP::Proxy implements a store and forward mechanism, for those filters which need to have the whole message body to work. It's enabled
       simply by pushing the HTTP::Proxy::BodyFilter::complete filter on the filter stack.

       The data is stored in memory by the "complete" filter, which passes it on to the following filter once the full message body has been
       received.

   Standard BodyFilters
       Standard HTTP::Proxy::BodyFilter classes are lowercase.

       The following BodyFilters are included in the HTTP::Proxy distribution:

       lines
	   This filter makes sure that the next filter in the filter chain will only receive complete lines. The "chunks" of data received by the
	   following filters with either end with "
" or will be the last piece of data for the current HTTP message body.

       htmltext
	   This class lets you create a filter that runs a given code reference against text included in a HTML document (outside "<script>" and
	   "<style>" tags). HTML entities are not included in the text.

       htmlparser
	   Creates a filter from a HTML::Parser object.

       simple
	   This class lets you create a simple body filter from a code reference.

       save
	   Store the message body to a file.

       complete
	   This filter stores the whole message body in memory, thus allowing some actions to be taken only when the full page has been received
	   by the proxy.

       tags
	   The HTTP::Proxy::BodyFilter::tags filter makes sure that the next filter in the filter chain will only receive complete tags. The
	   current implementation is not 100% perfect, though.

       Please read each filter's documentation for more details about their use.

USEFUL METHODS FOR SUBCLASSES

       Some methods are available to filters, so that they can eventually use the little knowledge they might have of HTTP::Proxy's internals.
       They mostly are accessors.

       proxy()
	   Gets a reference to the HTTP::Proxy objects that owns the filter.  This gives access to some of the proxy methods.

AUTHOR

       Philippe "BooK" Bruhat, <book@cpan.org>.

SEE ALSO

       HTTP::Proxy, HTTP::Proxy::HeaderFilter.

COPYRIGHT

       Copyright 2003-2005, Philippe Bruhat.

LICENSE

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

perl v5.12.4							    2011-07-03					      HTTP::Proxy::BodyFilter(3pm)