Xml Chilkat2 Perl Reference Documentation
Chilkat2::Xml
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.Xml
Load XML from strings, files, byte data, or other Chilkat objects, then
save or emit formatted XML when processing is complete.
Move through parent, child, sibling, and selected elements while working
directly with the XML document structure.
Add, update, remove, or rename elements; set text content; and read,
add, modify, or delete attributes.
Locate elements by tag name, content, path, attribute value, or custom
search patterns.
Work with namespace-aware XML, declarations, CDATA, child ordering,
sorting, and subtree insertion or removal.
Store binary data as Base64 and optionally compress or encrypt element
content when XML carries encoded payloads.
For an extended overview, see
Xml Class Overview.
Load, navigate, search, edit, transform, and save in-memory XML trees.
Chilkat.Xml is the primary Chilkat class for in-memory XML tree
manipulation. It supports loading and saving XML, navigating between elements,
reading and writing text content, managing attributes, working with
namespaces, adding and removing subtrees, searching by tag, content, or
attribute, sorting child records, scrubbing XML, handling CDATA and XML
declarations, storing binary data as Base64, and optionally compressing or
encrypting element content.
Load and save XML
Navigate XML trees
Edit elements and attributes
Search and select
Namespaces and structure
Binary and protected content
Xml object reference for the selected
element, while methods ending in 2 update the caller's internal
reference to point to a different element. This distinction is central when
navigating and editing XML trees because it determines whether the current
object stays where it is or moves to another element.
Chilkat.Xml for tree-oriented XML
manipulation, and use Chilkat.XmlDSig,
Chilkat.XmlDSigGen, or related classes when the task is XML
digital signing or signature verification.
Object Creation
use Chilkat2;
my $xml = Chilkat2::Xml->new;
# or set properties (and RaiseError) at creation:
# my $xml = Chilkat2::Xml->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/Xml.pm file holds only this class's documentation (perldoc Chilkat2::Xml).
Perl frees the object when its last reference goes (undef $xml, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::Xml';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::Xml'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
Cdata
my $boolVal = $xml->Cdata;
$xml->Cdata($boolVal);
Controls how this element's text content is emitted. When set to 1, the element content is written inside a CDATA section instead of being emitted as ordinary character data with XML escaping.
< or &. It does not change the logical text value of the element; it only changes how that text is represented in the serialized XML.Content
my $strVal = $xml->Content;
$xml->Content($strVal);
Gets or sets the text content stored directly on this XML element. Child elements are not included in this value.
For example, both of the following elements have This is the content as their Content:
<tag1>This is the content</tag1> <tag2><child1>abc</child1><child2>abc</child2>This is the content</tag2>
ContentInt
my $intVal = $xml->ContentInt;
$xml->ContentInt($intVal);
Gets or sets this element's content as a 32-bit integer. Setting the property converts the integer to its decimal text representation; getting the property interprets the element's text content as an integer.
Content when the value may exceed the range of a 32-bit integer or when the exact lexical representation must be preserved.DebugLogFilePath
my $strVal = $xml->DebugLogFilePath;
$xml->DebugLogFilePath($strVal);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
DocType
my $strVal = $xml->DocType;
$xml->DocType($strVal);
Gets or sets the document type declaration associated with the XML document.
The value represents the document-level DOCTYPE declaration, for example <!DOCTYPE note SYSTEM "note.dtd">.
EmitBom
my $boolVal = $xml->EmitBom;
$xml->EmitBom($boolVal);
Controls whether a byte order mark (BOM, also called a preamble) is written when XML is saved to a file. The default is 0.
This setting is relevant to encodings for which a BOM can be emitted, such as UTF-8 and UTF-16. It does not affect XML returned as a language string by methods such as GetXml.
EmitCompact
my $boolVal = $xml->EmitCompact;
$xml->EmitCompact($boolVal);
Controls whether XML emitted by GetXml and GetXmlSb is compact. When 1, unnecessary formatting whitespace and line breaks are omitted. The default is 0 for backward compatibility.
EmitXmlDecl
my $boolVal = $xml->EmitXmlDecl;
$xml->EmitXmlDecl($boolVal);
Controls whether the XML declaration is included when XML is emitted. The default is 1. When set to 0, output methods such as GetXml and SaveXml omit the declaration.
An XML declaration is the leading construct such as <?xml version="1.0" encoding="utf-8"?>.
Encoding
my $strVal = $xml->Encoding;
$xml->Encoding($strVal);
Gets or sets the encoding value used in the XML declaration. The default is utf-8. This is a document-level setting and may be accessed from any element in the tree.
When XML is loaded, Chilkat sets this property from the encoding declared by the input XML when one is present. If no encoding is declared, the property is reset to utf-8.
Encoding changes the declared/output encoding used when XML is serialized; it does not reinterpret or transcode the already-stored Unicode text inside the in-memory tree.I
my $intVal = $xml->I;
$xml->I($intVal);
Provides a substitution value for [i] in Chilkat tag paths and ChilkatPath expressions. When a path contains [i], the current value of this property is substituted for I.
I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.IsBase64
my $boolVal = $xml->IsBase64;
Returns 1 if this element's content consists only of characters allowed in standard Base64 text, with whitespace ignored. Standard Base64 uses A-Z, a-z, 0-9, +, /, and optional trailing = padding.
J
my $intVal = $xml->J;
$xml->J($intVal);
Provides a substitution value for [j] in Chilkat tag paths and ChilkatPath expressions. When a path contains [j], the current value of this property is substituted for J.
I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.K
my $intVal = $xml->K;
$xml->K($intVal);
Provides a substitution value for [k] in Chilkat tag paths and ChilkatPath expressions. When a path contains [k], the current value of this property is substituted for K.
I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.LastErrorHtml
my $strVal = $xml->LastErrorHtml;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
my $strVal = $xml->LastErrorText;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
my $strVal = $xml->LastErrorXml;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
my $boolVal = $xml->LastMethodSuccess;
$xml->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
NumAttributes
my $intVal = $xml->NumAttributes;
Returns the number of attributes on this element.
For example, <tag attr1="value1" attr2="value2">...</tag> has two attributes. Attribute indexes used by methods such as GetAttributeName and GetAttributeValue are zero-based.
NumChildren
my $intVal = $xml->NumChildren;
Returns the number of direct child elements of this element. Descendants below those children are not included in the count.
SortCaseInsensitive
my $boolVal = $xml->SortCaseInsensitive;
$xml->SortCaseInsensitive($boolVal);
Controls case sensitivity for the XML sorting methods. Set to 1 for case-insensitive string comparisons or 0 for case-sensitive comparisons.
Standalone
my $boolVal = $xml->Standalone;
$xml->Standalone($boolVal);
Controls the standalone pseudo-attribute in the XML declaration. This is a document-level setting and may be accessed from any element in the tree.
Setting this property to 1 causes the declaration to include standalone="yes".
Strict
my $boolVal = $xml->Strict;
$xml->Strict($boolVal);
When Strict is true, the XML loading methods first check that the input is well-formed XML. If it is not, the load fails and the contents of this Xml object are left unchanged. The default is 0.
This applies to LoadXml, LoadXml2, LoadSb, LoadBd, LoadXmlFile and LoadXmlFile2.
Chilkat's XML parser is deliberately tolerant. By default it can accept input that is not well-formed, succeed, and leave a partially populated tree. That is convenient when the goal is a best-effort parse of imperfect input, but it is the wrong behavior when a silently dropped element or attribute changes what the application does.
Set Strict to 1 for XML carrying configuration, credentials, signed content, or security parameters, where an element that quietly failed to load would be acted on as though it had never been present.
The check is for XML 1.0 well-formedness only. It is not a validating parse: no DTD or schema is read, and the document is not checked against one. Markup declarations inside an internal DTD subset are skipped rather than parsed.
0 so that existing applications are unaffected. When a strict load is rejected, this Xml object keeps whatever it held before the call, so a failed reload never leaves the object empty.Tag
my $strVal = $xml->Tag;
$xml->Tag($strVal);
Gets or sets the element name for this element, including any namespace prefix. For example, the tag for <soapenv:Body> is soapenv:Body.
Use TagNsPrefix and TagUnprefixed when the prefix and local portion are needed separately.
TagNsPrefix
my $strVal = $xml->TagNsPrefix;
$xml->TagNsPrefix($strVal);
Gets or sets the namespace prefix portion of this element's tag. For soapenv:Envelope, the namespace prefix is soapenv.
xmlns attributes in the XML.TagPath
my $strVal = $xml->TagPath;
Returns the Chilkat tag path needed to reach this element from the document root. If this object currently references the root element, the returned path is the empty string.
| between element names. It is not an XPath expression.TagUnprefixed
my $strVal = $xml->TagUnprefixed;
$xml->TagUnprefixed($strVal);
Gets or sets the unprefixed portion of this element's tag. For soapenv:Envelope, the unprefixed tag is Envelope.
Use TagNsPrefix to access the prefix separately.
TreeId
my $intVal = $xml->TreeId;
Returns the identifier of the XML tree to which this element belongs. Elements in the same XML document have the same TreeId.
Xml objects can reference different elements in the same underlying tree. Comparing TreeId values is a convenient way to determine whether two element references belong to that same tree.UncommonOptions
my $strVal = $xml->UncommonOptions;
$xml->UncommonOptions($strVal);
Provides a catch-all string for uncommon XML behaviors. The default is the empty string, which is appropriate for normal use.
Leave this property empty unless Chilkat documentation or support identifies a specific option needed for a specialized interoperability case.
topVerboseLogging
my $boolVal = $xml->VerboseLogging;
$xml->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
my $strVal = $xml->Version;
Methods
AccumulateTagContent
# $skipTags is a string
# $str is a string or undef
my $str = $xml->AccumulateTagContent($tag, $skipTags);
Traverses the subtree rooted at the calling element and concatenates the text content of all elements whose tag equals tag.
skipTags is a vertical-bar-delimited list of tag names whose entire subtrees are excluded from the accumulation. For example, script|style skips elements rooted at either of those tags.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddAttribute
# $value is a string
# $success is true or false
my $success = $xml->AddAttribute($name, $value);
Adds an attribute named name with the specified string value to the calling element.
Returns 1 on success and 0 on failure.
AddOrUpdateAttribute or UpdateAttribute when the desired behavior is to update an existing attribute value instead of requiring a new attribute.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddAttributeInt
# $value is an integer
# $success is true or false
my $success = $xml->AddAttributeInt($name, $value);
Adds an attribute named name whose value is the decimal representation of value.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddChildTree
# $success is true or false
my $success = $xml->AddChildTree($tree);
Adds the entire XML subtree referenced by tree as a new direct child of the calling element.
If tree already belongs to another XML document, the subtree is transferred to the destination tree rather than copied as an unrelated duplicate.
TreeId can be used to determine which tree an element reference belongs to.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddOrUpdateAttribute
# $value is a string
$xml->AddOrUpdateAttribute($name, $value);
Sets the string value of an attribute on the calling element. If an attribute named name already exists, its value is replaced; otherwise the attribute is added.
Returns the object, so calls can be chained.
AddOrUpdateAttributeI
# $value is an integer
$xml->AddOrUpdateAttributeI($name, $value);
Sets an integer-valued attribute on the calling element. If an attribute named name already exists, its value is replaced with the decimal representation of value; otherwise the attribute is added.
Returns the object, so calls can be chained.
topAddStyleSheet
$xml->AddStyleSheet($styleSheet);
Adds an XML stylesheet processing instruction to the document. Pass the complete processing-instruction text, for example:
<?xml-stylesheet href="mystyle.css" title="Compact" type="text/css"?>
Returns the object, so calls can be chained.
topAddToAttribute
# $amount is an integer
$xml->AddToAttribute($name, $amount);
Treats the named attribute value as an integer, adds amount, and stores the resulting integer back in the attribute.
If the attribute does not yet exist, this method behaves like AddOrUpdateAttributeI and creates it with amount as the value.
Returns the object, so calls can be chained.
AddToChildContent
# $amount is an integer
$xml->AddToChildContent($tag, $amount);
Finds the child identified by tag, interprets its content as an integer, adds amount, and stores the resulting integer as the child's new content.
Returns the object, so calls can be chained.
topAddToContent
$xml->AddToContent($amount);
Interprets this element's content as an integer, adds amount, and stores the resulting integer as the new content.
Returns the object, so calls can be chained.
topAppendToContent
# $success is true or false
my $success = $xml->AppendToContent($str);
Appends str to the existing text content of the calling element without replacing its child elements.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ChildContentMatches
# $pattern is a string
# $caseSensitive is a boolean
# $flag is true or false
my $flag = $xml->ChildContentMatches($tagPath, $pattern, $caseSensitive);
Returns 1 if the child identified by tagPath has content matching pattern; otherwise returns 0. caseSensitive controls whether letter case is significant.
The pattern may contain * wildcards, where each asterisk matches zero or more characters.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Never dies: false is an answer, not a failure.
topChilkatPath
# $str is a string or undef
my $str = $xml->ChilkatPath($pathCmd);
Evaluates a Chilkat-specific path command that can navigate from the current element, return element content or an attribute value, or move the caller's internal element reference.
This syntax is not XPath. Commands are separated by vertical bars and the expression ends with a return command:
command|command|command|...|returnCommand
Navigation commands include:
TagName- first direct child having that tag.TagName[n]- the indexed direct child having that tag...- parent.++/--- next / previous sibling.TagName{Content}- first direct child with that tag and exact content./T/TagName- traverse the subtree and find the first element with that tag./C/TagName,ContentPattern- traverse for a tag whose content matches a wildcard pattern./C/ContentPattern- traverse for any tag whose content matches a wildcard pattern./A/TagName,AttrName,AttrValuePattern- traverse for a tag having a matching attribute value.
The final return command is:
*- return the current element's content.(AttrName)- return an attribute value.$- move thisXmlobject to the selected element and return an empty string.
I, J, and K properties can be used with [i], [j], and [k] in path expressions.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
Clear
Clears the calling element by removing all child elements, attributes, and text content, and resets its tag name to unnamed.
The element itself remains in the tree; this method clears its contents rather than removing the element from its parent.
Returns the object, so calls can be chained.
topContentMatches
# $caseSensitive is a boolean
# $flag is true or false
my $flag = $xml->ContentMatches($pattern, $caseSensitive);
Returns 1 if this element's content matches pattern; otherwise returns 0. caseSensitive controls whether letter case is significant.
The pattern may contain * wildcards, where each asterisk matches zero or more characters.
Never dies: false is an answer, not a failure.
topCopy
$xml->Copy($node);
Copies the Tag, Content, and attributes from node to the calling element.
AddChildTree or SwapTree when child structure is part of the operation.Returns the object, so calls can be chained.
topCopyRef
$xml->CopyRef($copyFromNode);
Changes this Xml object so that it references the same underlying XML element as copyFromNode. The caller's previous element reference is discarded.
CopyRef does not copy XML data. After the call, both Xml objects refer to the same element, so edits through either reference affect the same tree element.Returns the object, so calls can be chained.
topDecodeEntities
# $str is a string or undef
my $str = $xml->DecodeEntities($str);
Decodes HTML character entities found in str and returns the decoded text. This is a utility operation; it does not modify the XML tree unless the returned string is assigned to an element.
For example, an HTML entity such as & is decoded to &.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DecryptContent
# $success is true or false
my $success = $xml->DecryptContent($password);
Decrypts element content previously produced by EncryptContent, using the same password, and restores the original plaintext content.
Returns 1 on success and 0 on failure.
EncryptContent. It is not a general XML Encryption (XML-Enc) implementation.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
EncryptContent
# $success is true or false
my $success = $xml->EncryptContent($password);
Encrypts the calling element's text content using Chilkat's password-based 128-bit AES-CBC format and replaces the plaintext content with Base64-encoded encrypted data.
Returns 1 on success and 0 on failure.
DecryptContent with the same password to restore the content.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ExtractChildByIndex
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->ExtractChildByIndex($index);
Removes the direct child at zero-based index from the calling element and returns an Xml object for the detached child subtree.
RemoveChildByIndex, extraction gives the caller a reference to the removed subtree so it can be retained, inspected, or attached elsewhere.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
ExtractChildByName
# $attrName is a string
# $attrValue is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->ExtractChildByName($tagPath, $attrName, $attrValue);
Finds, removes, and returns the first child selected by tagPath and the optional attribute criteria.
If attrName and attrValue are empty, the first child matching the tag/path is extracted. If attrName is provided, the child must have that attribute. If attrValue is also provided, the attribute value must match exactly.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
FindChild
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->FindChild($tagPath);
Returns an Xml object referencing the child selected by tagPath. The calling object remains positioned on its current element.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
FindChild2
# $success is true or false
my $success = $xml->FindChild2($tagPath);
Moves the calling Xml object's internal reference to the child selected by tagPath. Returns 1 when the child is found and the move succeeds; otherwise returns 0.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FindNextRecord
# $contentPattern is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->FindNextRecord($tagPath, $contentPattern);
Finds the next direct child record for which the descendant identified by tagPath has content matching contentPattern. This is intended for iterating record-like child elements.
The content pattern may contain * wildcards.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
FindOrAddNewChild
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->FindOrAddNewChild($tagPath);
Returns the child selected by tagPath if it already exists. If it does not exist, creates the required child path with empty content and returns the resulting child element.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Use NewChild instead when duplicate children with the same tag are intentional.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
FirstChild
my $xml2 = $xml->FirstChild();
Returns an Xml object referencing the first direct child of the calling element.
A common forward-iteration pattern is FirstChild followed by repeated calls to NextSibling.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
FirstChild2
my $flag = $xml->FirstChild2();
Moves the calling Xml object's internal reference to its first direct child. Returns 1 if a first child exists; otherwise returns 0.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Never dies: false is an answer, not a failure.
GetAttributeName
# $str is a string or undef
my $str = $xml->GetAttributeName($index);
Returns the name of the attribute at zero-based index. Use NumAttributes to determine the valid index range.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetAttributeValue
# $str is a string or undef
my $str = $xml->GetAttributeValue($index);
Returns the value of the attribute at zero-based index. Use NumAttributes to determine the valid index range.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetAttributeValueInt
# $n is an integer
my $n = $xml->GetAttributeValueInt($index);
Returns the value of the attribute at zero-based index, interpreted as a 32-bit integer.
GetAttrValue
# $str is a string or undef
my $str = $xml->GetAttrValue($name);
Returns the value of the attribute named name on the calling element.
Use HasAttribute when the application must distinguish a missing attribute from an attribute whose value is empty.
Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is.
GetAttrValueInt
# $n is an integer
my $n = $xml->GetAttrValueInt($name);
Returns the value of the attribute named name interpreted as a 32-bit integer. Returns 0 if the attribute does not exist.
0, call HasAttribute first when that distinction matters.GetChild
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->GetChild($index);
Returns an Xml object referencing the direct child at zero-based index. The calling object remains positioned on its current element.
Use NumChildren to determine the valid child range.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
GetChild2
# $success is true or false
my $success = $xml->GetChild2($index);
Moves the calling Xml object's internal reference to the direct child at zero-based index. Returns 1 on success and 0 if the child cannot be selected.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetChildAttrValue
# $attrName is a string
# $str is a string or undef
my $str = $xml->GetChildAttrValue($tagPath, $attrName);
Returns the value of attribute attrName on the descendant element selected by tagPath.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is.
GetChildBoolValue
# $flag is true or false
my $flag = $xml->GetChildBoolValue($tagPath);
Returns the integer content of the child selected by tagPath as a Boolean value: content equal to 0 yields 0; a non-zero integer yields 1.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Never dies: false is an answer, not a failure.
GetChildContent
# $str is a string or undef
my $str = $xml->GetChildContent($tagPath);
Returns the text content of the child selected by tagPath.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Content; nested child elements are not serialized into this string.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is.
GetChildContentByIndex
# $str is a string or undef
my $str = $xml->GetChildContentByIndex($index);
Returns the text content of the direct child at zero-based index. Use NumChildren to determine the valid range.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetChildContentSb
# $sb is a Chilkat2::StringBuilder
# $success is true or false
my $success = $xml->GetChildContentSb($tagPath, $sb);
Finds the element selected by tagPath and appends that element's text content to sb.
The existing contents of the StringBuilder are preserved.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetChildExact
# $content is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->GetChildExact($tag, $content);
Returns the first direct child whose tag equals tag and whose text content exactly equals content.
The calling object remains positioned on its current element.
Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
GetChildIntValue
# $n is an integer
my $n = $xml->GetChildIntValue($tagPath);
Returns the content of the child selected by tagPath, interpreted as a 32-bit integer.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.GetChildContent and parse the returned text separately when values may exceed the range of a 32-bit integer.GetChildTag
# $str is a string or undef
my $str = $xml->GetChildTag($index);
Returns the tag name of the direct child at zero-based index. Use NumChildren to determine the valid index range.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetChildTagByIndex
# $str is a string or undef
my $str = $xml->GetChildTagByIndex($index);
Returns the tag name of the direct child at zero-based index. Use NumChildren to determine the valid index range.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetChildWithAttr
# $attrName is a string
# $attrValue is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->GetChildWithAttr($tagPath, $attrName, $attrValue);
Returns the child selected by tagPath that also has an attribute named attrName whose value exactly equals attrValue.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
GetChildWithContent
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->GetChildWithContent($content);
Returns the first direct child whose text content exactly equals content. The child tag may be any value.
Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
GetChildWithTag
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->GetChildWithTag($tagPath);
Returns an Xml object referencing the child selected by tagPath. The calling object remains positioned on its current element.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
GetChildWithTag2
# $success is true or false
my $success = $xml->GetChildWithTag2($tagPath);
Moves the calling Xml object's internal reference to the child selected by tagPath. Returns 1 when the child is found and the move succeeds; otherwise returns 0.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetNthChildWithTag
# $n is an integer
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->GetNthChildWithTag($tag, $n);
Returns the zero-based nth direct child whose tag exactly equals tag. Children with other tag names are ignored when counting matches.
Use NumChildrenHavingTag to determine how many matching children are available.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
GetNthChildWithTag2
# $n is an integer
# $success is true or false
my $success = $xml->GetNthChildWithTag2($tag, $n);
Moves the calling Xml object's internal reference to the zero-based nth direct child whose tag equals tag. Returns 1 on success and 0 when no such child exists.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetParent
my $xml2 = $xml->GetParent();
Returns an Xml object referencing this element's parent. Returns no parent when the current element is the document root.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
GetParent2
my $success = $xml->GetParent2();
Moves the calling Xml object's internal reference to its parent. Returns 1 if a parent exists; otherwise returns 0 when already at the root.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetRoot
my $xml2 = $xml->GetRoot();
Returns an Xml object referencing the root element of the XML tree that contains the current element. The calling object remains positioned on its current element.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
GetRoot2
Moves the calling Xml object's internal reference to the root element of its XML tree.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns the object, so calls can be chained.
GetSelf
my $xml2 = $xml->GetSelf();
Returns a new Xml object that references the same underlying XML element as the calling object.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
GetXml
my $str = $xml->GetXml();
Serializes the XML tree or subtree rooted at the current element and returns the XML text.
When called while positioned on the document root, the XML declaration is included if EmitXmlDecl is 1. When called on a non-root element, only that subtree is emitted and the document declaration is not included.
EmitCompact, Encoding, Standalone, and related document/output properties affect serialization as applicable.
Encoding declaration describes serialized XML encoding, while actual byte encoding matters when XML is written to a file or byte-oriented destination.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetXmlBd
Serializes the XML tree or subtree rooted at the current element and appends the encoded XML bytes to bd.
The existing contents of the BinData object are preserved. The XML output encoding is governed by the XML document's output settings, including Encoding.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetXmlSb
Serializes the XML tree or subtree rooted at the current element and appends the resulting XML text to sb.
The existing contents of sb are preserved. Output properties such as EmitCompact and EmitXmlDecl apply as appropriate.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
HasAttribute
# $flag is true or false
my $flag = $xml->HasAttribute($name);
Returns 1 if the calling element has an attribute named name; otherwise returns 0.
Never dies: false is an answer, not a failure.
topHasAttrWithValue
# $value is a string
# $flag is true or false
my $flag = $xml->HasAttrWithValue($name, $value);
Returns 1 if the calling element has an attribute named name whose value exactly equals value; otherwise returns 0.
Never dies: false is an answer, not a failure.
topHasChildWithContent
# $flag is true or false
my $flag = $xml->HasChildWithContent($content);
Returns 1 if any direct child has text content exactly equal to content; otherwise returns 0.
Never dies: false is an answer, not a failure.
topHasChildWithTag
# $flag is true or false
my $flag = $xml->HasChildWithTag($tagPath);
Returns 1 if the child selected by tagPath exists; otherwise returns 0.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Never dies: false is an answer, not a failure.
HasChildWithTagAndContent
# $content is a string
# $flag is true or false
my $flag = $xml->HasChildWithTagAndContent($tagPath, $content);
Returns 1 if the child selected by tagPath exists and its text content exactly equals content; otherwise returns 0.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Never dies: false is an answer, not a failure.
topInsertChildTreeAfter
# $tree is a Chilkat2::Xml
$xml->InsertChildTreeAfter($index, $tree);
Inserts the entire subtree referenced by tree as a direct child immediately after the existing child at zero-based index.
If tree belongs to another XML document, the subtree is transferred to the destination tree.
Returns the object, so calls can be chained.
InsertChildTreeBefore
# $tree is a Chilkat2::Xml
$xml->InsertChildTreeBefore($index, $tree);
Inserts the entire subtree referenced by tree as a direct child immediately before the existing child at zero-based index.
If tree belongs to another XML document, the subtree is transferred to the destination tree.
Returns the object, so calls can be chained.
LastChild
my $xml2 = $xml->LastChild();
Returns an Xml object referencing the last direct child of the calling element.
A common reverse-iteration pattern is LastChild followed by repeated calls to PreviousSibling.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
LastChild2
my $success = $xml->LastChild2();
Moves the calling Xml object's internal reference to its last direct child. Returns 1 if a last child exists; otherwise returns 0.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadBd
# $autoTrim is a boolean
# $success is true or false
my $success = $xml->LoadBd($bd, $autoTrim);
Parses XML from the bytes contained in bd and replaces the calling object's current XML tree with the loaded document.
If autoTrim is 1, leading and trailing whitespace is removed from each leaf element's text content during loading.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadSb
# $autoTrim is a boolean
# $success is true or false
my $success = $xml->LoadSb($sb, $autoTrim);
Parses XML from the current contents of sb and replaces the calling object's current XML tree with the loaded document.
If autoTrim is 1, leading and trailing whitespace is removed from each leaf element's text content while loading.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadXml
# $success is true or false
my $success = $xml->LoadXml($xmlData);
Parses the XML text in xmlData and replaces the calling object's current XML tree content with the loaded document root. Returns 1 if parsing succeeds.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadXml2
# $autoTrim is a boolean
# $success is true or false
my $success = $xml->LoadXml2($xmlData, $autoTrim);
Parses the XML text in xmlData and replaces the current XML tree, like LoadXml. The autoTrim argument additionally controls whether leading and trailing whitespace is removed from each leaf element's text content while loading.
autoTrim to 0 when leading or trailing text whitespace is significant to the application.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadXmlFile
# $success is true or false
my $success = $xml->LoadXmlFile($fileName);
Reads and parses an XML document from fileName, replacing the calling object's current XML tree with the loaded document root. Returns 1 on success.
The file's XML declaration and byte encoding are used as part of normal XML parsing.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadXmlFile2
# $autoTrim is a boolean
# $success is true or false
my $success = $xml->LoadXmlFile2($fileName, $autoTrim);
Reads and parses an XML document from fileName, replacing the current XML tree. The autoTrim argument controls whether leading and trailing whitespace is removed from each leaf element's text content.
autoTrim to 0 when leading or trailing text whitespace must be preserved exactly.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
NewChild
# $content is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->NewChild($tagPath, $content);
Creates and returns a new child at tagPath with the specified text content. A new child is created even when a child with the same tag already exists.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed. Use FindOrAddNewChild when duplicate final children should be avoided.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
NewChild2
# $content is a string
$xml->NewChild2($tagPath, $content);
Creates a new child at tagPath with the specified text content, but does not return a separate Xml object for the new element.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed.Returns the object, so calls can be chained.
NewChildAfter
# $tag is a string
# $content is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->NewChildAfter($index, $tag, $content);
Creates a new direct child with the specified tag and content, inserts it immediately after the child at zero-based index, and returns the new child element.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
NewChildBefore
# $tag is a string
# $content is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->NewChildBefore($index, $tag, $content);
Creates a new direct child with the specified tag and content, inserts it immediately before the child at zero-based index, and returns the new child element.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
NewChildInt2
# $value is an integer
$xml->NewChildInt2($tagPath, $value);
Creates a new child at tagPath whose content is the decimal representation of value. No separate child object is returned.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed.Returns the object, so calls can be chained.
NextInTraversal2
# $flag is true or false
my $flag = $xml->NextInTraversal2($sbState);
Moves the calling Xml object to the next element in a depth-first traversal of the tree and updates sbState with the traversal state.
Pass an empty StringBuilder when beginning a traversal, then reuse the same sbState for each subsequent call.
NextInTraversal method that returns another Xml object.Never dies: false is an answer, not a failure.
NextSibling
my $xml2 = $xml->NextSibling();
Returns an Xml object referencing the current element's next sibling, or no object when there is no next sibling.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
NextSibling2
my $flag = $xml->NextSibling2();
Moves the calling Xml object's internal reference to its next sibling. Returns 1 if one exists; otherwise returns 0.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Never dies: false is an answer, not a failure.
NumChildrenAt
# $n is an integer
my $n = $xml->NumChildrenAt($tagPath);
Returns the number of direct children of the element selected by tagPath. Returns -1 if the path does not identify an existing element.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.NumChildrenHavingTag
# $n is an integer
my $n = $xml->NumChildrenHavingTag($tag);
Returns the number of direct children whose tag exactly equals tag. Descendants below those children are not included.
PreviousSibling
my $xml2 = $xml->PreviousSibling();
Returns an Xml object referencing the current element's previous sibling, or no object when there is no previous sibling.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
PreviousSibling2
my $success = $xml->PreviousSibling2();
Moves the calling Xml object's internal reference to its previous sibling. Returns 1 if one exists; otherwise returns 0.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
PruneAttribute
# $n is an integer
my $n = $xml->PruneAttribute($attrName);
Recursively traverses the subtree rooted at the calling element and removes every occurrence of the attribute named attrName.
Returns the number of attributes removed.
topPruneTag
# $n is an integer
my $n = $xml->PruneTag($tag);
Recursively traverses the subtree rooted at the calling element and removes every element whose tag equals tag. Each removed element's entire descendant subtree is removed with it.
Returns the number of matching tag occurrences removed.
RemoveAllAttributes
my $success = $xml->RemoveAllAttributes();
Removes every attribute from the calling element. Returns 1 on success.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
RemoveAllChildren
Removes all direct child elements and their subtrees from the calling element. The calling element's own tag, attributes, and text content are retained.
Returns the object, so calls can be chained.
topRemoveAttribute
# $success is true or false
my $success = $xml->RemoveAttribute($name);
Removes the attribute named name from the calling element. Returns 1 when the operation succeeds.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
RemoveChild
$xml->RemoveChild($tagPath);
Removes all child elements selected by tagPath beneath the calling element.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.ExtractChild... method when the removed element must be retained.Returns the object, so calls can be chained.
RemoveChildByIndex
$xml->RemoveChildByIndex($index);
Removes the direct child at zero-based index, including that child's entire subtree.
Returns the object, so calls can be chained.
RemoveChildWithContent
$xml->RemoveChildWithContent($content);
Removes all direct children whose text content exactly equals content, including each removed child's subtree.
Returns the object, so calls can be chained.
RemoveFromTree
Detaches the calling element and its entire subtree from its parent. The detached element becomes the root of its own independent XML tree.
Xml object referencing the detached subtree.Returns the object, so calls can be chained.
RemoveStyleSheet
# $attrValue is a string
# $n is an integer
my $n = $xml->RemoveStyleSheet($attrName, $attrValue);
Removes XML stylesheet processing instructions whose attribute named attrName has the value attrValue.
Returns the number of matching stylesheet declarations removed, or -1 if an error occurs.
SaveBinaryContent
# $unzipFlag is a boolean
# $decryptFlag is a boolean
# $password is a string
# $success is true or false
my $success = $xml->SaveBinaryContent($filename, $unzipFlag, $decryptFlag, $password);
Decodes the binary content stored in this element and writes the resulting bytes to filename. Set unzipFlag and decryptFlag to reverse the transformations originally applied, and supply the corresponding password when decrypting.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SaveXml
# $success is true or false
my $success = $xml->SaveXml($fileName);
Serializes the XML tree or subtree rooted at the current element and writes it to fileName.
Document/output properties such as Encoding, EmitBom, EmitXmlDecl, and EmitCompact affect the generated output as applicable.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
Scrub
$xml->Scrub($directives);
Recursively normalizes the XML subtree rooted at the calling element according to the comma-separated keywords in directives.
Supported directives are:
AttrTrimEnds- remove leading and trailing whitespace from attribute values.AttrTrimInside- replace tabs, CR, and LF with spaces and collapse repeated spaces inside attribute values.ContentTrimEnds- remove leading and trailing whitespace from element content.ContentTrimInside- normalize internal tabs/line breaks/spaces in element content.LowercaseAttrs- convert attribute names to lowercase.LowercaseTags- convert tag names to lowercase.RemoveCtrl- remove US-ASCII control characters with values 0-31 except TAB, CR, and LF.
Returns the object, so calls can be chained.
SearchAllForContent
# $contentPattern is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->SearchAllForContent($afterPtr, $contentPattern);
Returns the first element whose text content matches contentPattern, regardless of tag name.
The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.
Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.
afterPtr on the next call to continue to the next match. Continue until no further element is returned.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
SearchAllForContent2
# $contentPattern is a string
# $success is true or false
my $success = $xml->SearchAllForContent2($afterPtr, $contentPattern);
Performs the same breadth-first content search as SearchAllForContent, but moves the calling Xml object's internal reference to the matching element instead of returning a separate element object.
The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.
Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SearchForAttribute
# $tag is a string
# $attr is a string
# $valuePattern is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->SearchForAttribute($afterPtr, $tag, $attr, $valuePattern);
Returns the first element whose tag equals tag, that has an attribute named attr, and whose attribute value matches valuePattern.
The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.
Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.
afterPtr to continue searching after that element.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
SearchForAttribute2
# $tag is a string
# $attr is a string
# $valuePattern is a string
# $success is true or false
my $success = $xml->SearchForAttribute2($afterPtr, $tag, $attr, $valuePattern);
Performs the same breadth-first tag/attribute search as SearchForAttribute, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.
The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.
Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SearchForContent
# $tag is a string
# $contentPattern is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->SearchForContent($afterPtr, $tag, $contentPattern);
Returns the first element whose tag equals tag and whose text content matches contentPattern.
The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.
Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.
afterPtr to continue searching after that element.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
SearchForContent2
# $tag is a string
# $contentPattern is a string
# $success is true or false
my $success = $xml->SearchForContent2($afterPtr, $tag, $contentPattern);
Performs the same breadth-first tag/content search as SearchForContent, but moves the calling Xml object's internal reference to the matching element.
The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.
Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SearchForTag
# $tag is a string
# $xml2 is a Chilkat2::Xml or undef
my $xml2 = $xml->SearchForTag($afterPtr, $tag);
Returns the first element whose tag exactly equals tag.
The search is breadth-first within the subtree rooted at the caller. afterPtr identifies the element after which searching begins. To begin at the first candidate, use undef where the language binding permits it; ActiveX callers should pass a reference to the caller's element.
afterPtr to find the next matching tag. Continue until no further element is returned.Returns undef if not found: this is not an error, and it never dies, whatever RaiseError is. The returned object is new and independent of this one, and inherits its RaiseError.
SearchForTag2
# $tag is a string
# $success is true or false
my $success = $xml->SearchForTag2($afterPtr, $tag);
Performs the same breadth-first tag search as SearchForTag, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.
Use afterPtr in the same way as with SearchForTag to begin or continue the search.
Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetBinaryContentBd
# $zipFlag is a boolean
# $encryptFlag is a boolean
# $password is a string
# $success is true or false
my $success = $xml->SetBinaryContentBd($data, $zipFlag, $encryptFlag, $password);
Stores the bytes in data as binary content on this element, with optional ZIP compression and optional password-based AES encryption. The stored binary representation is emitted as Base64 text when XML is serialized.
If zipFlag is 1, the bytes are compressed first. If encryptFlag is 1, the data is encrypted using Chilkat's 128-bit Rijndael/AES format and password.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetBinaryContentFromFile
# $zipFlag is a boolean
# $encryptFlag is a boolean
# $password is a string
# $success is true or false
my $success = $xml->SetBinaryContentFromFile($filename, $zipFlag, $encryptFlag, $password);
Reads the bytes from filename and stores them as this element's binary content, with optional ZIP compression and optional password-based encryption. The resulting stored data is represented as Base64 when XML text is generated.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SortByAttribute
# $ascending is a boolean
$xml->SortByAttribute($attrName, $ascending);
Sorts the calling element's direct children by the string value of attribute attrName. Set ascending to 1 for ascending order or 0 for descending order.
SortCaseInsensitive controls case sensitivity for string sorting.
Returns the object, so calls can be chained.
topSortByAttributeInt
# $ascending is a boolean
$xml->SortByAttributeInt($attrName, $ascending);
Sorts the calling element's direct children numerically by the value of attribute attrName, interpreting each sort value as an integer rather than comparing the text lexicographically.
Set ascending to 1 for ascending order or 0 for descending order.
Returns the object, so calls can be chained.
topSortByContent
$xml->SortByContent($ascending);
Sorts the calling element's direct children by their text content. Set ascending to 1 for ascending order or 0 for descending order.
SortCaseInsensitive controls case sensitivity for the string comparison.
Returns the object, so calls can be chained.
SortByTag
$xml->SortByTag($ascending);
Sorts the calling element's direct children by tag name. Set ascending to 1 for ascending order or 0 for descending order.
SortCaseInsensitive controls case sensitivity for the tag-name comparison.
Returns the object, so calls can be chained.
SortRecordsByAttribute
# $attrName is a string
# $ascending is a boolean
$xml->SortRecordsByAttribute($sortTag, $attrName, $ascending);
Treats each direct child as a record and sorts those records by the value of attribute attrName on the record's child identified by sortTag.
Set ascending to 1 for ascending order or 0 for descending order. String comparisons honor SortCaseInsensitive.
Returns the object, so calls can be chained.
topSortRecordsByContent
# $ascending is a boolean
$xml->SortRecordsByContent($sortTag, $ascending);
Treats each direct child as a record and sorts those records by the text content of the record's child named sortTag.
Set ascending to 1 for ascending order or 0 for descending order. String comparisons honor SortCaseInsensitive.
Returns the object, so calls can be chained.
SortRecordsByContentInt
# $ascending is a boolean
$xml->SortRecordsByContentInt($sortTag, $ascending);
Treats each direct child as a record and sorts those records numerically by the integer content of the record's child named sortTag.
Numeric comparison is used instead of lexicographic string comparison. Set ascending to 1 for ascending order or 0 for descending order.
Returns the object, so calls can be chained.
topSwapNode
# $success is true or false
my $success = $xml->SwapNode($node);
Swaps the calling element's tag, text content, and attributes with those of node.
Returns 1 on success and 0 on failure.
SwapTree when child subtrees should also be exchanged.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SwapTree
# $success is true or false
my $success = $xml->SwapTree($tree);
Swaps the calling element's complete tree state with tree, including tag, text content, attributes, and children.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
TagContent
# $str is a string or undef
my $str = $xml->TagContent($tagName);
Searches the subtree rooted at the calling element for the first element whose tag equals tagName and returns that element's text content.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
TagEquals
# $flag is true or false
my $flag = $xml->TagEquals($tag);
Returns 1 if the calling element's complete tag name, including any namespace prefix, exactly equals tag; otherwise returns 0.
Never dies: false is an answer, not a failure.
topTagIndex
# $n is an integer
my $n = $xml->TagIndex($tagPath);
Returns the zero-based child index of the element selected by tagPath. Returns -1 when no matching element is found at that path.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.GetChild, RemoveChildByIndex, and the insertion methods.TagNsEquals
# $flag is true or false
my $flag = $xml->TagNsEquals($ns);
Returns 1 if this element's namespace-prefix portion exactly equals ns; otherwise returns 0.
For example, the namespace prefix of soapenv:Body is soapenv.
Never dies: false is an answer, not a failure.
TagUnpEquals
# $flag is true or false
my $flag = $xml->TagUnpEquals($unprefixedTag);
Returns 1 if this element's unprefixed tag exactly equals unprefixedTag; otherwise returns 0.
For example, the unprefixed tag of soapenv:Body is Body.
Never dies: false is an answer, not a failure.
UnzipContent
my $success = $xml->UnzipContent();
Reverses ZipContent: decodes and decompresses the calling element's compressed content and replaces the stored Base64-compressed representation with the original content.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UnzipTree
my $success = $xml->UnzipTree();
Reverses ZipTree: decompresses the stored representation and reconstructs the calling element's previously compressed subtree.
The element's tag and attributes, which are not replaced by ZipTree, remain associated with the restored tree.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UpdateAt
# $autoCreate is a boolean
# $value is a string
# $success is true or false
my $success = $xml->UpdateAt($tagPath, $autoCreate, $value);
Sets the text content of the element selected by tagPath to value.
If autoCreate is 1, missing elements along the path are created as needed. If it is 0, the update requires the target path to already exist.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UpdateAttrAt
# $autoCreate is a boolean
# $attrName is a string
# $attrValue is a string
# $success is true or false
my $success = $xml->UpdateAttrAt($tagPath, $autoCreate, $attrName, $attrValue);
Sets attribute attrName to attrValue on the element selected by tagPath. The attribute is added when it does not already exist.
If autoCreate is 1, missing elements along the path are created as needed. If it is 0, the target path must already exist.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UpdateAttribute
# $attrValue is a string
# $success is true or false
my $success = $xml->UpdateAttribute($attrName, $attrValue);
Sets attribute attrName to attrValue. If the attribute already exists its value is replaced; otherwise the attribute is added.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UpdateAttributeInt
# $value is an integer
# $success is true or false
my $success = $xml->UpdateAttributeInt($attrName, $value);
Sets attribute attrName to the decimal representation of integer value. Use UpdateAttribute for string values.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UpdateChildContent
# $value is a string
$xml->UpdateChildContent($tagPath, $value);
Sets the text content of the child selected by tagPath to value. Missing elements along the path are automatically created as needed.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns the object, so calls can be chained.
UpdateChildContentInt
# $value is an integer
$xml->UpdateChildContentInt($tagPath, $value);
Sets the content of the child selected by tagPath to the decimal representation of integer value.
|-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.Returns the object, so calls can be chained.
topZipContent
my $success = $xml->ZipContent();
ZIP-compresses this element's text content and replaces the original content with Base64-encoded compressed data.
Returns 1 on success and 0 on failure.
UnzipContent to restore the original content.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ZipTree
my $success = $xml->ZipTree();
ZIP-compresses the calling element's content together with its entire child subtree and replaces that structure with Base64-encoded compressed data.
The calling element's tag and attributes are not changed. Call UnzipTree to reconstruct the compressed subtree.
Returns 1 on success and 0 on failure.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.