### ----------------------------------------------------
### -- LibXML
### -- Licenses: Artistic-2.0
### -- Authors: David Warring
### -- File: lib/LibXML/Document.rakumod
### ----------------------------------------------------
### -- Chunk 2 of 2
 subset of the given document.
method setExternalSubset(LibXML::Dtd $dtd is copy, Bool :$validate --> LibXML::Dtd) {
    with $dtd.raw.doc -> $doc {
        $dtd .= clone unless $doc.isSameNode($.raw);
    }

    if $validate {
        .validate(self) with $dtd;
    }
    $dtd.keep: self.raw.setExternalSubset: $dtd.raw;
}
=para If the :validate option is passed, the document is first validated against the DTD.

#| This method removes any external subset from the document
method removeExternalSubset(--> LibXML::Dtd) is dom-boxed {...}
=para If a document has an external subset defined it can be removed from the
    document by using this function. The removed dtd node will be returned.

#| Gets or sets the external DTD for a document.
method externalSubset is rw returns LibXML::Dtd {
    sub FETCH($) { self.getExternalSubset }
    sub STORE($, LibXML::Dtd $dtd) {
        self.setExternalSubset($dtd);
    }
    Proxy.new: :&FETCH, :&STORE;
}

proto method parser(|) handles<parse parseFromString> {*}
multi method parser(::?CLASS:U:) {
    resolve-package 'LibXML::Parser'
}
multi method parser(::?CLASS:D: *%c) {
    self.create: $.parser-class, |%c
}

=begin pod
    =head3 method parse

        my LibXML::Document $doc .= parse($string, |%opts);

    Calling C<LibXML::Document.parse(|c)> is equivalent to calling C<LibXML.parse(|c)>; See the parse method in L<LibXML>.
=end pod

#| Expand XInclude flags
method processXIncludes(LibXML::Config :$config = self.config, |c) is also<process-xincludes> {
    self.parser(:$config).processXIncludes(self, |c);
}

=begin pod
    =head3 method getElementsByTagName

        my LibXML::Element @nodes = $doc.getElementsByTagName($tagname);
        my LibXML::Node::Set $nodes = $doc.getElementsByTagName($tagname);

    Implements the DOM Level 2 function

    =head3 method getElementsByTagNameNS

        my LibXML::Element @nodes = $doc.getElementsByTagNameNS($nsURI,$tagname);
        my LibXML::Node::Set $nodes = $doc.getElementsByTagNameNS($nsURI,$tagname);

    Implements the DOM Level 2 function

    =head3 method getElementsByLocalName

        my LibXML::Element @nodes = $doc.getElementsByLocalName($localname);
        my LibXML::Node::Set $nodes = $doc.getElementsByLocalName($localname);

    This allows the fetching of all nodes from a given document with the given
    Localname.
=end pod

#| Returns the element that has an ID attribute with the given value. If no such element exists, this returns LibXML::Element:U.
method getElementById(Str:D $id --> LibXML::Element) is also<getElementsById> {
    $.raw.getElementById($id)
        andthen self.box(LibXML::Element, $_)
        orelse $.config.class-from(xmlElem)
}
=para Note: the ID of an element may change while manipulating the document. For
    documents with a DTD, the information about ID attributes is only available if
    DTD loading/validation has been requested. For HTML documents parsed with the
    HTML parser ID detection is done automatically. In XML documents, all "xml:id"
    attributes are considered to be of type ID. You can test ID-ness of an
    attribute node with $attr.isId().

#| Index elements for faster XPath searching
method indexElements returns Int { $.raw.IndexElements }
=para This function causes libxml2 to stamp all elements in a document with their
    document position index which considerably speeds up XPath queries for large
    documents. It should only be used with static documents that won't be further
    changed by any DOM methods, because once a document is indexed, XPath will
    always prefer the index to other methods of determining the document order of
    nodes. XPath could therefore return improperly ordered node-lists when applied
    on a document that has been changed after being indexed. It is of course
    possible to use this method to re-index a modified document before using it
    with XPath again. This function is not a part of the DOM specification.

=para This function returns the number of elements indexed, -1 if error occurred, or -2
    if this feature is not available in the running libxml2.

=para After running this function, the LibXML::Element elementIndex() method returns the
    index of the element, with the root element having an index of 1.

=para If this function has not been run, elementIndex() returns 0 for all elements.


=begin pod
=head2 Copyright

2001-2007, AxKit.com Ltd.

2002-2006, Christian Glahn.

2006-2009, Petr Pajas.

=head2 License

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

=end pod


