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.