The use of XML documents in systems configuration is widespread. XML documents represent data that is complex and can be structured in various ways. The XML based editing offers a powerful environment for editing hierarchical and structured XML datasets.

XML editing promises are made in a bundle edit_xml, which is then used in the edit_xml attribute of a files promise. The promiser of the files promise needs to be the XML document that is being edited. Within an edit_xml bundle, various promise types are available to create new or manipulate existing XML documents.

Common Attributes

The following attributes are available in all edit_xml promise types.

build_xpath

Description: Builds an XPath within the XML file

Please note that when build_xpath is defined as an attribute within an edit_xml promise body, the tree described by the specified XPath will be verified and built BEFORE other edit_xml promises within same promise body. Therefore, the file will not be empty during the execution of such promises.

Type: string

Allowed input range: (arbitrary string)

select_xpath

Description: Select the XPath node in the XML file to edit

Edits to the XML document take place within the selected node. This attribute is not used when inserting XML content into an empty file.

Type: string

Allowed input range: (arbitrary string)

build_xpath

This promise type assures that a balanced XML tree, described by the given XPath, will be present within the XML file. If the document is empty, the default promise is to build the XML tree within the document. If the document is not empty, the default promise is to verify the given XPath, and if necessary, locate an insertion node and build the necessary portion of XML tree within selected node. The insertion node is selected as the last unique node that is described by the XPath and also found within the document. The promise object referred to is a literal string representation of an XPath.

    bundle edit_xml example
    {
    build_xpath:
       "/Server/Service/Engine/Host";
    }

Note that typically, only a single XPath is built in each build_xpath promise. You may of course have multiple promises that each build an XPath. The supported syntax used in building an XPath is currently limited to a simple and compact format, as shown in the above example. The XPath must begin with '/', as it is verified and built using an absolute path, from the root node of the document.

The resulting document can then be further modified using insert_tree, set_text, set_attribute etc promises. Using predicate statements to set attributes or text values directly via build_xpath can lead to non-convergent behavior, and is discouraged.

insert_tree

This promise type assures that a balanced XML tree, containing the matching subtree, will be present in the specified node within the XML file. If the subtree is not found, the default promise is to insert the tree into the specified node. The specified node is determined by body-attributes. The promise object referred to is a literal string representation of a balanced XML tree.

    bundle edit_xml example
    {
    insert_tree:

      "<Host name=\"cfe_host\"><Alias>cfe_alias</Alias></Host>"
        select_xpath => "/Server/Service/Engine";
    }

Note that typically, only a single tree, within a single specified node, is inserted in each insert_tree promise. You may of course have multiple promises that each insert a tree.

delete_tree

This promise type assures that a balanced XML tree, containing the matching subtree, will not be present in the specified node within the XML file. If the subtree is found, the default promise is to remove the containing tree from within the specified node. The specified node is determined by body-attributes. The promise object referred to is a literal string representation of a balanced XML subtree.

    bundle edit_xml example
    {
    delete_tree:

      "<Host name=\"cfe_host\"></Host>"
        select_xpath => "/Server/Service/Engine";
    }

Note that typically, only a single tree, within a single specified node, is deleted in each delete_tree promise. You may of course have multiple promises that each delete a tree.

insert_text

This proimse type assures that a value string, containing the matching substring, will be present in the specified node within the XML file. If the substring is not found, the default promise is to append the substring to the end of the existing value string, within the specified node. The specified node is determined by body-attributes. The promise object referred to is a literal string of text.

    bundle edit_xml example
    {
    insert_text:

      "text content to be appended to existing text, including whitespace, within specified node"
        select_xpath => "/Server/Service/Engine/Host/Alias";
    }

Note that typically only a single value string, within a single specified node, is inserted in each insert_text promise. You may of course have multiple promises that each insert a value string.

set_text

This promise type assures that a matching value string will be present in the specified node within the XML file. If the existing value string does not exactly match, the default promise is to replace the existing value string, within the specified node. The specified node is determined by body-attributes. The promise object referred to is a literal string of text.

    bundle edit_xml example
    {
    set_text:
      "text content to replace existing text, including whitespace, within selected node"

        select_xpath => "/Server/Service/Engine/Host/Alias";
    }

Note that typically only a single value string, within a single selected node, is set in each set_text promise. You may of course have multiple promises that each set a value string.

delete_text

This promise type assures that a value string, containing the matching substring, will not be present in the specified node within the XML file. If the substring is found, the default promise is to remove the existing value string, from within the specified node. The specified node is determined by body-attributes. The promise object referred to is a literal string of text.

    bundle edit_xml example
    {
    delete_text:

      "text content to match, as a substring, of text to be deleted from specified node"
        select_xpath => "/Server/Service/Engine/Host/Alias";
    }

Note that typically, only a single value string, within a single specified node, is deleted in each delete_text promise. You may of course have multiple promises that each delete a value string.

set_attribute

This promise type assures that an attribute, with the given name and value, will be present in the specified node within the XML file. If the attribute is not found, the default promise is to insert the attribute, into the specified node. If the attribute is already present, the default promise is to insure that the attribute value is set to the given value. The specified node and attribute value are each determined by body-attributes. The promise object referred to is a literal string representation of the name of the attribute to be set.

    bundle edit_xml example
    {
    set_attribute:
      "name"

        attribute_value => "cfe_host",
           select_xpath => "/Server/Service/Engine/Host";
    }

Note that typically only a single attribute, within a single selected node, is set in each set_attribute promise. You may of course have multiple promises that each set an attribute.

Attributes

attribute_value

Description: Value of the attribute to be inserted into the XPath node of the XML file

Type: string

Allowed input range: (arbitrary string)

delete_attribute

This promise type assures that an attribute, with the given name, will not be present in the specified node within the XML file. If the attribute is found, the default promise is to remove the attribute, from within the specified node. The specified node is determined by body-attributes. The promise object referred to is a literal string representation of the name of the attribute to be deleted.

    bundle edit_xml example
    {
    delete_attribute:
      "attribute name"
        select_xpath => "/Server/Service/Engine/Host";
    }

Note that typically, only a single attribute, within a single specified node, is deleted in each delete_attribute promise. You may of course have multiple promises that each delete an attribute.