NAME

URL::Transform - perform URL transformations in various document types

SYNOPSIS

    my $output;
    my $urlt = URL::Transform->new(
        'document_type'      => 'text/html;charset=utf-8',
        'content_encoding'   => 'gzip',
        'output_function'    => sub { $output .= "@_" },
        'transform_function' => sub { return (join '|', @_) },
    );
    $urlt->parse_file($Bin.'/data/URL-Transform-01.html');

    print "and this is the output: ", $output;

DESCRIPTION

URL::Transform is a generic module to perform an url transformation in a documents. Accepts callback function using which the url link can be changed.

There are different modules to handle different document types, elements or attributes:

text/html, text/vnd.wap.wml, application/xhtml+xml, application/vnd.wap.xhtml+xml

URL::Transform::using::HTML::Parser, URL::Transform::using::XML::SAX (incomplete was used only to benchmark)

text/css

URL::Transform::using::CSS::RegExp

text/html/meta-content

URL::Transform::using::HTML::Meta

application/x-javascript

URL::Transform::using::Remove

By passing parser option to the URL::Transform->new() constructor you can set what library will be used to parse and execute the output and transform functions. Note that the elements inside for example text/html that are of a different type will be transformed via "default_for($document_type)" modules.

transform_function is called with following arguments:

    transform_function->(
        'tag_name'       => 'img',
        'attribute_name' => 'src',
        'url'            => 'http://search.cpan.org/s/img/cpan_banner.png',
    );

and must return (un)modified url as the return value.

output_function is called with (already modified) document chunk for outputting.

PROPERTIES

    content_encoding
    document_type
    parser
    transform_function
    output_function

parser

For HTML/XML can be HTML::Parser, XML::SAX

document_type

    text/html - default

transform_function

Function that will be called to make the transformation. The function will receive one argument - url text.

output_function

Reference to function that will receive resulting output. The default one is to use print.

content_encoding

Can be set to gzip or deflate. By default it is undef, so there is no content encoding.

METHODS

new

Object constructor.

Requires transform_function a CODE ref argument.

The rest of the arguments are optional. Here is the list with defaults:

    document_type       => 'text/html;charset=utf-8',
    output_function     => sub { print @_ },
    parser              => 'HTML::Parser',
    content_encoding    => undef,

default_for($document_type)

Returns default parser for a supplied $document_type.

Can be used also as a set function with additional argument - parser name.

If called as object method set the default parser for the object. If called as module function set the default parser for a whole module.

parse_string($string)

Submit document as a string for parsing.

This some function must be implemented by helper parsing classes.

parse_chunk($chunk)

Submit chunk of a document for parsing.

This some function should be implemented by helper parsing classes.

can_parse_chunks

Return true/false if the parser can parse in chunks.

parse_file($file_name)

Submit file for parsing.

This some function should be implemented by helper parsing classes.

link_tags

    # To simplify things, reformat the %HTML::Tagset::linkElements
    # hash so that it is always a hash of hashes.

# Construct a hash of tag names that may have links.

js_attributes

# Construct a hash of all possible JavaScript attribute names

decode_string($string)

Will return decoded string suitable for parsing. Decoding is chosen according to the $self->content_encoding.

Decoding is run automatically for every chunk/string/file.

encode_string($string)

Will return encoded string. Encoding is chosen according to the $self->content_encoding.

NOTE if you want to have your content encoded back to the $self->content_encoding you will have to run this method in your code. Argument to the output_function() are always plain text.

get_supported_content_encodings()

Returns hash reference of supported content encodings.

benchmarks

    Benchmark: timing 10000 iterations of HTML::Parser    , XML::LibXML::SAX, XML::SAX::PurePerl...
    HTML::Parser      :  3 wallclock secs ( 2.41 usr +  0.04 sys =  2.45 CPU) @ 4081.63/s (n=10000)
    XML::LibXML::SAX  : 29 wallclock secs (27.22 usr +  0.11 sys = 27.33 CPU) @ 365.90/s (n=10000)
    XML::SAX::PurePerl: 192 wallclock secs (180.62 usr +  0.50 sys = 181.12 CPU) @ 55.21/s (n=10000)

TODO

There are urls in pics meta tag: <meta http-equiv="pics-label" content=" .... See http://www.w3.org/PICS/.

SEE ALSO

HTML::Parser, URL::Transform::using::HTML::Parser

AUTHOR

Jozef Kutej <jkutej at cpan.org>

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm URL::Transform

perl -MCPAN -e shell
install URL::Transform