Table of Contents
List of Tables
List of Examples
This module exposes a script variable that provides basic parsing and manipulation of XML documents or blocks of XML data. The variable provides ways to access entire XML elements, their text content or their attributes. You can modify the content and attributes as well as adding or removing nodes in the XML tree.
The processing does not take into account any DTDs or schemas in terms of validation.
This module exports the $xml(path) variable.
The xml variables will be available to the process that created them from the moment they were initialized. They will not reset per message or per transaction. If you want to use them on a per message basis you should initialize them each time.
Accessing elements and attributes is based on the tree representation of the XML document thus a complete path from the root node is required. The in-memory equivalent of an XML document is an "XML object" which must be initilized with a well-formed block of XML data before use. In consequence, the path must start with the object name, followed by any number of nodes leading to the desired element.
The grammar that describes the path is:
path = name | name(identifier)+(acces)?
identifier = element(index)?
element = /string | /$var
index = [integer] | [$var]
access = .val | .attr/string | .attr/$var
In order to select between nodes with identical names on a certain level in the tree, an index can be provided, starting from 0.
The sequence of nodes in the path can be followed by .val in order to access the last node's text content or by .attr/attr_name in order to access it's attribute named attr_name. Otherwise the entire element (start-tag, end-tag, children elements and content) is accessed.
Assiging NULL to the variable removes the entire element or it's text content or attribute acording to the access mode.
If you want to insert an element, you must assign a string value (containg a well-formed block of XML data that has a root node) to the parent node. Note that assigning a value directly to a node does not replace it with that value.
IMPORTANT: In XML all characters in the content of the document are significant including blanks and formatting line breaks. An element and it's content will be returned WITH all the whitespaces and newlines and when adding a new node under an existing one, if you want to insert it with indentation, you must include the needed characters in the assigned string.
Other script variables can be used as element names, attribute names and indexes in the path. Variables that will be used as indexes must contain integer values. Variables that will be used as element or attribute names should contain string values.
Example 1.1. Creating a document
... $xml(my_doc) = "<doc></doc>"; # init object $xml(my_doc/doc) = "<list></list>"; # add a "list" node $xml(my_doc/doc/list) = "<item>some_value</item>"; # add an "item" node to the list $xml(my_doc/doc/list) = "<item>another_value</item>"; # add another item to the list $xml(my_doc/doc/list/item.val) = "new_val"; # set text content of previous item $xml(my_doc/doc/list.attr/sort) = "asc"; # add attribute "sort" to list node $xml(my_doc/doc/list.attr/sort) = NULL; # remove previous attribute $xml(my_doc/doc/list/item) = NULL; # remove second item $xml(my_doc/doc/list.val) = "end"; # add text content to list which now has # mixed content $xml(my_doc/doc/list.val) = NULL; # remove the text content xlog("$xml(my_doc/doc/list)\n"); # display the entire list xlog("$xml(my_doc)\n"); # display the entire document $xml(my_doc) = NULL; # clear the entire document ...
Example 1.2. Inserting nodes with indentation
... $xml(my_doc) = "<doc>\n</doc>"; $xml(my_doc/doc) = "\t<list></list>\n"; $xml(my_doc/doc/list) = "\n\t\t<item></item>\n\t"; # this creates the following document: # <doc> # <list> # <item></item> # </list> # </doc> # # without the explicit formating characters the document would be: # <doc><list><item></item></list></doc> ...
Example 1.3. Using script variables in path
... # accessing the attribute of second item in list $var(my_list) = "list"; $var(my_idx) = 1; $var(my_attr) = "sort"; xlog("$xml(my_doc/doc/$var(my_list)/item[$var(my_idx)].attr/$var(my_attr))\n"); ...
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
|1.||Vlad Patrascu (@rvlad-patrascu)||Feb 2017 - Jan 2022|
|2.||Maksym Sobolyev (@sobomax)||Jan 2021 - Jan 2021|
|3.||Razvan Crainea (@razvancrainea)||Mar 2017 - Sep 2019|
|4.||Bogdan-Andrei Iancu (@bogdan-iancu)||Apr 2019 - Apr 2019|
|5.||Peter Lemenkov (@lemenkov)||Jun 2018 - Jun 2018|
|6.||Liviu Chircu (@liviuchircu)||Mar 2017 - Jun 2018|
(1) including any documentation-related commits, excluding merge commits
Copyright © 2017 www.opensips-solutions.com