LibXML-raku

[Raku LibXML Project] / [LibXML Module] / Config

class LibXML::Config

LibXML Global configuration

Synopsis

use LibXML::Config;
if  LibXML::Config.have-compression { ... }

# change global default for maximum errors
LibXML::Config.max-errors = 42;

# create a parser with its own configuration
my LibXML::Config:D $config .= new: :max-errors(100);
my LibXML::Parser:D $parser .= new: :$config;
my LibXML::Document:D $doc = $parser.parse: :html, :file<messy.html>;

Description

This class holds configuration settings. Some of which are read-only. Others are writeable, as listed below.

In the simple case, the global configuration can be updated to suit the application.

Objects of type LibXML::Config may be created to enable configuration to localised and more explicit.

Note however that the input-callbacks and external-entity-loader are global in the libxml library and need to be configured globally:

LibXML::Config.input-callbacks = @input-callbacks;
LibXML::Config.external-entity-loader = &external-entity-loader;

…or parser-locking needs to be set, which allows multiple local configurations, but disables multi-threaded parsing:

LibXML::Config.parser-locking = True;
my LibXML::Config $config .= new: :@input-callbacks, :&external-entity-loader;

Configuration instance objects may be passed to objects that perform the LibXML::_Configurable role, including LibXML, LibXML::Parser, LibXML::_Reader.

    my $doc = LibXML.parse: :file<doc.xml>, :$config;

DOM objects, generally aren’t configurable, although some particular methods do support a :$config option.

LibXML::Document methods: processXIncludes, validate, Str, Blob, and parse. - LibXML::Element method: appendWellBalancedChunk. - LibXML::Node methods: ast and xpath-class.

Configuration Methods

method version

method version() returns Version:D

Returns the run-time version of the libxml2 library.

method config-version

method config-version() returns Version:D

Returns the version of the libxml2 library that the LibXML module was built against

method have-reader

method have-reader() returns Bool

Returns True if the libxml2 library supports XML Reader (LibXML::Reader) functionality.

method have-writer

method have-writer() returns Bool

Returns True if the libxml2 library supports XML Writer (LibXML::Writer) functionality.

Note: LibXML::Writer is available as a separate module.

method have-schemas

method have-schemas() returns Bool

Returns True if the libxml2 library supports XML Schema (LibXML::Schema) functionality.

method have-threads

method have-threads() returns Bool

Returns True if the libxml2 library supports threads

method have-compression

method have-compression() returns Bool

Returns True if the libxml2 library supports compression

method have-iconv

method have-iconv() returns Bool

Returns True if the libxml2 library supports iconv (unicode encoding)

Serialization Default Options

method skip-xml-declaration

method skip-xml-declaration() is rw returns Bool

Whether to omit ‘<?xml …>’ preamble (default False)

method skip-dtd

method skip-dtd() is rw returns Bool

Whether to omit internal DTDs (default False)

has Bool:D(Any) $!tag-expansion

Whether to output empty tags as ‘’ rather than ‘’ (default False)

method max-errors

method max-errors() is rw returns Int:D

Maximum errors before throwing a fatal X::LibXML::TooManyErrors

Parsing Default Options

method parser-flags

method parser-flags() returns UInt:D

Low-level default parser flags (Read-only)

sub set-external-entity-loader

sub set-external-entity-loader(
    &loader
) returns Mu

External entity handler to be used when parser expand-entities is set.

The routine provided is called whenever the parser needs to retrieve the content of an external entity. It is called with two arguments: the system ID (URI) and the public ID. The value returned by the subroutine is parsed as the content of the entity.

This method can be used to completely disable entity loading, e.g. to prevent exploits of the type described at (http://searchsecuritychannel.techtarget.com/generic/0,295582,sid97_gci1304703,00.html), where a service is tricked to expose its private data by letting it parse a remote file (RSS feed) that contains an entity reference to a local file (e.g. /etc/fstab).

This method acts globally across all parser instances and threads.

A more granular and localised solution to this problem, however, is provided by custom URL resolvers, as in

my LibXML::InputCallback $cb .= new;
sub match($uri) {   # accept file:/ URIs except for XML catalogs in /etc/xml/
  my ($uri) = @_;
  ? ($uri ~~ m|^'file:/'}
     and $uri !~~ m|^'file:///etc/xml/'|)
}
sub deny(|c) { }
$cb.register-callbacks(&match, &deny, &deny, &deny);
$parser.input-callbacks($cb)

method input-callbacks

method input-callbacks is rw returns LibXML::InputCallback

Default input callback handlers.

The LibXML::Config:U input-callbacks method sets and enables a set of input callbacks for the entire process.

The LibXML::Config:U input-callbacks sets up a localised set of input callbacks. Concurrent use of multiple input callbacks is NOT thread-safe and parser-locking also needs to be set to disable concurrent parsing (see below).

See LibXML::InputCallback

parser-locking

This configuration setting will lock the parsing of documents to disable concurrent parsing. It needs to be set to allow per-parser input-callbacks, which are not currently thread safe.

Note: parser-locking defaults to True on Windows, as some platforms have thread-safety issues.

Query Handler

method query-handler

method query-handler() is rw returns LibXML::Config::QueryHandler

Default query handler to service querySelector() and querySelectorAll() methods

See LibXML::XPath::Context

has Bool:D $.with-cache

Enable object re-use per XML node.

Copyright

2001-2007, AxKit.com Ltd.

2002-2006, Christian Glahn.

2006-2009, Petr Pajas.

License

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 http://www.perlfoundation.org/artistic_license_2_0.