The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Chain-0.06
River stage zero No dependents
1 ++
/ XML::Chain::Selector

NAME

XML::Chain::Selector - selector for traversing the XML::Chain

SYNOPSIS

    my $user = xc('user', xmlns => 'http://testns')->auto_indent({chars=>' 'x4})
        ->a('name', '-' => 'Johnny Thinker')
        ->a('username', '-' => 'jt')
        ->c('bio')
            ->c('div', xmlns => 'http://www.w3.org/1999/xhtml')
                ->a('h1', '-' => 'about')
                ->a('p', '-' => '...')
                ->up
            ->a('greeting', '-' => 'Hey')
            ->up
        ->a('active', '-' => '1')
        ->root;
    say $user->as_string;

Will print:

    <user xmlns="http://testns">
        <name>Johnny Thinker</name>
        <username>jt</username>
        <bio>
            <div xmlns="http://www.w3.org/1999/xhtml">
                <h1>about</h1>
                <p>...</p>
            </div>
            <greeting>Hey</greeting>
        </bio>
        <active>1</active>
    </user>

DESCRIPTION

CHAINED METHODS

c, append_and_select

Appends new element to current elements and changes context to them. New element is defined in parameters:

    $xc->c('i', class => 'icon-download icon-white')
    # <i class="icon-download icon-white"/>

First parameter is name of the element, then followed by optional element attributes.

t, append_text

Appends text to current elements.

    xc('span')->t('some')->t(' ')->t('more text')
    # <span>some more text</span>

First parameter is name of the element, then followed by optional element attributes.

root

Sets document element as current element.

    say xc('p')
        ->t('this ')
        ->a(xc('b')->t('is'))
        ->t(' important!')
        ->root->as_string;
    # <p>this <b>is</b> important!</p>

up, parent

Traverse current elements and replace them by their parents.

find

    say $xc->find('//p/b[@class="less"]')->text_content;
    say $xc->find('//xhtml:div', xhtml => 'http://www.w3.org/1999/xhtml')->count;

Look-up elements by xpath and set them as current elements. Optional look-up namespace prefixes can be specified. Any global registered namespace prefixes "reg_global_ns" can be used.

children

Set all current elements child nodes as current elements.

first

Set first current elements as current elements.

empty

Removes all child nodes from current elements.

rename

    my $body = xc('bodyz')->rename('body');
    # <body/>

Rename node name(s).

attr

    my $img = xc('img')->attr('href' => '#', 'title' => 'imaget');
    # <img href="#" title="imaget"/>

    say $img->attr('title')
    # imaget

    say $img->attr('title' => undef)
    # <img href="#"/>

Get or set elements attributes. With one argument returns attribute value otherwise sets them. Setting attribute to undef will remove it from the element.

each

    # rename using each
    $body->rename('body');
    $body
        ->a(xc('p.1')->t(1))
        ->a(xc('p.2')->t(2))
        ->a(xc('div')->t(3))
        ->a(xc('p.3')->t(4))
        ->each(sub { $_->rename('p') if $_->name =~ m/^p[.]/ });
    is($body, '<body><p>1</p><p>2</p><div>3</div><p>4</p></body>','rename using each()');

Loops through all selected elements and calls callback for each of them.

remap

    xc('body')->a('p', i => 1)->children->remap(
        sub {
            (map {xc('e', i => $_)} 1 .. 3), $_;
        }
    )->root;
    # <body><e i="1"/><e i="2"/><e i="3"/><p i="1"/></body>

Replaces all selected elements by callback returned elements.

rm, remove_and_parent

    my $pdiv = xc('base')
            ->a(xc('p')->t(1))
            ->a(xc('p')->t(2))
            ->a(xc('div')->t(3))
            ->a(xc('p')->t(4));
    my $p = $pdiv->find('//p');
    # $pdiv->find('//p[position()=3]')->rm->name eq 'base'
    # $p->count == 2     # deleted elements are skipped also in old selectors
    # <base><p>1</p><p>2</p><div>3</div></base>

Deletes current elements and returns their parent.

auto_indent

(experimental feature (good/usefull for debug, needs more testing), works only on element for which as_string is called at this moment)

    my $simple = xc('div')
                    ->auto_indent(1)
                    ->a('div', '-' => 'in1')
                    ->a('div', '-' => 'in2')
                    ->t('in2.1')
                    ->a('div', '-' => 'in3')
    ;
    say $simple->as_string;

Will print:

    <div>
        <div>in1</div>
        <div>in2</div>
        in2.1
        <div>in3</div>
    </div>

Turn on/off tidy/auto-indentation of document elements. Default indentation characters are tabs.

Argument can be either true/false scalar or a hashref with indentation options. Currently {chars=' 'x4} > will set indentation characters to be four spaces.

CHAINED DOCUMENT METHODS

See "CHAINED DOCUMENT METHODS" in XML::Chain.

METHODS

as_string, toString

Returns string representation of current XML elements. Call root before to get a string representing the whole document.

    $xc->as_string
    $xc->root->as_string

as_xml_libxml

Returns array of current elements as XML::LibXML objects.

text_content

Returns text content of all current XML elements.

count / size

    say $xc->find('//b')->count;

Return the number of current elements.

single

    my $lxml_el = $xc->find('//b')->first->as_xml_libxml;

Checks is there is exactly one element in current elements and return it as XML::Chain::Element object.

reg_global_ns

    $sitemap->reg_global_ns('i' => 'http://www.google.com/schemas/sitemap-image/1.1');
    $sitemap->reg_global_ns('s' => 'http://www.sitemaps.org/schemas/sitemap/0.9');
    say $sitemap->find('/s:urlset/s:url/i:image')->count
    # 2

AUTHOR

Jozef Kutej

COPYRIGHT & LICENSE

Copyright 2017 Jozef Kutej, all rights reserved.

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