view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    For the sake of completeness, you can also specify element trees and
    queries using named parameters:

        $query = HTML::Query->new( tree  => $tree );
        $query = HTML::Query->new( query => $query );

    You can freely mix and match elements, queries and named sources. The
    query will be constructed as an aggregate across them all.

        $q = HTML::Query->new(
            text  => $text1,
            text  => $text2,
            file  => $file1,
            file  => $file2,
            tree  => $tree,
            query => $query1,
        );

    The final, optional argument can be a selector specification. This is
    immediately passed to the query() method which will return a new query
    with only those elements selected.

        my $spec = 'ul.menu li a';              # <ul class="menu">..<li>..<a>

        my $query = HTML::Query->new( $tree, $spec );
        my $query = HTML::Query->new( text => $text, $spec );
        my $query = HTML::Query->new(
            text => $text,
            file => $file,
            $spec
        );

    The list of arguments can also be passed by reference to a list.

        my $query = HTML::Query->new(\@args);

  query($spec)
    This method locates the descendant elements identified by the $spec
    argument for each element in the query. It then interally stores the
    results for requerying or return. See get_elements().

        my $query = HTML::Query->new(\@args);
        my $results = $query->query($spec);

    See "QUERY SYNTAX" for the permitted syntax of the $spec argument.

  get_elements()
    This method returns the stored results from a query. In list context it
    returns a list of matching HTML::Element objects. In scalar context it
    returns a reference to the results array.

        my $query = HTML::Query->new(\@args);
        my $results = $query->query($spec);

        my @elements  = $results->query($spec)->get_elements();
        my $elements  = $results->query($spec)->get_elements();

  get_specificity()
    Calculate the specificity for any given passed selector, a critical
    factor in determining how best to apply the cascade

    A selector's specificity is calculated as follows:

    * count the number of ID attributes in the selector (= a) * count the
    number of other attributes and pseudo-classes in the selector (= b) *
    count the number of element names in the selector (= c) * ignore
    pseudo-elements.

    The specificity is based only on the form of the selector. In
    particular, a selector of the form "[id=p33]" is counted as an attribute
    selector (a=0, b=0, c=1, d=0), even if the id attribute is defined as an
    "ID" in the source document's DTD.

    See the following spec for additional details:
    <http://www.w3.org/TR/CSS21/cascade.html#specificity>

  size()
    Returns the number of elements in the query.

  first()
    Returns the first element in the query.

        my $elem = $query->first;

    If the query is empty then an exception will be thrown. If you would
    rather have an undefined value returned then you can use the "try"
    method inherited from Badger::Base. This effectively wraps the call to
    "first()" in an "eval" block to catch any exceptions thrown.

        my $elem = $query->try('first') || warn "no first element\n";

  last()
    Similar to first(), but returning the last element in the query.

        my $elem = $query->last;

  list()
    Returns a list of the HTML::Element object in the query in list context,
    or a reference to a list in scalar context.

        my @elems = $query->list;
        my $elems = $query->list;

  AUTOLOAD
    The "AUTOLOAD" method maps any other method calls to the HTML::Element
    objects in the list. When called in list context it returns a list of
    the values returned from calling the method on each element. In scalar
    context it returns a reference to a list of return values.

        my @text_blocks = $query->as_trimmed_text;
        my $text_blocks = $query->as_trimmed_text;

KNOWN BUGS
  Attribute Values
    It is not possible to use "]" in an attribute value. This is due to a
    limitation in the parser which will be fixed RSN.

AUTHOR
    Andy Wardley <http://wardley.org>

MAINTAINER
    Kevin Kamel <kamelkev@mailermailer.com>

CONTRIBUTORS
    Vivek Khera <vivek@khera.org> Michael Peters <wonko@cpan.org> David Gray
    <cpan@doesntsuck.com>

COPYRIGHT
    Copyright (C) 2010 Andy Wardley. All Rights Reserved.

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

SEE ALSO
    HTML::Tree, HTML::Element, HTML::TreeBuilder, pQuery,