Skip to content

Commit bad83df

Browse files
dwarringdwarring
committed
Refactor some proxy accessors
1 parent 66c4153 commit bad83df

File tree

11 files changed

+226
-231
lines changed

11 files changed

+226
-231
lines changed

‎docs/HashMap.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Both [LibXML::Node::Set](https://libxml-raku.github.io/LibXML-raku/Node/Set) and
4646

4747
This is the nodes in the set or list collated by tag-name.
4848

49-
Several container types are available:
49+
Several container types are available:
5050

5151
* `LibXML::HashMap` By default XPath objects are used to store strings, floats, booleans, nodes or node-sets.
5252

‎docs/Node.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ method nodeName() returns Str
122122

123123
Gets or sets the node name
124124

125-
This method is aware of namespaces and returns the full name of the current node (`prefix:localname`).
125+
This method is aware of namespaces and returns the full name of the current node (`prefix:localname`).
126126

127127
It also returns the correct DOM names for node types with constant names, namely: `#text`, `#cdata-section`, `#comment`, `#document`, `#document-fragment`.
128128

@@ -228,9 +228,9 @@ method setBaseURI(
228228

229229
Sets the base URI
230230

231-
This method only does something useful for an element node in an XML document. It sets the xml:base attribute on the node to $strURI, which effectively sets the base URI of the node to the same value.
231+
This method only does something useful for an element node in an XML document. It sets the xml:base attribute on the node to $strURI, which effectively sets the base URI of the node to the same value.
232232

233-
Note: For HTML documents this behaves as if the document was XML which may not be desired, since it does not effectively set the base URI of the node. See RFC 2396 appendix D for an example of how base URI can be specified in HTML.
233+
Note: For HTML documents this behaves as if the document was XML which may not be desired, since it does not effectively set the base URI of the node. See RFC 2396 appendix D for an example of how base URI can be specified in HTML.
234234

235235
### method line-number
236236

@@ -242,7 +242,7 @@ Return the source line number where the tag was found
242242

243243
If a node is added to the document the line number is 0. Problems may occur, if a node from one document is passed to another one.
244244

245-
IMPORTANT: Due to limitations in the libxml2 library line numbers greater than 65535 will be returned as 65535. Please see [http://bugzilla.gnome.org/show_bug.cgi?id=325533](http://bugzilla.gnome.org/show_bug.cgi?id=325533) for more details.
245+
IMPORTANT: Due to limitations in the libxml2 library line numbers greater than 65535 will be returned as 65535. Please see [http://bugzilla.gnome.org/show_bug.cgi?id=325533](http://bugzilla.gnome.org/show_bug.cgi?id=325533) for more details.
246246

247247
Note: line-number() is special to LibXML and not part of the DOM specification.
248248

@@ -486,7 +486,7 @@ multi method cloneNode(
486486

487487
Copy a node
488488

489-
When $deep is True the function will copy all child nodes as well. Otherwise the current node will be copied. Note that in case of element, attributes are copied even if $deep is not True.
489+
When $deep is True the function will copy all child nodes as well. Otherwise the current node will be copied. Note that in case of element, attributes are copied even if $deep is not True.
490490

491491
### method insertBefore
492492

@@ -529,7 +529,7 @@ Searching Methods
529529

530530
multi method findnodes(Str $xpath-expr,
531531
LibXML::Node $ref-node?,
532-
Bool :$deref, :%ns) returns LibXML::Node::Set
532+
Bool :$deref, :%ns) returns LibXML::Node::Set
533533
multi method findnodes(LibXML::XPath::Expression:D $xpath-expr,
534534
LibXML::Node $ref-node?,
535535
Bool :$deref, :%ns) returns LibXML::Node::Set
@@ -551,13 +551,13 @@ It indexes element child nodes and attributes. This option is used by the `AT-KE
551551

552552
*NOTE ON NAMESPACES AND XPATH*:
553553

554-
A common mistake about XPath is to assume that node tests consisting of an element name with no prefix match elements in the default namespace. This assumption is wrong - by XPath specification, such node tests can only match elements that are in no (i.e. null) namespace.
554+
A common mistake about XPath is to assume that node tests consisting of an element name with no prefix match elements in the default namespace. This assumption is wrong - by XPath specification, such node tests can only match elements that are in no (i.e. null) namespace.
555555

556-
So, for example, one cannot match the root element of an XHTML document with `$node.find('/html')` since `'/html'` would only match if the root element `<html>` had no namespace, but all XHTML elements belong to the namespace http://www.w3.org/1999/xhtml. (Note that `xmlns="..."` namespace declarations can also be specified in a DTD, which makes the situation even worse, since the XML document looks as if there was no default namespace).
556+
So, for example, one cannot match the root element of an XHTML document with `$node.find('/html')` since `'/html'` would only match if the root element `<html>` had no namespace, but all XHTML elements belong to the namespace http://www.w3.org/1999/xhtml. (Note that `xmlns="..."` namespace declarations can also be specified in a DTD, which makes the situation even worse, since the XML document looks as if there was no default namespace).
557557

558-
There are several possible ways to deal with namespaces in XPath:
558+
There are several possible ways to deal with namespaces in XPath:
559559

560-
* The recommended way is to define a document independent prefix-to-namespace mapping. For example:
560+
* The recommended way is to define a document independent prefix-to-namespace mapping. For example:
561561

562562
my %ns = 'x' => 'http://www.w3.org/1999/xhtml';
563563
$node.find('/x:html', :%ns);
@@ -567,7 +567,7 @@ There are several possible ways to deal with namespaces in XPath:
567567
my $xpath-context = $node.xpath-context: :%ns;
568568
$xpath-context.find('/x:html');
569569

570-
* Another possibility is to use prefixes declared in the queried document (if known). If the document declares a prefix for the namespace in question (and the context node is in the scope of the declaration), `LibXML` allows you to use the prefix in the XPath expression, e.g.:
570+
* Another possibility is to use prefixes declared in the queried document (if known). If the document declares a prefix for the namespace in question (and the context node is in the scope of the declaration), `LibXML` allows you to use the prefix in the XPath expression, e.g.:
571571

572572
$node.find('/xhtml:html');
573573

@@ -673,21 +673,21 @@ The canonicalize method is similar to Str(). Instead of simply serializing the d
673673

674674
If :$comments is False or not specified, the result-document will not contain any comments that exist in the original document. To include comments into the canonized document, :$comments has to be set to True.
675675

676-
The parameter :$xpath defines the nodeset of nodes that should be visible in the resulting document. This can be used to filter out some nodes. One has to note, that only the nodes that are part of the nodeset, will be included into the result-document. Their child-nodes will not exist in the resulting document, unless they are part of the nodeset defined by the xpath expression.
676+
The parameter :$xpath defines the nodeset of nodes that should be visible in the resulting document. This can be used to filter out some nodes. One has to note, that only the nodes that are part of the nodeset, will be included into the result-document. Their child-nodes will not exist in the resulting document, unless they are part of the nodeset defined by the xpath expression.
677677

678-
If :$xpath is omitted or empty, Str: :C14N will include all nodes in the given sub-tree, using the following XPath expressions: with comments
678+
If :$xpath is omitted or empty, Str: :C14N will include all nodes in the given sub-tree, using the following XPath expressions: with comments
679679

680680
```xpath
681681
(. | .//node() | .//@* | .//namespace::*)
682682
```
683683

684-
and without comments
684+
and without comments
685685

686686
```xpath
687687
(. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
688688
```
689689

690-
An optional parameter :$selector can be used to pass an [LibXML::XPathContext](https://libxml-raku.github.io/LibXML-raku/XPathContext) object defining the context for evaluation of $xpath-expression. This is useful for mapping namespace prefixes used in the XPath expression to namespace URIs. Note, however, that $node will be used as the context node for the evaluation, not the context node of :$selector.
690+
An optional parameter :$selector can be used to pass an [LibXML::XPathContext](https://libxml-raku.github.io/LibXML-raku/XPathContext) object defining the context for evaluation of $xpath-expression. This is useful for mapping namespace prefixes used in the XPath expression to namespace URIs. Note, however, that $node will be used as the context node for the evaluation, not the context node of :$selector.
691691

692692
:v(v1.1) can be passed to specify v1.1 of the C14N specification. The `:$eclusve` flag is not applicable to this level.
693693

@@ -825,7 +825,7 @@ Associative Interface
825825
say $node<species/humps>;
826826
say $node<species><humps>;
827827

828-
This is a lightweight associative interface, based on xpath expressions. `$node.AT-KEY($foo)` is equivalent to `$node.findnodes($foo, :deref)`.
828+
This is a lightweight associative interface, based on xpath expressions. `$node.AT-KEY($foo)` is equivalent to `$node.findnodes($foo, :deref)`.
829829

830830
Copyright
831831
---------

‎docs/Parser.md

Lines changed: 72 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -10,69 +10,68 @@ Parse XML with LibXML
1010
Synopsis
1111
--------
1212

13-
use LibXML;
14-
15-
# Parser constructor
16-
17-
my LibXML $parser .= new: :$catalog, |%opts;
18-
19-
# Parsing XML
20-
21-
$dom = LibXML.parse(
22-
location => $file-or-url,
23-
# parser options ...
24-
);
25-
$dom = LibXML.parse(
26-
file => $file-or-url,
27-
# parser options ...
28-
);
29-
$dom = LibXML.parse(
30-
string => $xml-string,
31-
# parser options ...
32-
);
33-
$dom = LibXML.parse(
34-
io => $raku-file-handle,
35-
# parser options ...
36-
);
37-
# dispatch to above depending on type
38-
$dom = $parser.parse($src ...);
39-
40-
# Parsing HTML
41-
42-
$dom = LibXML.parse(..., :html);
43-
$dom = $parser.parse(..., :html);
44-
$parser.html = True; $parser.parse(...);
45-
46-
# Parsing well-balanced XML chunks
47-
48-
my LibXML::DocumentFragment $chunk = $parser.parse-balanced( string => $wbxml);
49-
50-
# Processing XInclude
51-
52-
$parser.process-xincludes( $doc );
53-
$parser.processXIncludes( $doc );
54-
55-
# Push parser
56-
57-
$parser.parse-chunk($string, :$terminate);
58-
$parser.init-push();
59-
$parser.push($chunk);
60-
$parser.append(@chunks);
61-
$doc = $parser.finish-push( :$recover );
62-
63-
# Set/query parser options
64-
65-
my LibXML $parser .= new: name => $value, ...;
66-
# -OR-
67-
$parser.option-exists($name);
68-
$parser.get-option($name);
69-
$parser.set-option($name, $value);
70-
$parser.set-options(name => $value, ...);
71-
72-
# XML catalogs
73-
my LibXML $parser .= new: catalog => $catalog-file, |%opts
74-
# -OR-
75-
$parser.load-catalog( $catalog-file );
13+
```raku
14+
use LibXML;
15+
16+
# Parser constructor
17+
18+
my LibXML $parser .= new: :$catalog, |%opts;
19+
20+
# Parsing XML
21+
22+
$dom = LibXML.parse(
23+
location => $file-or-url,
24+
# parser options ...
25+
);
26+
$dom = LibXML.parse(
27+
file => $file-or-url,
28+
# parser options ...
29+
);
30+
$dom = LibXML.parse(
31+
string => $xml-string,
32+
# parser options ...
33+
);
34+
$dom = LibXML.parse(
35+
io => $raku-file-handle,
36+
# parser options ...
37+
);
38+
# dispatch to above depending on type
39+
$dom = $parser.parse($src ...);
40+
41+
# Parsing HTML
42+
43+
$dom = LibXML.parse(..., :html);
44+
$dom = $parser.parse(..., :html);
45+
$parser.html = True; $parser.parse(...);
46+
47+
# Parsing well-balanced XML chunks
48+
my LibXML::DocumentFragment $chunk = $parser.parse-balanced( string => $wbxml);
49+
50+
# Processing XInclude
51+
$parser.process-xincludes( $doc );
52+
$parser.processXIncludes( $doc );
53+
54+
# Push parser
55+
$parser.parse-chunk($string, :$terminate);
56+
$parser.init-push();
57+
$parser.push($chunk);
58+
$parser.append(@chunks);
59+
$doc = $parser.finish-push( :$recover );
60+
61+
# Set/query parser options
62+
63+
my LibXML $parser .= new: name => $value, ...;
64+
# -OR-
65+
$parser.option-exists($name);
66+
$parser.get-option($name);
67+
$parser.set-option($name, $value);
68+
$parser.set-options(name => $value, ...);
69+
70+
# XML catalogs
71+
my LibXML $parser .= new: catalog => $catalog-file, |%opts
72+
# -OR-
73+
$parser.load-catalog( $catalog-file );
74+
```
7675

7776
Parsing
7877
-------
@@ -139,13 +138,13 @@ All of the functions listed below will throw an exception if the document is inv
139138
);
140139
$dom = $parser.parse(...);
141140

142-
This method provides an interface to the XML parser that parses given file (or URL), string, or input stream to a DOM tree. The function can be called as a class method or an object method. In both cases it internally creates a new parser instance passing the specified parser options; if called as an object method, it clones the original parser (preserving its settings) and additionally applies the specified options to the new parser. See the constructor `new` and [Parser Options](Parser Options) for more information.
141+
This method provides an interface to the XML parser that parses given file (or URL), string, or input stream to a DOM tree. The function can be called as a class method or an object method. In both cases it internally creates a new parser instance passing the specified parser options; if called as an object method, it clones the original parser (preserving its settings) and additionally applies the specified options to the new parser. See the constructor `new` and [Parser Options](Parser Options) for more information.
143142

144143
Note: Although this method usually returns a `LibXML::Document` object. It can be requisitioned to return other document types by providing a `:sax-handler` that returns an alternate document via a `publish()` method. See [LibXML::SAX::Builder](https://libxml-raku.github.io/LibXML-raku/SAX/Builder). [LibXML::SAX::Handler::XML](https://libxml-raku.github.io/LibXML-raku/SAX/Handler/XML), for example produces pure Raku XML document objects.
145144

146145
#### method parse - `:html` option
147146

148-
use LibXML::Document :HTML;
147+
use LibXML::Document :HTML;
149148
my HTML $dom = LibXML.parse: :html, ...;
150149
my HTML $dom = $parser.parse: :html, ...;
151150

@@ -342,7 +341,7 @@ Each of the flags listed below is labeled
342341

343342
* /parser/
344343

345-
if it can be used with a [LibXML](https://libxml-raku.github.io/LibXML-raku) parser object (i.e. passed to `LibXML.new`, `LibXML.set-option`, etc.)
344+
if it can be used with a [LibXML](https://libxml-raku.github.io/LibXML-raku) parser object (i.e. passed to `LibXML.new`, `LibXML.set-option`, etc.)
346345

347346
* /html/
348347

@@ -352,7 +351,7 @@ Each of the flags listed below is labeled
352351

353352
if it can be used with the [LibXML::Reader](https://libxml-raku.github.io/LibXML-raku/Reader).
354353

355-
Unless specified otherwise, the default for boolean valued options is False.
354+
Unless specified otherwise, the default for boolean valued options is False.
356355

357356
The available options are:
358357

@@ -376,9 +375,9 @@ The available options are:
376375

377376
/parser/
378377

379-
If this option is activated, libxml2 will store the line number of each element node in the parsed document. The line number can be obtained using the `line-number()` method of the [LibXML::Node](https://libxml-raku.github.io/LibXML-raku/Node) class (for non-element nodes this may report the line number of the containing element). The line numbers are also used for reporting positions of validation errors.
378+
If this option is activated, libxml2 will store the line number of each element node in the parsed document. The line number can be obtained using the `line-number()` method of the [LibXML::Node](https://libxml-raku.github.io/LibXML-raku/Node) class (for non-element nodes this may report the line number of the containing element). The line numbers are also used for reporting positions of validation errors.
380379

381-
IMPORTANT: Due to limitations in the libxml2 library line numbers greater than 65535 will be returned as 65535. Please see [http://bugzilla.gnome.org/show_bug.cgi?id=325533](http://bugzilla.gnome.org/show_bug.cgi?id=325533) for more details.
380+
IMPORTANT: Due to limitations in the libxml2 library line numbers greater than 65535 will be returned as 65535. Please see [http://bugzilla.gnome.org/show_bug.cgi?id=325533](http://bugzilla.gnome.org/show_bug.cgi?id=325533) for more details.
382381

383382
* enc
384383

@@ -484,7 +483,7 @@ The available options are:
484483

485484
All attempts to fetch non-local resources (such as DTD or external entities) will fail unless set to True (or custom input-callbacks are defined).
486485

487-
It may be necessary to use the flag `recover` for processing documents requiring such resources while networking is off.
486+
It may be necessary to use the flag `recover` for processing documents requiring such resources while networking is off.
488487

489488
* clean-namespaces
490489

@@ -518,14 +517,14 @@ The following obsolete methods trigger parser options in some special way:
518517

519518
$parser.recover-silently = True;
520519

521-
If called without an argument, returns true if the current value of the `recover` parser option is 2 and returns false otherwise. With a true argument sets the `recover` parser option to 2; with a false argument sets the `recover` parser option to 0.
520+
If called without an argument, returns true if the current value of the `recover` parser option is 2 and returns false otherwise. With a true argument sets the `recover` parser option to 2; with a false argument sets the `recover` parser option to 0.
522521

523522
XML Catalogs
524523
------------
525524

526-
`libxml2` supports XML catalogs. Catalogs are used to map remote resources to their local copies. Using catalogs can speed up parsing processes if many external resources from remote addresses are loaded into the parsed documents (such as DTDs or XIncludes).
525+
`libxml2` supports XML catalogs. Catalogs are used to map remote resources to their local copies. Using catalogs can speed up parsing processes if many external resources from remote addresses are loaded into the parsed documents (such as DTDs or XIncludes).
527526

528-
Note that libxml2 has a global pool of loaded catalogs, so if you apply the method `load-catalog` to one parser instance, all parser instances will start using the catalog (in addition to other previously loaded catalogs).
527+
Note that libxml2 has a global pool of loaded catalogs, so if you apply the method `load-catalog` to one parser instance, all parser instances will start using the catalog (in addition to other previously loaded catalogs).
529528

530529
Note also that catalogs are not used when a custom external entity handler is specified. At the current state it is not possible to make use of both types of resolving systems at the same time.
531530

‎docs/Reader.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ where ... are reader options described below in [Reader options](Reader options)
9999

100100
* ...
101101

102-
the reader further supports various parser options described in [LibXML::Parser](https://libxml-raku.github.io/LibXML-raku/Parser) (specifically those labeled by /reader/).
102+
the reader further supports various parser options described in [LibXML::Parser](https://libxml-raku.github.io/LibXML-raku/Parser) (specifically those labeled by /reader/).
103103

104104
Methods Controlling Parsing Progress
105105
------------------------------------
@@ -345,7 +345,7 @@ Returns a canonical location path to the current element from the root node to
345345

346346
* Namespaced elements are matched by '*', because there is no way to declare prefixes within XPath patterns.
347347

348-
* Unlike `LibXML::Node::nodePath()`, this function does not provide sibling counts (i.e. instead of e.g. '/a/b[1]' and '/a/b[2]' you get '/a/b' for both matches).
348+
* Unlike `LibXML::Node::nodePath()`, this function does not provide sibling counts (i.e. instead of e.g. '/a/b[1]' and '/a/b[2]' you get '/a/b' for both matches).
349349

350350
### method matchesPattern
351351

‎lib/LibXML/Config.rakumod

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,6 @@ has &!external-entity-loader;
193193
proto method external-entity-loader() {*}
194194
multi method external-entity-loader(::?CLASS:U:) is rw { $singleton.external-entity-loader }
195195
multi method external-entity-loader(::?CLASS:D:) is rw {
196-
#method external-entity-loader(--> Callable) is rw {
197196
Proxy.new(
198197
FETCH => { &!external-entity-loader },
199198
STORE => -> $, &loader {

0 commit comments

Comments
 (0)