NAME
POE::Component::WebService::Validator::CSS::W3C - non-blocking access to
CSS validator.
SYNOPSIS
use strict;
use warnings;
use POE qw(Component::WebService::Validator::CSS::W3C);
my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn;
POE::Session->create(
package_states => [
main => [ qw( _start validated ) ],
],
);
$poe_kernel->run;
sub _start {
$poco->validate( {
event => 'validated',
uri => 'http://zoffix.com',
}
);
}
sub validated {
my $input = $_[ARG0];
if ( $input->{request_error} ) {
print "Failed to access validator: $input->{request_error}\n";
}
else {
if ( $input->{is_valid} ) {
printf "%s is valid! See %s for proof\n",
@$input{ qw(uri request_uri) };
}
else {
printf "%s contains %d error(s), see %s\nErrors are:\n",
@$input{ qw(uri num_errors request_uri) };
printf " %s on line %d\n",
@$_{ qw(message line) }
for @{ $input->{errors} };
}
}
$poco->shutdown;
}
Using the event based interface is also possible.
DESCRIPTION
The module is a non-blocking POE wrapper around
WebService::Validator::CSS::W3C which provides access to W3C CSS
validator ( )
CONSTRUCTOR
spawn
my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn;
POE::Component::WebService::Validator::CSS::W3C->spawn(
alias => 'val'
);
The constructor returns a
POE::Component::WebService::Validator::CSS::W3C object, though you don't
need to store it anywhere if you set the "alias" argument (see below).
Takes a few *optional* arguments which are as follows:
alias
POE::Component::WebService::Validator::CSS::W3C->spawn(
alias => 'val'
);
Optional. Specifies a POE Session alias for the component.
ua
my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
ua => LWP::UserAgent->new( timeout => 10 ),
);
Optional. Takes an LWP::UserAgent object which will be used to access
W3C validator. If not specified the LWP::UserAgent with its defaults
will be used, *with the exception* of "timeout" which will be set to 30
seconds.
val_uri
my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
val_uri => 'http://jigsaw.w3.org/css-validator/validator',
);
Specifies the URI of the CSS validator to access. Defaults to:
"http://jigsaw.w3.org/css-validator/validator", however you are strongly
encouraged install local validator, see
for details.
options
my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
options => {
trace => 1,
default => 1,
},
);
Optional. A hashref of POE Session options to pass to the component's
session. No options are set by default.
debug
my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
debug => 1
);
When set to a true value turns on output of debug messages. Defaults to:
0.
METHODS
These are the object-oriented methods of the components.
validate
$poco->validate( {
event => 'validated', # mandatory
uri => 'http://zoffix.com', # this or 'string' must be here
}
);
$poco->validate( {
event => 'event_to_send_results_to', # mandatory
string => '#foo { display: none; }', # this or 'uri' must be
medium => 'print', # this one and all below is optional
profile => 'css3',
warnings => 2,
language => 'de',
session => 'other_session_to_get_results',
_user => rand(), # user defined args
_any => 'other',
}
);
Takes hashref of options. See "validate" event below for description.
session_id
my $val_session_id = $poco->session_id;
Takes no arguments. Returns component's session ID.
shutdown
$poco->shutdown;
Takes no arguments. Shuts down the component.
ACEPTED EVENTS
validate
$poe_kernel->post( val => validate => {
event => 'validated', # mandatory
uri => 'http://zoffix.com', # this or 'string' must be here
}
);
$poe_kernel->post( val => validate => {
event => 'event_to_send_results_to', # mandatory
string => '#foo { display: none; }', # this or 'uri' must be
medium => 'print', # this one and all below is optional
profile => 'css3',
warnings => 2,
language => 'de',
session => 'other_session_to_get_results',
_user => rand(), # user defined args
_any => 'other',
}
);
Instructs the component to validate some CSS code, which can be passed
either in a form of a scalar or in a form of a URI to the page. Options
are passed in a hashref with keys as follows:
event
{ event => 'validation_result' }
Mandatory. An event to send the result to.
uri
{ uri => 'http://zoffix.com' }
Semi-mandatory. Either "uri" or "string" (see below) must be specified.
The "uri" key instructs the validator to validate the page specified in
the value.
string
{ string => '#foo { display: block; }' }
Semi-mandatory. Either "string" or "uri" (see above) must be specified.
The "string" key instructs the validator to validate CSS code specified
as the value.
medium
{ medium => 'print' }
Optional. Specifies the media type of CSS to check against. Should be
one of "aural", "braille", "embossed", "handheld", "print", "screen",
"tty", "tv", and "presentation". A special value "all" can also be
specified which means all media types. Defaults to: "undef" which means
validator will use its default, which currently is "all".
profile
{ profile => 'css3' }
Specifies the CSS version to check against. Legal values are "css1",
"css2", "css21", "css3", "svg", "svgbasic", "svgtiny", "mobile",
"atsc-tv", and "tv". A special value "none" can also be used. Defaults
to: "undef" which tells the W3C validator to use its default, which
currently defaults to "css21".
warnings
{ warnings => 2 }
An integer 0 - 10 that determines how many warning messages you want to
get back from the CSS Validator, 0 means no warnings, 10 would give most
warnings, but is currently effectively the same as 1. The defaut is
undef in which case the CSS Validator determines a default value; this
is expected to be as if 2 had been specified. NOTE: there seems to be a
discrepancy in WebService::Validator::CSS::W3C documentation and '0'
defaults to "Most Important", '1' => 'Normal', '2' => 'All' and value
"no", or default is "No warnings". The bug report has been submitted and
hopefully this will be resolved soon. Use "warnings" option with caution
until this note is removed.
language
{ language => 'de' }
The desired language of the supposedly human-readable messages. The
string will passed as an Accept-Language header in the HTTP request. The
CSS Validator currently supports "en", "de", "fr", "ja", "nl", "zh", and
"zh-cn".
session
{ session => $some_other_session_ref }
{ session => 'some_alias' }
{ session => $session->ID }
Optional. An alternative session alias, reference or ID that the
response should be sent to, defaults to sending session.
user defined
Optional. Any keys starting with "_" (underscore) will not affect the
component and will be passed back in the result intact.
shutdown
$poe_kernel->post( 'calc' => 'shutdown' );
Takes no arguments. Tells the component to shut itself down.
OUTPUT
$VAR1 = {
'result' => 1,
'is_valid' => 0,
'num_errors' => '1',
'errors' => [
$VAR1->{'som'}{'_content'}[2][0][2][0][2][5][2][0][2][1][2][1][4]
],
'uri' => 'google.ca',
'request_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca&output=soap12')}, 'URI::http' ),
'refer_to_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca')}, 'URI::http' ),
'http_response' => bless( { blah }, 'HTTP::Response' ),
'som' => bless( { blah }, 'SOAP::SOM' ),
'val_uri' => 'http://jigsaw.w3.org/css-validator/validator',
'num_warnings' => '0',
'warnings' => [],
};
The result will be posted to the event and (optional) session specified
in the arguments to the "validate" (event or method). The result, in the
form of a hashref, will be passed in "ARG0". The keys of that hashref
are as follows:
result
{ 'result' => 1 }
Whill contain either a true or false value. The false value will
indicate that we failed to access the validator, use "request_error" key
(see below) to determine the reason. If the value is true - we
successfully accessed the validator (note that it doesn't mean that the
code was valid)
request_error
{ request_error => '500: Request timed out' }
If we could not access the validator (i.e. "result" contains a false
value) then the "request_error" key will contain the description of the
error.
is_valid
{ is_valid => 0 }
Will contain either a true or false value. If contains a true value the
CSS code which was validate does not contain errors. If "is_valid" key
contains a false value - the CSS code is invalid.
num_errors
{ 'num_errors' => '1' }
Will contain the number of errors found in CSS code which was validated.
errors
printf "%s on line %d\n", @$_{ qw(message line) }
for @{ $_[ARG0]->{errors} };
This will contain an arrayref of hashrefs which represent errors. The
possible error hashref might be:
( {
context => 'p',
property => 'color',
expression => { start => '', end => 'not-a-color' }
errortype => 'parse-error',
message => 'not-a-color is not a color value',
line => 0,
} )
However, not all the keys will be present at all times.
uri
{ 'uri' => 'google.ca' }
If the "uri" argument was used to the "validate" event/method (as
opposed to "string") the "uri" key in the output will contain whatever
you've passed to "validate"
string
{ 'string' => '#foo { display: block; }' }
If the "string" argument was used to the "validate" event/method (as
opposed to "uri") the "string" key in the output will contain whatever
you've passed to "validate"
request_uri
{ 'request_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca&output=soap12')}, 'URI::http' ) }
Will contain a URI object which was used to access the validator.
refer_to_uri
{ 'refer_to_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca')}, 'URI::http' ), }
Will contain a URI object which you can use to direct people to the HTML
version of the validator output.
http_response
{ 'http_response' => bless( { blah }, 'HTTP::Response' ) }
The "http_response" key will contain an HTTP::Response object obtained
during the access to validator. You could perhaps examine it to find out
why you failed to access the validator.
val_uri
{ 'val_uri' => 'http://jigsaw.w3.org/css-validator/validator' }
The "val_uri" key will contain a URI of the CSS validator which was used
for validaton.
som
{ 'som' => bless( { blah }, 'SOAP::SOM' ), }
The SOAP::SOM object for the successful deserialization, check the
"result" key (see above) for a true value before using this object.
warnings
{ 'warnings' => [], }
The "warnings" key will contain an arrayref of warnings found in CSS
file (providing the warning level was set appropriately). Note: the docs
for WebService::Validator::CSS::W3C read:
Returns a list with information about the warnings found for the style
sheet. This is currently of limited use as it is broken, see
http://www.w3.org/Bugs/Public/show_bug.cgi?id=771 for details.
The validator bug shows as "RESOLVED", however I could not get any
warnings from WebService::Validator::CSS::W3C. If you can figure it out
drop me a line ;)
user defined
{ '_some' => 'other' }
Any arguments beginning with "_" (underscore) passed into the "validate"
event/method will be present intact in the result.
SEE ALSO
WebService::Validator::CSS::W3C, POE, LWP::UserAgent
AUTHOR
Zoffix Znet, "" ( ,
)
BUGS
Please report any bugs or feature requests to
"bug-poe-component-webservice-validator-css-w3c at rt.cpan.org", or
through the web interface at
. I will be notified, and then you'll automatically
be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc POE::Component::WebService::Validator::CSS::W3C
You can also look for information at:
* RT: CPAN's request tracker
* AnnoCPAN: Annotated CPAN documentation
* CPAN Ratings
* Search CPAN
COPYRIGHT & LICENSE
Copyright 2008 Zoffix Znet, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.