deprecated/buildtools/buildsystemtools/lib/XML/DOM/Parser.pod
author lorewang
Wed, 01 Dec 2010 16:05:36 +0800
changeset 715 e0739b8406dd
parent 655 3f65fd25dfd4
permissions -rw-r--r--
Specify extenal tool with path
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
655
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     1
=head1 NAME
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     2
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     3
XML::DOM::Parser - An XML::Parser that builds XML::DOM document structures
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     4
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     5
=head1 SYNOPSIS
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     6
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     7
 use XML::DOM;
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     8
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
     9
 my $parser = new XML::DOM::Parser;
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    10
 my $doc = $parser->parsefile ("file.xml");
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    11
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    12
=head1 DESCRIPTION
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    13
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    14
XML::DOM::Parser extends L<XML::Parser>
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    15
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    16
The XML::Parser module was written by Clark Cooper and
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    17
is built on top of XML::Parser::Expat, 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    18
which is a lower level interface to James Clark's expat library.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    19
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    20
XML::DOM::Parser parses XML strings or files
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    21
and builds a data structure that conforms to the API of the Document Object 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    22
Model as described at L<http://www.w3.org/TR/REC-DOM-Level-1>.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    23
See the L<XML::Parser> manpage for other additional properties of the 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    24
XML::DOM::Parser class. 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    25
Note that the 'Style' property should not be used (it is set internally.)
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    26
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    27
The XML::Parser B<NoExpand> option is more or less supported, in that it will
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    28
generate EntityReference objects whenever an entity reference is encountered
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    29
in character data. I'm not sure how useful this is. Any comments are welcome.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    30
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    31
As described in the synopsis, when you create an XML::DOM::Parser object, 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    32
the parse and parsefile methods create an L<XML::DOM::Document> object
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    33
from the specified input. This Document object can then be examined, modified and
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    34
written back out to a file or converted to a string.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    35
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    36
When using XML::DOM with XML::Parser version 2.19 and up, setting the 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    37
XML::DOM::Parser option B<KeepCDATA> to 1 will store CDATASections in
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    38
CDATASection nodes, instead of converting them to Text nodes.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    39
Subsequent CDATASection nodes will be merged into one. Let me know if this
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    40
is a problem.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    41
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    42
=head1 Using LWP to parse URLs
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    43
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    44
The parsefile() method now also supports URLs, e.g. I<http://www.erols.com/enno/xsa.xml>.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    45
It uses LWP to download the file and then calls parse() on the resulting string.
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    46
By default it will use a L<LWP::UserAgent> that is created as follows:
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    47
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    48
 use LWP::UserAgent;
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    49
 $LWP_USER_AGENT = LWP::UserAgent->new;
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    50
 $LWP_USER_AGENT->env_proxy;
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    51
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    52
Note that env_proxy reads proxy settings from environment variables, which is what I need to
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    53
do to get thru our firewall. If you want to use a different LWP::UserAgent, you can either set
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    54
it globally with:
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    55
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    56
 XML::DOM::Parser::set_LWP_UserAgent ($my_agent);
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    57
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    58
or, you can specify it for a specific XML::DOM::Parser by passing it to the constructor:
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    59
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    60
 my $parser = new XML::DOM::Parser (LWP_UserAgent => $my_agent);
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    61
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    62
Currently, LWP is used when the filename (passed to parsefile) starts with one of
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    63
the following URL schemes: http, https, ftp, wais, gopher, or file (followed by a colon.)
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    64
If I missed one, please let me know. 
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    65
3f65fd25dfd4 sync up SVN codes
kelvzhu
parents:
diff changeset
    66
The LWP modules are part of libwww-perl which is available at CPAN.