/ 
POE-Component-Bundle-WebDevelopment-2.001001
River stage one • 2 direct dependents • 2 total dependents
/ POE::Component::WebService::Validator::HTML::W3C

NAME

POE::Component::WebService::Validator::HTML::W3C - a non-blocking POE wrapper around WebService::Validator::HTML::W3C

SYNOPSIS

use strict;
use warnings;

use POE qw(Component::WebService::Validator::HTML::W3C);

my $poco = POE::Component::WebService::Validator::HTML::W3C->spawn(
    alias => 'val',
);

POE::Session->create(
    package_states => [
        main => [ qw( _start validated ) ],
    ],
);

$poe_kernel->run;

sub _start {
    $poe_kernel->post( val => validate => {
            in => 'http://haslayout.net',
            event => 'validated',
        }
    );
}

sub validated {
    my ( $kernel, $input ) = @_[ KERNEL, ARG0 ];

    use Data::Dumper;
    print Dumper( $input );

    $poco->shutdown;
}

DESCRIPTION

The module provides a non-blocking POE wrapper around WebService::Validator::HTML::W3C

CONSTRUCTOR

POE::Component::WebService::Validator::HTML::W3C->spawn( alias => 'val' );

POE::Component::WebService::Validator::HTML::W3C->spawn(
    alias => 'val',
    debug => 1,
);

my $poco = POE::Component::WebService::Validator::HTML::W3C->spawn;

Returns a PoCo object. Takes three optional arguments:

alias

POE::Component::WebService::Validator::HTML::W3C->spawn( alias => 'val' );

Specifies a POE Kernel alias for the component.

options

POE::Component::WebService::Validator::HTML::W3C->spawn(
    options => {
        trace => 1,
        default => 1,
    },
);

A hashref of POE Session options to pass to the component's session.

debug

POE::Component::WebService::Validator::HTML::W3C->spawn( debug => 1 );

When set to a true value turns on output of debug messages.

METHODS

These are the object-oriented methods of the component.

validate

$poco->validate( {
        in => 'http://zoffix.com',
        event => 'validated',
        _random => 'bar',
    }
);

Method makes a validation request. Takes a single argument which is a hashref of options. See validate event for details.

session_id

my $tube_id = $poco->session_id;

Takes no arguments. Returns POE Session ID of the component.

shutdown

$poco->shutdown;

Takes no arguments. Shuts the component down.

ACCEPTED EVENTS

validate

$poe_kernel->post( val => validate => {
        in      => 'http://haslayout.net',
        event   => 'when_we_are_done', # everything below is optional
        session => 'some_other_session',
        _user   => 'something',
        _moar   => 'yet more',
        options => {
            http_timeout  => 10,
            validator_uri => 'http://local.plz/check',
            # and the rest of
            # WebService::Validator::HTML::W3C constructor options.
        },
        get_warnings => 1, # see description (below) before use
    },
);

$poe_kernel->post( val => validate => {
        in      => 'markup_file.html',
        type    => 'file',
        event   => 'done',
    },
);

$poe_kernel->post( val => validate => {
        in      => $some_markup_in_memory,
        type    => 'markup',
        event   => 'done',
    },
);

Takes one argument which is a hashref. Instructs the component to validate a webpage, markup from the file or markup stored in a scalar. The options hashref keys are as follows:

in

{ in => 'http://haslayout.net' }

{ in => 'filename.html' }

{ in => $markup_stored_just_like_that }

Mandatory. The value can be either the URI of the webpage, filename with markup to validate or markup stored in a plain scalar. Unless in key contains a URI to a webpage you must also set the type key to tell the component what you want to validate. Note: when in key represents a URI of the webpage it must be accessible by the validator.

event

{ event => 'we_are_done' }

Mandatory. The event to send the output to. See RESULTS section for information on how it will be sent. See session key (below) if you want to send the output to another session.

type

{ type => 'file' }

{ type => 'markup' }

Optional. This option specifies what exactly you gave the component in the in key. When type is set to file, the component will treat in key value as a filename of the file with the markup to validate. When type is set to markup, the component will treat the value of in key as a scalar containing a piece of markup to validate. Any other value will tell the component that the in key represents a URI of the webpage to validate. Defaults to uri (in contains a URI)

session

{ session => 'another_session' }

{ session => $another_session_ref }

{ session => $another_session_ID }

Optional. The value must be either an alias, a reference or an ID of an active session. When specified, the output will be sent to the session specified. Defaults to the sending session (the session that sends the validate event).

user defined keys

{ _user => 'something' }

{ _other => \@another }

Optional. Any keys starting with the _ (underscore) will be present in the results intact. Note: these will be passed through POE::Wheel::Run so values should be something that would survive the process.

options

{
    options => {
        http_timeout => 10,
        validator_uri => 'http://local/check',
        # and other WebService::Validator::HTML::W3C
        # constructor options.
    }
}

Optional. The value must be a hashref. This will be passed directly to the WebService::Validator::HTML::W3C constructor. See WebService::Validator::HTML::W3C new method for possible options.

get_warnings

{ get_warnings => 1 }

This will request the validator to get the warning messages. Note: the documentation of WebService::Validator::HTML::W3C reads:

ONLY available with the SOAP output from the development Validator at the moment.

I didn't have a chance to test this feature out, so use at your own risk and please report the bugs if you find any.

shutdown

$poe_kernel->post( val => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

RESULTS

sub validated {
    my ( $kernel, $results ) = @_[ KERNEL, ARG0 ];

    use Data::Dumper;
    print Dumper( $results );

    $poco->shutdown;
}

$VAR1 = {
      'errors' => [
                    {
                             'msg' => 'no document type declaration; implying "<!DOCTYPE HTML SYSTEM>"',
                             'col' => '0',
                             'line' => '1'
                      },
                    # and more and more of these
      ],
      'in' => 'http://google.ca',
      'num_errors' => '46',
      'validator_uri' => 'http://validator.w3.org/check',
      'type' => 'uri',
      'is_valid' => 0
    };


$VAR1 = {
      'options' => {
                     'http_timeout' => 2,
                     'validator_uri' => 'http://somewhereesle.com'
                   },
      '_user_defined' => 'something',
      'in' => 'http://zoffix.com',
      'validator_error' => 'Could not contact validator',
      'type' => 'uri',
      'validator_uri' => 'http://somewhereesle.com'
};

The event handler set up to handle the event you've specified in the event key of the validate event/method (and optionally the session you've specified in session key) will receive the results of the validation. The results will be returned in a form of a hashref in the ARG0. Some keys of the hashref will not be present if we failed to contact the validator or other reasons why we couldn't proceed with validation. The keys of the results hashref are as follows:

validator_error

if ( $results->{validator_error} ) {
    print "Could not validate: $results->{validator_error}\n";
}
else {
    # print out the results here.
}

If for some reason we could not perform the validation (for possible reasons see WebService::Validator::HTML::W3C's validator_error() method description), the validator_error key will be present containing the description of the error. If we successfully performed validation (the validation itself, not whether or not the HTML was valid) then this key will not be present in the results, thus you can use it to check for success.

is_valid

if ( $results->{is_valid} ) {
    print "Your document is valid! YEY!\n";
}
else {
    print "ZOMG! HTML WITH ERRORZ!\n";
    # print out error herer.
}

Set to either true or false value indicated whether or not the HTML document passed or failed validation. If it is set to true - document is valid, otherwise document contains errors. If document is valid the num_errors key will have 0 (zero) as a value and errors key will be set to undef. The is_valid key will NOT exist if {validator_error} is present.

num_errors

unless ( $results->{is_valid} ) {
    print "Your document contained: $results->{num_errors} errors\n";
}

The number (possibly a zero) of errors that validator found in your HTML. Note: this is NOT the number of elements in the {errors} key's arrayref, this is because {errors} will also have the entity was defined here type of messages which describe previous errors but not actually errors themselves. This key will NOT exist if {validator_error} is present.

errors

foreach my $error ( @{ $results->{errors} } ) {
   printf "line: %s, col: %s\n  error: %s\n\n",
                @$error{ qw( line col msg ) };

}

This key will NOT exist if {validator_error} is present, otherwise it will contain an arrayref, elements of which are hashrefs with the following keys:

msg

The textual description of an error

col

The column number of the HTML code where the error was spotted

line

The line number of the HTML code where the error was spotted.

Note: each element is NOT necessarily an error, but could also be the entity was defined here type of messages which describe previous errors but not actually errors themselves. If you think that should be different contact the author of WebService::Validator::HTML::W3C module.

type

if ( $results->{type} eq 'file' ) {
    print "I've validated file $results->{in}\n";
}
elsif ( $results->{type} eq 'markup' ) {
    print "I've validated markup which was: \n$results->{in}\n";
}
else {
    print "I've validated a URI $results->{in}\n";
    # note that if we get here then: $results->{type} eq 'uri'
}

This is the type of validation which was performed. Unless you've specified a proper type with type option in the validate event/method this key's value will be 'uri'. Otherwise it will be either 'file' or 'markup' (always lowercase).

in

print "These are the results for $results->{in}\n";

This will have whatever you have specified in the in option of the validate event/method.

validator_uri

print "Results provided by $results->{validator_uri}\n";

This will contain the URI of the validator which performed validation. Unless you've set { options => { validator_uri => 'http://something_else' } } in the validate method/event call, validator_uri key will contain 'http://validator.w3.org/check'

user specified arguments

print "User set $_ to $results->{ $_ }\n"
    for grep { /^_/ } keys %$results;

Any keys beginning with _ (underscore) which were specified to the validate method/event will be present intact in the result.

warnings

foreach my $warning ( @{ $results->{warnings} } ) {
   printf "line: %s, col: %s\n  warning: %s\n\n",
                @$warning{ qw( line col msg ) };
}

If get_warnings option is set in the validate method/event (and make sure to read its description before setting it!), the warnings key will be present in the results, value of which will be an arrayref. Each element of that arrayref will be a hashref, each having three keys:

msg

The textual description of a warning

col

The column number of the HTML code where the warning was spotted

line

The line number of the HTML code where the warning was spotted.

Note: this is untested. Read the description of get_warnings option of the validate event/method for the reason. Please report any bugs/discrepancies.

SEE ALSO

POE, WebService::Validator::HTML::W3C

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/POE-Component-Bundle-WebDevelopment

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/POE-Component-Bundle-WebDevelopment/issues

If you can't access GitHub, you can email your request to bug-POE-Component-Bundle-WebDevelopment at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.