File Coverage

lib/HTML/Query.pm

Criterion	Covered	Total	%
statement	225	237	94.9
branch	106	126	84.1
condition	31	39	79.4
subroutine	23	24	95.8
pod	8	11	72.7
total	393	437	89.9

package HTML::Query;

our $VERSION = '0.08';

use Badger::Class
    version   => $VERSION,
    debug     =>  0,
    base      => 'Badger::Base',
    utils     => 'blessed',
    import    => 'class CLASS',
    vars      => 'AUTOLOAD',
    constants => 'ARRAY',
    constant  => {
        ELEMENT => 'HTML::Element',
        BUILDER => 'HTML::TreeBuilder',
    },
    exports   => {
        any   => 'Query',
        hooks => {
            query => \&_export_query_to_element,
        },
    },
    messages  => {
        no_elements => 'No elements specified to query',
        no_query    => 'No query specified',
        no_source   => 'No argument specified for source: %s',
        bad_element => 'Invalid element specified: %s',
        bad_source  => 'Invalid source specified: %s',
        bad_query   => 'Invalid query specified: %s',
        bad_spec    => 'Invalid specification "%s" in query: %s',
        is_empty    => 'The query does not contain any elements',
    };

our $SOURCES = {
    text => sub {
        class(BUILDER)->load;
        BUILDER->new_from_content(shift);
    },
    file => sub {
        class(BUILDER)->load;
        BUILDER->new_from_file(shift);
    },
    tree => sub {
        $_[0]
    },
    query => sub {
        ref $_[0] eq ARRAY
            ? @{ $_[0] }
            :    $_[0];
    },
};

sub Query (@) {
    CLASS->new(@_);
}

sub new {
    my $class = shift;
    my ($element, @elements, $type, $code, $select);

    # expand a single list ref into items
    unshift @_, @{ shift @_ }
        if @_ == 1 && ref $_[0] eq ARRAY;

    $class = ref $class || $class;

    my $self = {
                error => undef,
                suppress_errors => undef,
                match_self => undef,
                elements => \@elements,
                specificity => {}
               };

    # each element should be an HTML::Element object, although we might
    # want to subclass this module to recognise a different kind of object,
    # so we get the element class from the ELEMENT constant method which a
    # subclass can re-define.
    my $element_class = $class->ELEMENT;

    while (@_) {
        $element = shift;
        $class->debug("argument: ".$element) if DEBUG;

        if (! ref $element) {
            # a non-reference item is a source type (text, file, tree)
            # followed by the source, or if it's the last argument following
            # one ore more element options or named argument pairs then it's
            # a selection query
            if (@_) {
                $type = $element;
                $code = $SOURCES->{ $type }
                    || return $class->error_msg( bad_source => $type );
                $element = shift;
                $class->debug("source $type: $element") if DEBUG;
                unshift(@_, $code->($element));
                next;
            }
            elsif (@elements) {
                $select = $element;
                last;
            }
        }
        elsif (blessed $element) {
            # otherwise it should be an HTML::Element object or another
            # HTML::Query object
            if ($element->isa($element_class)) {
                push(@elements, $element);
                next;
            }
            elsif ($element->isa($class)) {
                push(@elements, @{$element->get_elements});
                next;
            }
        }

        return $class->error_msg( bad_element => $element );
    }

    bless $self, $class;

    return defined $select ? $self->query($select) : $self;
}

sub query {
    my ($self, $query) = @_;
    my @result;
    my $ops = 0;
    my $pos = 0;

    $self->{error} = undef;

    return $self->error_msg('no_query')
        unless defined $query && length $query;

    # multiple specs can be comma separated, e.g. "table tr td, li a, div.foo"
    COMMA: while (1) {
        # each comma-separated traversal spec is applied downward from
        # the source elements in the $self->{elements} query
        my @elements = @{$self->get_elements};
        my $comops   = 0;

        my $specificity = 0;
        my $startpos = pos($query) || 0;

        my $hack_sequence = 0; # look for '* html'

        warn "Starting new COMMA" if DEBUG;

        # for each whitespace delimited descendant spec we grok the correct
        # parameters for look_down() and apply them to each source element
        # e.g. "table tr td"
        SEQUENCE: while (1) {
            my @args;
            $pos = pos($query) || 0;
            my $relationship = '';
            my $leading_whitespace;

            warn "Starting new SEQUENCE" if DEBUG;

            # ignore any leading whitespace
            if ($query =~ / \G (\s+) /cgsx) {
              $leading_whitespace = defined($1) ? 1 : 0;
              warn "removing leading whitespace\n" if DEBUG;
            }

            # grandchild selector is whitespace sensitive, requires leading whitespace
            if ($leading_whitespace && $comops && ($query =~ / \G (\*) \s+ /cgx)) {
              # can't have a relationship modifier as the first part of the query
              $relationship = $1;
              warn "relationship = $relationship\n" if DEBUG;
            }

            # get other relationship modifiers
            if ($query =~ / \G (>|\+) \s* /cgx) {
              # can't have a relationship modifier as the first part of the query
              $relationship = $1;
              warn "relationship = $relationship\n" if DEBUG;
              if (!$comops) {
                return $self->_report_error( $self->message( bad_spec => $relationship, $query ) );
              }
            }

            # optional leading word is a tag name
            if ($query =~ / \G ([\w\*]+) /cgx) {
              my $tag = $1;

              if ($tag =~ m/\*/) {
                if (($leading_whitespace || $comops == 0) && ($tag eq '*')) {
                  warn "universal tag\n" if DEBUG;
                  push(@args, _tag => qr/\w+/);

                  if ($comops == 0) {  #we need to catch the case where we see '* html'
                    $hack_sequence++;
                  }
                }
                else {
                  return $self->_report_error( $self->message( bad_spec => $tag, $query ) );
                }
              }
              else {
                warn "html tag\n" if DEBUG;
                $specificity += 1; # standard tags are worth 1 point
                push( @args, _tag => $tag );

                if ($comops == 1 && $tag eq 'html') {
                  $hack_sequence++;
                }
              }
            }

            # loop to collect a description about this specific part of the rule
            while (1) {
                my $work = scalar @args;

                # that can be followed by (or the query can start with) a #id
                if ($query =~ / \G \# ([\w\-]+) /cgx) {
                    $specificity += 100;
                    push( @args, id => $1 );
                }

                # and/or a .class
                if ($query =~ / \G \. ([\w\-]+) /cgx) {
                   $specificity += 10;
                   push( @args, class => qr/ (^|\s+) $1 ($|\s+) /x );
                }

                # and/or none or more [ ] attribute specs
                if ($query =~ / \G \[ (.*?) \] /cgx) {
                    my $attribute = $1;
                    $specificity += 10;

                    #if we have an operator
                    if ($attribute =~ m/(.*?)\s*([\|\~]?=)\s*(.*)/) {
                        my ($name,$attribute_op,$value) = ($1,$2,$3);

                        unless (defined($name) && length($name)) {
                             return $self->_report_error( $self->message( bad_spec => $name, $query ) );
                        }

                        warn "operator $attribute_op" if DEBUG;

                        if (defined $value) {
                            for ($value) {
                                s/^['"]//;
                                s/['"]$//;
                            }
                            if ($attribute_op eq '=') {
                                push( @args, $name => $value);
                            }
                            elsif ($attribute_op eq '|=') {
                                push(@args, $name => qr/\b${value}-?/)
                            }
                            elsif ($attribute_op eq '~=') {
                                push(@args, $name => qr/\b${value}\b/)
                            }
                            else {
                                return $self->_report_error( $self->message( bad_spec => $attribute_op, $query ) );
                            }
                        }
                        else {
                            return $self->_report_error( $self->message( bad_spec => $attribute_op, $query ) );
                        }
                    }
                    else {
                        unless (defined($attribute) && length($attribute)) {
                          return $self->_report_error( $self->message( bad_spec => $attribute, $query ) );
                        }

                        # add a regex to match anything (or nothing)
                        push( @args, $attribute => qr/.*/ );
                    }
                }
                # and/or one or more pseudo-classes
                if ($query =~ / \G : ([\w\-]+) /cgx) {
                    my $pseudoclass = $1;
                    $specificity += 10;

                    if ($pseudoclass eq 'first-child') {
                        push( @args, sub { ! grep { ref $_ } $_[0]->left() } );
                    } elsif ($pseudoclass eq 'last-child') {
                        push( @args, sub { ! grep { ref $_ } $_[0]->right() } );
                    } else {
                        warn "Pseudoclass :$pseudoclass not supported";
                        next;
                    }
                }

                # keep going until this particular expression is fully processed
                last unless scalar(@args) > $work;
            }

            # we must have something in @args by now or we didn't find any
            # valid query specification this time around
            last SEQUENCE unless @args;

            $self->debug(
                'Parsed ', substr($query, $pos, pos($query) - $pos),
                ' into args [', join(', ', @args), ']'
            ) if DEBUG;

            # we want to skip certain hack sequences like '* html'
            if ($hack_sequence == 2) {
              @elements = []; # clear out our stored elements to match behaviour of modern browsers
            }
            # we're just looking for any descendent
            elsif( !$relationship ) {
              if ($self->{match_self}) {
                # if we are re-querying, be sure to match ourselves not just descendents
                @elements = map { $_->look_down(@args) } @elements;
              } else {
                # look_down() will match self in addition to descendents,
                # so we explicitly disallow matches on self as we iterate
                # thru the list.  The other cases below already exclude self.
                # https://rt.cpan.org/Public/Bug/Display.html?id=58918
                my @accumulator;
                foreach my $e (@elements) {
                  if ($e->root() == $e) {
                    push(@accumulator, $e->look_down(@args));
                  }
                  else {
                    push(@accumulator, grep { $_ != $e } $e->look_down(@args));
                  }
                }
                @elements = @accumulator;
              }
            }
            # immediate child selector
            elsif( $relationship eq '>' ) {
              @elements = map {
                $_->look_down(
                  @args,
                  sub {
                    my $tag = shift;
                    my $root = $_;

                    return $tag->depth == $root->depth + 1;
                  }
                )
              } @elements;
            }
            # immediate sibling selector
            elsif( $relationship eq '+' ) {
              @elements = map {
                $_->parent->look_down(
                  @args,
                  sub {
                    my $tag = shift;
                    my $root = $_;
                    my @prev_sibling = $tag->left;
                    # get prev next non-text sibling
                    foreach my $sibling (reverse @prev_sibling) {
                      next unless ref $sibling;
                      return $sibling == $root;
                    }
                  }
                )
              } @elements;
            }
            # grandchild selector
            elsif( $relationship eq '*' ) {
              @elements = map {
                $_->look_down(
                  @args,
                  sub {
                    my $tag = shift;
                    my $root = $_;

                    return $tag->depth > $root->depth + 1;
                  }
                )
              } @elements;
            }

            # so we can check we've done something
            $comops++;

            # dedup the results we've gotten
            @elements = $self->_dedup(\@elements);

            map { warn $_->as_HTML } @elements if DEBUG;
        }

        if ($comops) {
            $self->debug(
                'Added', scalar(@elements), ' elements to results'
            ) if DEBUG;

            my $selector = substr ($query,$startpos, $pos - $startpos);
            $self->_add_specificity($selector,$specificity);

            #add in the recent pass
            push(@result,@elements);

            # dedup the results across the result sets, necessary for comma based selectors
            @result = $self->_dedup(\@result);

            # sort the result set...
            @result = sort _by_address @result;

            # update op counter for complete query to include ops performed
            # in this fragment
            $ops += $comops;
        }
        else {
            # looks like we got an empty comma section, e.g. : ",x, ,y,"
            # so we'll ignore it
        }

        last COMMA unless $query =~ / \G \s*,\s* /cgsx;
    }

    # check for any trailing text in the query that we couldn't parse
    if ($query =~ / \G (.+?) \s* $ /cgsx) {
        return $self->_report_error( $self->message( bad_spec => $1, $query ) );
    }

    # check that we performed at least one query operation
    unless ($ops) {
        return $self->_report_error( $self->message( bad_query => $query ) );
    }

    return wantarray ? @result : $self->_new_match_self(@result);
}

# return elements stored from last query
sub get_elements {
  my $self = shift;

  return wantarray ? @{$self->{elements}} : $self->{elements};
}

###########################################################################################################
# from CSS spec at http://www.w3.org/TR/CSS21/cascade.html#specificity
###########################################################################################################
# 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.
#
# Concatenating the three numbers a-b-c (in a number system with a large base) gives the specificity.
#
# Example(s):
#
# Some examples:
#
# *             {}  /* a=0 b=0 c=0 -> specificity =   0 */
# LI            {}  /* a=0 b=0 c=1 -> specificity =   1 */
# UL LI         {}  /* a=0 b=0 c=2 -> specificity =   2 */
# UL OL+LI      {}  /* a=0 b=0 c=3 -> specificity =   3 */
# H1 + *[REL=up]{}  /* a=0 b=1 c=1 -> specificity =  11 */
# UL OL LI.red  {}  /* a=0 b=1 c=3 -> specificity =  13 */
# LI.red.level  {}  /* a=0 b=2 c=1 -> specificity =  21 */
# #x34y         {}  /* a=1 b=0 c=0 -> specificity = 100 */
###########################################################################################################

=pod

=item 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:
L

=back

=cut

sub get_specificity {
  my ($self,$selector) = @_;

  unless (exists $self->{specificity}->{$selector}) {

   # if the invoking tree happened to be large this could get expensive real fast
   # instead load up an empty instance and query that.
   local $self->{elements} = [];
   $self->query($selector);
  }

  return $self->{specificity}->{$selector};
}

sub suppress_errors {
    my ($self, $setting) = @_;

    if (defined($setting)) {
      $self->{suppress_errors} = $setting;
    }

    return $self->{suppress_errors};
}

sub get_error {
    my ($self) = @_;

    return $self->{error};
}

sub list {
    # return list of items or return unblessed list ref of items
    return wantarray ? @{ $_[0] } : [ @{ $_[0] } ];
}

sub size {
  my $self = shift;
  return scalar @{$self->get_elements};
}

sub first {
    my $self = shift;

    return @{$self->get_elements} ? $self->get_elements->[0] : $self->error_msg('is_empty');
}

sub last {
    my $self = shift;

    return @{$self->get_elements} ? $self->get_elements->[-1] : $self->error_msg('is_empty');
}

####################################################################
#
# Everything below here is a private method subject to change
#
####################################################################

sub _add_specificity {
  my ($self, $selector, $specificity) = @_;

  $self->{specificity}->{$selector} = $specificity;

  return();
}

sub _report_error {
    my ($self, $message) = @_;

    if ($self->suppress_errors()) {
      if (defined($message)) {
        $self->{error} = $message;
      }
      return undef;
    }
    else {
      $self->error($message);   # this will DIE
    }
}

    # this Just Works[tm] because first arg is HTML::Element object
sub _export_query_to_element {
    class(ELEMENT)->load->method(
        query => \&Query,
    );
}

# remove duplicate elements in the case where elements are nested between multiple matching elements
sub _dedup {
  my ($self,$elements) = @_;

  my %seen = ();
  my @unique = ();

  foreach my $item (@{$elements}) {
    if (!exists($seen{$item})) {
      push(@unique, $item);
    }

    $seen{$item}++;
  }

  return @unique;
}

# utility method to assist in sorting of query return sets
sub _by_address
{
  my $self = shift;

  my @a = split /\./, $a->address();
  my @b = split /\./, $b->address();

  my $max = (scalar @a > scalar @b) ? scalar @a : scalar @b;

  for (my $index=0; $index<$max; $index++) {

    if (!defined($a[$index]) && !defined($b[$index])) {
      return 0;
    }
    elsif (!defined($a[$index])) {
      return -1;
    }
    elsif(!defined($b[$index])) {
      return 1;
    }

    if ($a[$index] == $b[$index]) {
      next; #move to the next
    }
    else {
      return $a[$index] <=> $b[$index];
    }
  }
}

# instantiate an instance with match_self turned on, for use with
# follow-up queries, so they match the top-most elements.
sub _new_match_self {
  my $self = shift;

  my $result = $self->new(@_);

  $result->{match_self} = 1;
  return $result;
}

sub AUTOLOAD {
    my $self     = shift;
    my ($method) = ($AUTOLOAD =~ /([^:]+)$/ );
    return if $method eq 'DESTROY';

    # we allow Perl to catch any unknown methods that the user might
    # try to call against the HTML::Element objects in the query
    my @results =
        map  { $_->$method(@_) }
        @{$self->get_elements};

    return wantarray ? @results : \@results;
}

1;

=head1 NAME

HTML::Query - jQuery-like selection queries for HTML::Element

=head1 SYNOPSIS

Creating an C object using the L constructor
subroutine:

    use HTML::Query 'Query';

    # using named parameters
    $q = Query( text  => $text  );          # HTML text
    $q = Query( file  => $file  );          # HTML file
    $q = Query( tree  => $tree  );          # HTML::Element object
    $q = Query( query => $query );          # HTML::Query object
    $q = Query(
        text  => $text1,                    # or any combination
        text  => $text2,                    # of the above
        file  => $file1,
        file  => $file2,
        tree  => $tree,
        query => $query,
    );

    # passing elements as positional arguments
    $q = Query( $tree );                    # HTML::Element object(s)
    $q = Query( $tree1, $tree2, $tree3, ... );

    # or from one or more existing queries
    $q = Query( $query1 );                  # HTML::Query object(s)
    $q = Query( $query1, $query2, $query3, ... );

    # or a mixture
    $q = Query( $tree1, $query1, $tree2, $query2 );

    # the final argument (in all cases) can be a selector
    my $spec = 'ul.menu li a';              # ....

    $q = Query( $tree, $spec );
    $q = Query( $query, $spec );
    $q = Query( $tree1, $tree2, $query1, $query2, $spec );
    $q = Query( text  => $text,  $spec );
    $q = Query( file  => $file,  $spec );
    $q = Query( tree  => $tree,  $spec );
    $q = Query( query => $query, $spec );
    $q = Query(
        text => $text,
        file => $file,
        # ...etc...
        $spec
    );

Or using the OO L constructor method (which the L
subroutine maps onto):

    use HTML::Query;

    $q = HTML::Query->new(
        # accepts the same arguments as Query()
    )

Or by monkey-patching a L method into L.

    use HTML::Query 'query';                # note lower case 'q'
    use HTML::TreeBuilder;

    # build a tree
    my $tree = HTML::TreeBuilder->new;
    $tree->parse_file($filename);

    # call the query() method on any element
    my $query = $tree->query($spec);

Once you have a query, you can start selecting elements:

    @r = $q->query('a')->get_elements();            # all ... elements
    @r = $q->query('a#menu')->get_elements();       # all  with "menu" id
    @r = $q->query('#menu')->get_elements();        # all elements with "menu" id
    @r = $q->query('a.menu')->get_elements();       # all  with "menu" class
    @r = $q->query('.menu')->get_elements();        # all elements with "menu" class
    @r = $q->query('a[href]')->get_elements();      # all  with 'href' attr
    @r = $q->query('a[href=foo]')->get_elements();  # all  with 'href="foo"' attr

    # you can specify elements within elements...
    @r = $q->query('ul.menu li a')->get_elements(); # ......

    # and use commas to delimit multiple path specs for different elements
    @r = $q->query('table tr td a, form input[type=submit]')->get_elements();

    # query() in scalar context returns a new query
    $r = $q->query('table')->get_elements();;       # find all tables
    $s = $r->query('tr')->get_elements();           # find all rows in all those tables
    $t = $s->query('td')->get_elements();           # and all cells in those rows...

Inspecting query elements:

    # get number of elements in query
    my $size  = $q->size

    # get first/last element in query
    my $first = $q->first;
    my $last  = $q->last;

    # convert query to list or list ref of HTML::Element objects
    my $list = $q->list;            # list ref in scalar context
    my @list = $q->list;            # list in list context

All other methods are mapped onto the L objects
in the query:

    print $query->as_trimmed_text;  # print trimmed text for each element
    print $query->as_HTML;          # print each element as HTML
    $query->delete;                 # call delete() on each element

=head1 DESCRIPTION

The C module is an add-on for the L module
set. It provides a simple way to select one or more elements from a tree using
a query syntax inspired by jQuery. This selector syntax will be reassuringly
familiar to anyone who has ever written a CSS selector.

C is not an attempt to provide a complete (or even near-complete)
implementation of jQuery in Perl (see Ingy's L module for a
more ambitious attempt at that). Rather, it borrows some of the tried and
tested selector syntax from jQuery (and CSS) that can easily be mapped onto
the C method provided by the L
module.

=head2 Creating a Query

The easiest way to create a query is using the exportable L
subroutine.

    use HTML::Query 'Query';        # note capital 'Q'

It accepts a C or C named parameter and will create an
C object from the HTML source text or file, respectively.

    my $query = Query( text => $text );
    my $query = Query( file => $file );

This delegates to L to parse the
HTML into a tree of L objects.  The root
element returned is then wrapped in an C object.

If you already have one or more L objects that
you want to query then you can pass them to the L subroutine as
arguments. For example, you can explicitly use
L to parse an HTML document into a tree:

    use HTML::TreeBuilder;
    my $tree = HTML::TreeBuilder->new;
    $tree->parse_file($filename);

And then create an C object for the tree either using an
explicit C named parameter:

    my $query = Query( tree => $tree );

Or implicitly using positional arguments.

    my $query = Query( $tree );

If you want to query across multiple elements, then pass each one as a
positional argument.

    my $query = Query( $tree1, $tree2, $tree3 );

You can also create a new query from one or more existing queries,

    my $query = Query( query => $query );   # named parameter
    my $query = Query( $query1, $query2 );  # positional arguments.

You can mix and match these different parameters and positional arguments
to create a query across several different sources.

    $q = Query(
        text  => $text1,
        text  => $text2,
        file  => $file1,
        file  => $file2,
        tree  => $tree,
        query => $query,
    );

The L subroutine is a simple wrapper around the L
constructor method. You can instantiate your objects manually if you prefer.
The L method accepts the same arguments as for the L
subroutine (in fact, the L subroutine simply forwards all
arguments to the L method).

    use HTML::Query;

    my $query = HTML::Query->new(
        # same argument format as for Query()
    );

A final way to use C is to have it add a L method
to L.  The C import hook (all lower
case) can be specified to make this so.

    use HTML::Query 'query';                # note lower case 'q'
    use HTML::TreeBuilder;

    my $tree = HTML::TreeBuilder->new;
    $tree->parse_file($filename);

    # now all HTML::Elements have a query() method
    my @items = $tree->query('ul li')->get_elements();  # find all list items

This approach, often referred to as I, should be used
carefully and sparingly. It involves a violation of
L's namespace that could have unpredictable
results with a future version of the module (e.g. one which defines its own
C method that does something different). Treat it as something that
is great to get a quick job done right now, but probably not something to be
used in production code without careful consideration of the implications.

=head2 Selecting Elements

Having created an C object by one of the methods outlined above,
you can now fetch descendant elements in the tree using a simple query syntax.
For example, to fetch all the C<< EaE >> elements in the tree, you can
write:

    @links = $query->query('a')->get_elements();

Or, if you want the elements that have a specific C attribute defined
with a value of, say C, you can write:

    @links = $query->query('a.menu')->get_elements();

More generally, you can look for the existence of any attribute and optionally
provide a specific value for it.

    @links = $query->query('a[href]')->get_elements();            # any href attribute
    @links = $query->query('a[href=index.html]')->get_elements(); # specific value

You can also find an element (or elements) by specifying an id.

    @links = $query->query('#menu')->get_elements();         # any element with id="menu"
    @links = $query->query('ul#menu')->get_elements();       # ul element with id="menu"

You can provide multiple selection criteria to find elements within elements
within elements, and so on.  For example, to find all links in a menu,
you can write:

    # matches:
    @links = $query->query('ul.menu li a')->get_elements();

You can separate different criteria using commas.  For example, to fetch all
table rows and C elements with a C class:

    @elems = $query->('table tr, span.foo')->get_elements();

=head2 Query Results

When called in list context, as shown in the examples above, the L
method returns a list of L objects matching the
search criteria. In scalar context, the L method returns a new
C object containing the L objects
found. You can then call the L method against that object to further
refine the query. The L method applies the selection to all elements
stored in the query.

    my $tables = $query->query('table');             # query for tables
    my $rows   = $tables->query('tr');               # requery for all rows in those tables
    my $cells  = $rows->query('td')->get_elements(); # return back all the cells in those rows

=head2 Inspection Methods

The L method returns the number of elements in the query. The
L and L methods return the first and last items in the
query, respectively.

    if ($query->size) {
        print "from ", $query->first->as_trimmed_text, " to ", $query->last->as_trimmed_text;
    }

If you want to extract the L objects from the
query you can call the L method. This returns a list of
L objects in list context, or a reference to a
list in scalar context.

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

=head2 Element Methods

Any other methods are automatically applied to each element in the list. For
example, to call the C method on all the
L objects in the query, you can write:

    print $query->as_trimmed_text;

In list context, this method returns a list of the return values from
calling the method on each element.  In scalar context it returns a
reference to a list of return values.

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

See L for further information on the methods it
provides.

=head1 QUERY SYNTAX

=head2 Basic Selectors

=head3 element

Matches all elements of a particular type.

    @elems = $query->query('table')->get_elements();     #  




960




 





 





 





 





 





 



   




961




 





 





 





 





 





 



 =head3 #id 




962




 





 





 





 





 





 



   




963




 





 





 





 





 





 



 Matches all elements with a specific id attribute. 




964




 





 





 





 





 





 



   




965




 





 





 





 





 





 



     @elems = $query->query('#menu')->get_elements()     #  




966




 





 





 





 





 





 



   




967




 





 





 





 





 





 



 This can be combined with an element type: 




968




 





 





 





 





 





 



   




969




 





 





 





 





 





 



     @elems = $query->query('ul#menu')->get_elements();  #  




970




 





 





 





 





 





 



   




971




 





 





 





 





 





 



 =head3 .class 




972




 





 





 





 





 





 



   




973




 





 





 





 





 





 



 Matches all elements with a specific class attribute. 




974




 





 





 





 





 





 



   




975




 





 





 





 





 





 



     @elems = $query->query('.info')->get_elements();     #  




976




 





 





 





 





 





 



   




977




 





 





 





 





 





 



 This can be combined with an element type and/or element id: 




978




 





 





 





 





 





 



   




979




 





 





 





 





 





 



     @elems = $query->query('p.info')->get_elements();     #  




980




 





 





 





 





 





 



     @elems = $query->query('p#foo.info')->get_elements(); #  




981




 





 





 





 





 





 



     @elems = $query->query('#foo.info')->get_elements();  #  




982




 





 





 





 





 





 



   




983




 





 





 





 





 





 



 The selectors listed above can be combined in a whitespace delimited 




984




 





 





 





 





 





 



 sequence to select down through a hierarchy of elements.  Consider the 




985




 





 





 





 





 





 



 following table: 




986




 





 





 





 





 





 



   




987




 





 





 





 





 





 



      




988




 





 





 





 





 





 



        




989




 





 





 





 





 





 



         WE WANT THIS ELEMENT 




990




 





 





 





 





 





 



        




991




 





 





 





 





 





 



        




992




 





 





 





 





 





 



         AND THIS ONE 




993




 





 





 





 





 





 



        




994




 





 





 





 





 





 



       ...etc.. 




995




 





 





 





 





 





 



      




996




 





 





 





 





 





 



   




997




 





 





 





 





 





 



 To locate the cells that we're interested in, we can write: 




998




 





 





 





 





 





 



   




999




 





 





 





 





 





 



     @elems = $query->query('table.search tr.result td.value')->get_elements(); 




1000




 





 





 





 





 





 



   




1001




 





 





 





 





 





 



 =head2 Attribute Selectors 




1002




 





 





 





 





 





 



   




1003




 





 





 





 





 





 



 W3C CSS 2 specification defines new constructs through which to select 




1004




 





 





 





 





 





 



 based on specific attributes within elements. See the following link for the spec: 




1005




 





 





 





 





 





 



 L 




1006




 





 





 





 





 





 



   




1007




 





 





 





 





 





 



 =head3 [attr] 




1008




 





 





 





 





 





 



   




1009




 





 





 





 





 





 



 Matches elements that have the specified attribute, including any where 




1010




 





 





 





 





 





 



 the attribute has no value. 




1011




 





 





 





 





 





 



   




1012




 





 





 





 





 





 



     @elems = $query->query('[href]')->get_elements();        #  




1013




 





 





 





 





 





 



   




1014




 





 





 





 





 





 



 This can be combined with any of the above selectors.  For example: 




1015




 





 





 





 





 





 



   




1016




 





 





 





 





 





 



     @elems = $query->query('a[href]')->get_elements();       #  




1017




 





 





 





 





 





 



     @elems = $query->query('a.menu[href]')->get_elements();  #  




1018




 





 





 





 





 





 



   




1019




 





 





 





 





 





 



 You can specify multiple attribute selectors.  Only those elements that 




1020




 





 





 





 





 





 



 match I of them will be selected. 




1021




 





 





 





 





 





 



   




1022




 





 





 





 





 





 



     @elems = $query->query('a[href][rel]')->get_elements();  #  




1023




 





 





 





 





 





 



   




1024




 





 





 





 





 





 



 =head3 [attr=value] 




1025




 





 





 





 





 





 



   




1026




 





 





 





 





 





 



 Matches elements that have an attribute set to a specific value.  The 




1027




 





 





 





 





 





 



 value can be quoted in either single or double quotes, or left unquoted. 




1028




 





 





 





 





 





 



   




1029




 





 





 





 





 





 



     @elems = $query->query('[href=index.html]')->get_elements(); 




1030




 





 





 





 





 





 



     @elems = $query->query('[href="index.html"]')->get_elements(); 




1031




 





 





 





 





 





 



     @elems = $query->query("[href='index.html']")->get_elements(); 




1032




 





 





 





 





 





 



   




1033




 





 





 





 





 





 



 You can specify multiple attribute selectors.  Only those elements that 




1034




 





 





 





 





 





 



 match I of them will be selected. 




1035




 





 





 





 





 





 



   




1036




 





 





 





 





 





 



     @elems = $query->query('a[href=index.html][rel=home]')->get_elements(); 




1037




 





 





 





 





 





 



   




1038




 





 





 





 





 





 



 =head3 [attr|=value] 




1039




 





 





 





 





 





 



   




1040




 





 





 





 





 





 



 Matches any element X whose foo attribute has a hyphen-separated list of 




1041




 





 





 





 





 





 



 values beginning (from the left) with bar. The value can be quoted in either 




1042




 





 





 





 





 





 



 single or double quotes, or left unquoted. 




1043




 





 





 





 





 





 



   




1044




 





 





 





 





 





 



     @elems = $query->query('[lang|=en]')->get_elements(); 




1045




 





 





 





 





 





 



     @elems = $query->query('p[class|="example"]')->get_elements(); 




1046




 





 





 





 





 





 



     @elems = $query->query("img[alt|='fig']")->get_elements(); 




1047




 





 





 





 





 





 



   




1048




 





 





 





 





 





 



 You can specify multiple attribute selectors.  Only those elements that 




1049




 





 





 





 





 





 



 match I of them will be selected. 




1050




 





 





 





 





 





 



   




1051




 





 





 





 





 





 



     @elems = $query->query('p[class|="external"][lang|="en"]')->get_elements(); 




1052




 





 





 





 





 





 



   




1053




 





 





 





 





 





 



 =head3 [attr~=value] 




1054




 





 





 





 





 





 



   




1055




 





 





 





 





 





 



 Matches any element X whose foo attribute value is a list of space-separated 




1056




 





 





 





 





 





 



 values, one of which is exactly equal to bar. The value can be quoted in either 




1057




 





 





 





 





 





 



 single or double quotes, or left unquoted. 




1058




 





 





 





 





 





 



   




1059




 





 





 





 





 





 



     @elems = $query->query('[lang~=en]')->get_elements(); 




1060




 





 





 





 





 





 



     @elems = $query->query('p[class~="example"]')->get_elements(); 




1061




 





 





 





 





 





 



     @elems = $query->query("img[alt~='fig']")->get_elements(); 




1062




 





 





 





 





 





 



   




1063




 





 





 





 





 





 



 You can specify multiple attribute selectors.  Only those elements that 




1064




 





 





 





 





 





 



 match I of them will be selected. 




1065




 





 





 





 





 





 



   




1066




 





 





 





 





 





 



     @elems = $query->query('p[class~="external"][lang~="en"]')->get_elements(); 




1067




 





 





 





 





 





 



   




1068




 





 





 





 





 





 



 KNOWN BUG: you can't have a C<]> character in the attribute value because 




1069




 





 





 





 





 





 



 it confuses the query parser.  Fixing this is TODO. 




1070




 





 





 





 





 





 



   




1071




 





 





 





 





 





 



 =head2 Universal Selector 




1072




 





 





 





 





 





 



   




1073




 





 





 





 





 





 



 W3C CSS 2 specification defines a new construct through which to select 




1074




 





 





 





 





 





 



 any element within the document below a given hierarchy. 




1075




 





 





 





 





 





 



   




1076




 





 





 





 





 





 



 http://www.w3.org/TR/css3-selectors/#universal-selector 




1077




 





 





 





 





 





 



   




1078




 





 





 





 





 





 



   @elems = $query->query('*')->get_elements(); 




1079




 





 





 





 





 





 



   




1080




 





 





 





 





 





 



 =head2 Combinator Selectors 




1081




 





 





 





 





 





 



   




1082




 





 





 





 





 





 



 W3C CSS 2 specification defines new constructs through which to select 




1083




 





 





 





 





 





 



 based on heirarchy with the DOM. See the following link for the spec: 




1084




 





 





 





 





 





 



 L 




1085




 





 





 





 





 





 



   




1086




 





 





 





 





 





 



 =head3 Immediate Descendents (children) 




1087




 





 





 





 





 





 



   




1088




 





 





 





 





 





 



 When you combine selectors with whitespace elements are selected if 




1089




 





 





 





 





 





 



 they are descended from the parent in some way. But if you just want 




1090




 





 





 





 





 





 



 to select the children (and not the grandchildren, great-grandchildren, 




1091




 





 





 





 





 





 



 etc) then you can combine the selectors with the C<< > >> character. 




1092




 





 





 





 





 





 



   




1093




 





 





 





 





 





 



  @elems = $query->query('a > img')->get_elements(); 




1094




 





 





 





 





 





 



   




1095




 





 





 





 





 





 



 =head3 Non-Immediate Descendents 




1096




 





 





 





 





 





 



   




1097




 





 





 





 





 





 



 If you just want any descendents that aren't children then you can combine 




1098




 





 





 





 





 





 



 selectors with the C<*> character. 




1099




 





 





 





 





 





 



   




1100




 





 





 





 





 





 



  @elems = $query->query('div * a')->get_elements(); 




1101




 





 





 





 





 





 



   




1102




 





 





 





 





 





 



 =head3 Immediate Siblings 




1103




 





 





 





 





 





 



   




1104




 





 





 





 





 





 



 If you want to use a sibling relationship then you can can join selectors 




1105




 





 





 





 





 





 



 with the C<+> character. 




1106




 





 





 





 





 





 



   




1107




 





 





 





 





 





 



  @elems = $query->query('img + span')->get_elements(); 




1108




 





 





 





 





 





 



   




1109




 





 





 





 





 





 



 =head2 Pseudo-classes 




1110




 





 





 





 





 





 



   




1111




 





 





 





 





 





 



 W3C CSS 2 and CSS 3 specifications define new concepts of pseudo-classes to  




1112




 





 





 





 





 





 



 permit formatting based on information that lies outside the document tree.  




1113




 





 





 





 





 





 



 See the following link for the most recent spec: 




1114




 





 





 





 





 





 



 L 




1115




 





 





 





 





 





 



   




1116




 





 





 





 





 





 



 HTML::Query currently has limited support for CSS 2, and no support for CSS 3. 




1117




 





 





 





 





 





 



   




1118




 





 





 





 





 





 



 Patches are *highly* encouraged to help add support here. 




1119




 





 





 





 





 





 



   




1120




 





 





 





 





 





 



 =head3 -child pseudo-classes 




1121




 





 





 





 





 





 



   




1122




 





 





 





 





 





 



 If you want to return child elements within a certain position then -child 




1123




 





 





 





 





 





 



 pseudo-classes (:first-child, :last-child) are what you're looking for. 




1124




 





 





 





 





 





 



   




1125




 





 





 





 





 





 



  @elems = $query->query('table td:first-child')->get_elements; 




1126




 





 





 





 





 





 



   




1127




 





 





 





 





 





 



 =head3 Link pseudo-classes: :link and :visited 




1128




 





 





 





 





 





 



   




1129




 





 





 





 





 





 



 Unsupported. 




1130




 





 





 





 





 





 



   




1131




 





 





 





 





 





 



 The :link pseudo-class is to be implemented, currently unsupported. 




1132




 





 





 





 





 





 



   




1133




 





 





 





 





 





 



 It is not possible to locate :visited outside of a browser context due to it's 




1134




 





 





 





 





 





 



 dynamic nature. 




1135




 





 





 





 





 





 



   




1136




 





 





 





 





 





 



 =head3 Dynamic pseudo-classes 




1137




 





 





 





 





 





 



   




1138




 





 





 





 





 





 



 Unsupported. 




1139




 





 





 





 





 





 



   




1140




 





 





 





 





 





 



 It is not possible to locate these classes(:hover, :active, :focus) outside 




1141




 





 





 





 





 





 



 of a browser context due to their dynamic nature. 




1142




 





 





 





 





 





 



   




1143




 





 





 





 





 





 



 =head3 Language pseudo-class 




1144




 





 





 





 





 





 



   




1145




 





 





 





 





 





 



 Unsupported. 




1146




 





 





 





 





 





 



   




1147




 





 





 





 





 





 



 Functionality for the :lang psuedo-class is largely replicated by using an  




1148




 





 





 





 





 





 



 attribute selector for lang combined with a universal selector query. 




1149




 





 





 





 





 





 



   




1150




 





 





 





 





 





 



 If this is insufficient I'd love to see a patch adding support for it. 




1151




 





 





 





 





 





 



   




1152




 





 





 





 





 





 



 =head3 Other pseudo-classes 




1153




 





 





 





 





 





 



   




1154




 





 





 





 





 





 



 W3C CSS 3 added a number of new behaviors that need support. At 




1155




 





 





 





 





 





 



 this time there is no support for them, but we should work on adding support. 




1156




 





 





 





 





 





 



   




1157




 





 





 





 





 





 



 Patches are very welcome. 




1158




 





 





 





 





 





 



   




1159




 





 





 





 





 





 



 =head2 Pseudo-elements 




1160




 





 





 





 





 





 



   




1161




 





 





 





 





 





 



 W3C CSS 2 and CSS 3 specification defines new concepts of pseudo-elements to 




1162




 





 





 





 





 





 



 permit formatting based on information that lies outside the document tree. 




1163




 





 





 





 





 





 



 See the following link for the most recent spec: 




1164




 





 





 





 





 





 



 L 




1165




 





 





 





 





 





 



   




1166




 





 





 





 





 





 



 At this time there is no support for pseudo-elements, but we are working 




1167




 





 





 





 





 





 



 on adding support. 




1168




 





 





 





 





 





 



   




1169




 





 





 





 





 





 



 Patches are very welcome. 




1170




 





 





 





 





 





 



   




1171




 





 





 





 





 





 



 =head2 Combining Selectors 




1172




 





 





 





 





 





 



   




1173




 





 





 





 





 





 



 You can combine basic and hierarchical selectors into a single query 




1174




 





 





 





 





 





 



 by separating each part with a comma.  The query will select all matching 




1175




 





 





 





 





 





 



 elements for each of the comma-delimited selectors.  For example, to 




1176




 





 





 





 





 





 



 find all C, C and C elements in a tree: 




1177




 





 





 





 





 





 



   




1178




 





 





 





 





 





 



     @elems = $query->query('a, b, i')->get_elements(); 




1179




 





 





 





 





 





 



   




1180




 





 





 





 





 





 



 Each of these selectors can be arbitrarily complex. 




1181




 





 





 





 





 





 



   




1182




 





 





 





 





 





 



     @elems = $query->query( 




1183




 





 





 





 





 





 



         'table.search[width=100%] tr.result[valign=top] td.value, 




1184




 





 





 





 





 





 



          form.search input[type=submit], 




1185




 





 





 





 





 





 



          a[href=index.html]' 




1186




 





 





 





 





 





 



     )->get_elements(); 




1187




 





 





 





 





 





 



   




1188




 





 





 





 





 





 



 =head1 EXPORT HOOKS 




1189




 





 





 





 





 





 



   




1190




 





 





 





 





 





 



 =head2 Query 




1191




 





 





 





 





 





 



   




1192




 





 





 





 





 





 



 The C constructor subroutine (note the capital letter) can be 




1193




 





 





 





 





 





 



 exported as a convenient way to create C objects. It simply 




1194




 





 





 





 





 





 



 forwards all arguments to the L constructor method. 




1195




 





 





 





 





 





 



   




1196




 





 





 





 





 





 



     use HTML::Query 'Query'; 




1197




 





 





 





 





 





 



   




1198




 





 





 





 





 





 



     my $query = Query( file => $file, 'ul.menu li a' ); 




1199




 





 





 





 





 





 



   




1200




 





 





 





 





 





 



 =head2 query 




1201




 





 





 





 





 





 



   




1202




 





 





 





 





 





 



 The C export hook can be called to monkey-patch a L method 




1203




 





 





 





 





 





 



 into the L module. 




1204




 





 





 





 





 





 



   




1205




 





 





 





 





 





 



 This is considered questionable behaviour in polite society which regards it 




1206




 





 





 





 





 





 



 as a violation of the inner sanctity of the L. 




1207




 





 





 





 





 





 



   




1208




 





 





 





 





 





 



 But if you're the kind of person that doesn't mind a bit of occasional 




1209




 





 





 





 





 





 



 namespace abuse for the sake of getting the job done, then go right ahead. 




1210




 





 





 





 





 





 



 Just don't blame me if it all blows up later. 




1211




 





 





 





 





 





 



   




1212




 





 





 





 





 





 



     use HTML::Query 'query';                # note lower case 'q' 




1213




 





 





 





 





 





 



     use HTML::TreeBuilder; 




1214




 





 





 





 





 





 



   




1215




 





 





 





 





 





 



     # build a tree 




1216




 





 





 





 





 





 



     my $tree = HTML::TreeBuilder->new; 




1217




 





 





 





 





 





 



     $tree->parse_file($filename); 




1218




 





 





 





 





 





 



   




1219




 





 





 





 





 





 



     # call the query() method on any element 




1220




 





 





 





 





 





 



     my $query = $tree->query('ul li a'); 




1221




 





 





 





 





 





 



   




1222




 





 





 





 





 





 



 =head1 METHODS 




1223




 





 





 





 





 





 



   




1224




 





 





 





 





 





 



 The C object is a subclass of L and 




1225




 





 





 





 





 





 



 inherits all of its method. 




1226




 





 





 





 





 





 



   




1227




 





 





 





 





 





 



 =head2 new(@elements,$selector) 




1228




 





 





 





 





 





 



   




1229




 





 





 





 





 





 



 This constructor method is used to create a new C object. It 




1230




 





 





 





 





 





 



 expects a list of any number (including zero) of 




1231




 





 





 





 





 





 



 L or C objects. 




1232




 





 





 





 





 





 



   




1233




 





 





 





 





 





 



     # single HTML::Element object 




1234




 





 





 





 





 





 



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




1235




 





 





 





 





 





 



   




1236




 





 





 





 





 





 



     # multiple element object 




1237




 





 





 





 





 





 



     my $query = HTML::Query->new($elem1, $elem2, $elem3, ...); 




1238




 





 





 





 





 





 



   




1239




 





 





 





 





 





 



     # copy elements from an existing query 




1240




 





 





 





 





 





 



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




1241




 





 





 





 





 





 



   




1242




 





 





 





 





 





 



     # copy elements from several queries 




1243




 





 





 





 





 





 



     my $query = HTML::Query->new($query1, $query2, $query3); 




1244




 





 





 





 





 





 



   




1245




 





 





 





 





 





 



     # or a mixture 




1246




 





 





 





 





 





 



     my $query = HTML::Query->new($elem1, $query1, $elem2, $query3); 




1247




 





 





 





 





 





 



   




1248




 





 





 





 





 





 



 You can also use named parameters to specify an alternate source for a 




1249




 





 





 





 





 





 



 element. 




1250




 





 





 





 





 





 



   




1251




 





 





 





 





 





 



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




1252




 





 





 





 





 





 



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




1253




 





 





 





 





 





 



   




1254




 





 





 





 





 





 



 In this case, the L module is used to 




1255




 





 





 





 





 





 



 parse the source file or text into a tree of L 




1256




 





 





 





 





 





 



 objects. 




1257




 





 





 





 





 





 



   




1258




 





 





 





 





 





 



 For the sake of completeness, you can also specify element trees and queries 




1259




 





 





 





 





 





 



 using named parameters: 




1260




 





 





 





 





 





 



   




1261




 





 





 





 





 





 



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




1262




 





 





 





 





 





 



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




1263




 





 





 





 





 





 



   




1264




 





 





 





 





 





 



 You can freely mix and match elements, queries and named sources.  The 




1265




 





 





 





 





 





 



 query will be constructed as an aggregate across them all. 




1266




 





 





 





 





 





 



   




1267




 





 





 





 





 





 



     $q = HTML::Query->new( 




1268




 





 





 





 





 





 



         text  => $text1, 




1269




 





 





 





 





 





 



         text  => $text2, 




1270




 





 





 





 





 





 



         file  => $file1, 




1271




 





 





 





 





 





 



         file  => $file2, 




1272




 





 





 





 





 





 



         tree  => $tree, 




1273




 





 





 





 





 





 



         query => $query1, 




1274




 





 





 





 





 





 



     ); 




1275




 





 





 





 





 





 



   




1276




 





 





 





 





 





 



 The final, optional argument can be a selector specification.  This is 




1277




 





 





 





 





 





 



 immediately passed to the L method which will return a new query 




1278




 





 





 





 





 





 



 with only those elements selected. 




1279




 





 





 





 





 





 



   




1280




 





 





 





 





 





 



     my $spec = 'ul.menu li a';              # .... 




1281




 





 





 





 





 





 



   




1282




 





 





 





 





 





 



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




1283




 





 





 





 





 





 



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




1284




 





 





 





 





 





 



     my $query = HTML::Query->new( 




1285




 





 





 





 





 





 



         text => $text, 




1286




 





 





 





 





 





 



         file => $file, 




1287




 





 





 





 





 





 



         $spec 




1288




 





 





 





 





 





 



     ); 




1289




 





 





 





 





 





 



   




1290




 





 





 





 





 





 



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




1291




 





 





 





 





 





 



   




1292




 





 





 





 





 





 



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




1293




 





 





 





 





 





 



   




1294




 





 





 





 





 





 



 =head2 query($spec) 




1295




 





 





 





 





 





 



   




1296




 





 





 





 





 





 



 This method locates the descendant elements identified by the C<$spec> 




1297




 





 





 





 





 





 



 argument for each element in the query. It then interally stores the results  




1298




 





 





 





 





 





 



 for requerying or return. See get_elements(). 




1299




 





 





 





 





 





 



   




1300




 





 





 





 





 





 



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




1301




 





 





 





 





 





 



     my $results = $query->query($spec); 




1302




 





 





 





 





 





 



   




1303




 





 





 





 





 





 



 See L<"QUERY SYNTAX"> for the permitted syntax of the C<$spec> argument. 




1304




 





 





 





 





 





 



   




1305




 





 





 





 





 





 



 =head2 get_elements() 




1306




 





 





 





 





 





 



   




1307




 





 





 





 





 





 



 This method returns the stored results from a query. In list context it returns a list of 




1308




 





 





 





 





 





 



 matching L objects. In scalar context it returns a reference to 




1309




 





 





 





 





 





 



 the results array. 




1310




 





 





 





 





 





 



   




1311




 





 





 





 





 





 



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




1312




 





 





 





 





 





 



     my $results = $query->query($spec); 




1313




 





 





 





 





 





 



   




1314




 





 





 





 





 





 



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




1315




 





 





 





 





 





 



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




1316




 





 





 





 





 





 



   




1317




 





 





 





 





 





 



 =head2 size() 




1318




 





 





 





 





 





 



   




1319




 





 





 





 





 





 



 Returns the number of elements in the query. 




1320




 





 





 





 





 





 



   




1321




 





 





 





 





 





 



 =head2 first() 




1322




 





 





 





 





 





 



   




1323




 





 





 





 





 





 



 Returns the first element in the query. 




1324




 





 





 





 





 





 



   




1325




 





 





 





 





 





 



     my $elem = $query->first; 




1326




 





 





 





 





 





 



   




1327




 





 





 





 





 





 



 If the query is empty then an exception will be thrown. If you would rather 




1328




 





 





 





 





 





 



 have an undefined value returned then you can use the C method inherited 




1329




 





 





 





 





 





 



 from L. This effectively wraps the call to 




1330




 





 





 





 





 





 



 C in an C block to catch any exceptions thrown. 




1331




 





 





 





 





 





 



   




1332




 





 





 





 





 





 



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




1333




 





 





 





 





 





 



   




1334




 





 





 





 





 





 



 =head2 last() 




1335




 





 





 





 





 





 



   




1336




 





 





 





 





 





 



 Similar to L, but returning the last element in the query. 




1337




 





 





 





 





 





 



   




1338




 





 





 





 





 





 



     my $elem = $query->last; 




1339




 





 





 





 





 





 



   




1340




 





 





 





 





 





 



 =head2 list() 




1341




 





 





 





 





 





 



   




1342




 





 





 





 





 





 



 Returns a list of the L object in the query in 




1343




 





 





 





 





 





 



 list context, or a reference to a list in scalar context. 




1344




 





 





 





 





 





 



   




1345




 





 





 





 





 





 



     my @elems = $query->list; 




1346




 





 





 





 





 





 



     my $elems = $query->list; 




1347




 





 





 





 





 





 



   




1348




 





 





 





 





 





 



 =head2 AUTOLOAD 




1349




 





 





 





 





 





 



   




1350




 





 





 





 





 





 



 The C method maps any other method calls to the 




1351




 





 





 





 





 





 



 L objects in the list. When called in list 




1352




 





 





 





 





 





 



 context it returns a list of the values returned from calling the method on 




1353




 





 





 





 





 





 



 each element. In scalar context it returns a reference to a list of return 




1354




 





 





 





 





 





 



 values. 




1355




 





 





 





 





 





 



   




1356




 





 





 





 





 





 



     my @text_blocks = $query->as_trimmed_text; 




1357




 





 





 





 





 





 



     my $text_blocks = $query->as_trimmed_text; 




1358




 





 





 





 





 





 



   




1359




 





 





 





 





 





 



 =head1 KNOWN BUGS 




1360




 





 





 





 





 





 



   




1361




 





 





 





 





 





 



 =head2 Attribute Values 




1362




 





 





 





 





 





 



   




1363




 





 





 





 





 





 



 It is not possible to use C<]> in an attribute value.  This is due to a 




1364




 





 





 





 





 





 



 limitation in the parser which will be fixed RSN. 




1365




 





 





 





 





 





 



   




1366




 





 





 





 





 





 



 =head1 AUTHOR 




1367




 





 





 





 





 





 



   




1368




 





 





 





 





 





 



 Andy Wardley L 




1369




 





 





 





 





 





 



   




1370




 





 





 





 





 





 



 =head1 MAINTAINER 




1371




 





 





 





 





 





 



   




1372




 





 





 





 





 





 



 Kevin Kamel  




1373




 





 





 





 





 





 



   




1374




 





 





 





 





 





 



 =head1 CONTRIBUTORS 




1375




 





 





 





 





 





 



   




1376




 





 





 





 





 





 



 Vivek Khera  




1377




 





 





 





 





 





 



 Michael Peters  




1378




 





 





 





 





 





 



 David Gray  




1379




 





 





 





 





 





 



   




1380




 





 





 





 





 





 



 =head1 COPYRIGHT 




1381




 





 





 





 





 





 



   




1382




 





 





 





 





 





 



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




1383




 





 





 





 





 





 



   




1384




 





 





 





 





 





 



 This module is free software; you can redistribute it and/or modify it 




1385




 





 





 





 





 





 



 under the same terms as Perl itself. 




1386




 





 





 





 





 





 



   




1387




 





 





 





 





 





 



 =head1 SEE ALSO 




1388




 





 





 





 





 





 



   




1389




 





 





 





 





 





 



 L, L, 




1390




 





 





 





 





 





 



 L, L, L 




1391




 





 





 





 





 





 



   




1392




 





 





 





 





 





 



 =cut 




1393




 





 





 





 





 





 



   




1394




 





 





 





 





 





 



 # Local Variables: 




1395




 





 





 





 





 





 



 # mode: Perl 




1396




 





 





 





 





 





 



 # perl-indent-level: 4 




1397




 





 





 





 





 





 



 # indent-tabs-mode: nil 




1398




 





 





 





 





 





 



 # End: 




1399




 





 





 





 





 





 



 # 




1400




 





 





 





 





 





 



 # vim: expandtab shiftwidth=4:

=head3 #id

Matches all elements with a specific id attribute.

    @elems = $query->query('#menu')->get_elements()     #

This can be combined with an element type:

    @elems = $query->query('ul#menu')->get_elements();  #

=head3 .class

Matches all elements with a specific class attribute.

    @elems = $query->query('.info')->get_elements();     #

This can be combined with an element type and/or element id:

    @elems = $query->query('p.info')->get_elements();     #
    @elems = $query->query('p#foo.info')->get_elements(); #
    @elems = $query->query('#foo.info')->get_elements();  #

The selectors listed above can be combined in a whitespace delimited
sequence to select down through a hierarchy of elements.  Consider the
following table:

     




988




 





 





 





 





 





 



        




989




 





 





 





 





 





 



         WE WANT THIS ELEMENT 




990




 





 





 





 





 





 



        




991




 





 





 





 





 





 



        




992




 





 





 





 





 





 



         AND THIS ONE 




993




 





 





 





 





 





 



        




994




 





 





 





 





 





 



       ...etc.. 




995






      ...etc..


To locate the cells that we're interested in, we can write:

    @elems = $query->query('table.search tr.result td.value')->get_elements();

=head2 Attribute Selectors

W3C CSS 2 specification defines new constructs through which to select
based on specific attributes within elements. See the following link for the spec:
L

=head3 [attr]

Matches elements that have the specified attribute, including any where
the attribute has no value.

    @elems = $query->query('[href]')->get_elements();        #

This can be combined with any of the above selectors.  For example:

    @elems = $query->query('a[href]')->get_elements();       #
    @elems = $query->query('a.menu[href]')->get_elements();  #

You can specify multiple attribute selectors.  Only those elements that
match I of them will be selected.

    @elems = $query->query('a[href][rel]')->get_elements();  #

=head3 [attr=value]

Matches elements that have an attribute set to a specific value.  The
value can be quoted in either single or double quotes, or left unquoted.

    @elems = $query->query('[href=index.html]')->get_elements();
    @elems = $query->query('[href="index.html"]')->get_elements();
    @elems = $query->query("[href='index.html']")->get_elements();

You can specify multiple attribute selectors.  Only those elements that
match I of them will be selected.

    @elems = $query->query('a[href=index.html][rel=home]')->get_elements();

=head3 [attr|=value]

Matches any element X whose foo attribute has a hyphen-separated list of
values beginning (from the left) with bar. The value can be quoted in either
single or double quotes, or left unquoted.

    @elems = $query->query('[lang|=en]')->get_elements();
    @elems = $query->query('p[class|="example"]')->get_elements();
    @elems = $query->query("img[alt|='fig']")->get_elements();

You can specify multiple attribute selectors.  Only those elements that
match I of them will be selected.

    @elems = $query->query('p[class|="external"][lang|="en"]')->get_elements();

=head3 [attr~=value]

Matches any element X whose foo attribute value is a list of space-separated
values, one of which is exactly equal to bar. The value can be quoted in either
single or double quotes, or left unquoted.

    @elems = $query->query('[lang~=en]')->get_elements();
    @elems = $query->query('p[class~="example"]')->get_elements();
    @elems = $query->query("img[alt~='fig']")->get_elements();

You can specify multiple attribute selectors.  Only those elements that
match I of them will be selected.

    @elems = $query->query('p[class~="external"][lang~="en"]')->get_elements();

KNOWN BUG: you can't have a C<]> character in the attribute value because
it confuses the query parser.  Fixing this is TODO.

=head2 Universal Selector

W3C CSS 2 specification defines a new construct through which to select
any element within the document below a given hierarchy.

http://www.w3.org/TR/css3-selectors/#universal-selector

  @elems = $query->query('*')->get_elements();

=head2 Combinator Selectors

W3C CSS 2 specification defines new constructs through which to select
based on heirarchy with the DOM. See the following link for the spec:
L

=head3 Immediate Descendents (children)

When you combine selectors with whitespace elements are selected if
they are descended from the parent in some way. But if you just want
to select the children (and not the grandchildren, great-grandchildren,
etc) then you can combine the selectors with the C<< > >> character.

 @elems = $query->query('a > img')->get_elements();

=head3 Non-Immediate Descendents

If you just want any descendents that aren't children then you can combine
selectors with the C<*> character.

 @elems = $query->query('div * a')->get_elements();

=head3 Immediate Siblings

If you want to use a sibling relationship then you can can join selectors
with the C<+> character.

 @elems = $query->query('img + span')->get_elements();

=head2 Pseudo-classes

W3C CSS 2 and CSS 3 specifications define new concepts of pseudo-classes to
permit formatting based on information that lies outside the document tree.
See the following link for the most recent spec:
L

HTML::Query currently has limited support for CSS 2, and no support for CSS 3.

Patches are *highly* encouraged to help add support here.

=head3 -child pseudo-classes

If you want to return child elements within a certain position then -child
pseudo-classes (:first-child, :last-child) are what you're looking for.

 @elems = $query->query('table td:first-child')->get_elements;

=head3 Link pseudo-classes: :link and :visited

Unsupported.

The :link pseudo-class is to be implemented, currently unsupported.

It is not possible to locate :visited outside of a browser context due to it's
dynamic nature.

=head3 Dynamic pseudo-classes

Unsupported.

It is not possible to locate these classes(:hover, :active, :focus) outside
of a browser context due to their dynamic nature.

=head3 Language pseudo-class

Unsupported.

Functionality for the :lang psuedo-class is largely replicated by using an
attribute selector for lang combined with a universal selector query.

If this is insufficient I'd love to see a patch adding support for it.

=head3 Other pseudo-classes

W3C CSS 3 added a number of new behaviors that need support. At
this time there is no support for them, but we should work on adding support.

Patches are very welcome.

=head2 Pseudo-elements

W3C CSS 2 and CSS 3 specification defines new concepts of pseudo-elements to
permit formatting based on information that lies outside the document tree.
See the following link for the most recent spec:
L

At this time there is no support for pseudo-elements, but we are working
on adding support.

Patches are very welcome.

=head2 Combining Selectors

You can combine basic and hierarchical selectors into a single query
by separating each part with a comma.  The query will select all matching
elements for each of the comma-delimited selectors.  For example, to
find all C, C and C elements in a tree:

    @elems = $query->query('a, b, i')->get_elements();

Each of these selectors can be arbitrarily complex.

    @elems = $query->query(
        'table.search[width=100%] tr.result[valign=top] td.value,
         form.search input[type=submit],
         a[href=index.html]'
    )->get_elements();

=head1 EXPORT HOOKS

=head2 Query

The C constructor subroutine (note the capital letter) can be
exported as a convenient way to create C objects. It simply
forwards all arguments to the L constructor method.

    use HTML::Query 'Query';

    my $query = Query( file => $file, 'ul.menu li a' );

=head2 query

The C export hook can be called to monkey-patch a L method
into the L module.

This is considered questionable behaviour in polite society which regards it
as a violation of the inner sanctity of the L.

But if you're the kind of person that doesn't mind a bit of occasional
namespace abuse for the sake of getting the job done, then go right ahead.
Just don't blame me if it all blows up later.

    use HTML::Query 'query';                # note lower case 'q'
    use HTML::TreeBuilder;

    # build a tree
    my $tree = HTML::TreeBuilder->new;
    $tree->parse_file($filename);

    # call the query() method on any element
    my $query = $tree->query('ul li a');

=head1 METHODS

The C object is a subclass of L and
inherits all of its method.

=head2 new(@elements,$selector)

This constructor method is used to create a new C object. It
expects a list of any number (including zero) of
L or C objects.

    # single HTML::Element object
    my $query = HTML::Query->new($elem);

    # multiple element object
    my $query = HTML::Query->new($elem1, $elem2, $elem3, ...);

    # copy elements from an existing query
    my $query = HTML::Query->new($another_query);

    # copy elements from several queries
    my $query = HTML::Query->new($query1, $query2, $query3);

    # or a mixture
    my $query = HTML::Query->new($elem1, $query1, $elem2, $query3);

You can also use named parameters to specify an alternate source for a
element.

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

In this case, the L module is used to
parse the source file or text into a tree of L
objects.

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 L method which will return a new query
with only those elements selected.

    my $spec = 'ul.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);

=head2 query($spec)

This method locates the descendant elements identified by the C<$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 L<"QUERY SYNTAX"> for the permitted syntax of the C<$spec> argument.

=head2 get_elements()

This method returns the stored results from a query. In list context it returns a list of
matching L 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();

=head2 size()

Returns the number of elements in the query.

=head2 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 C method inherited
from L. This effectively wraps the call to
C in an C block to catch any exceptions thrown.

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

=head2 last()

Similar to L, but returning the last element in the query.

    my $elem = $query->last;

=head2 list()

Returns a list of the L object in the query in
list context, or a reference to a list in scalar context.

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

=head2 AUTOLOAD

The C method maps any other method calls to the
L 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;

=head1 KNOWN BUGS

=head2 Attribute Values

It is not possible to use C<]> in an attribute value.  This is due to a
limitation in the parser which will be fixed RSN.

=head1 AUTHOR

Andy Wardley L

=head1 MAINTAINER

Kevin Kamel

=head1 CONTRIBUTORS

Vivek Khera
Michael Peters
David Gray

=head1 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.

=head1 SEE ALSO

L, L,
L, L, L

=cut

# Local Variables:
# mode: Perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4: