Returns a
String
that is an XML representation of
source,
which should be an
Array,
a compound object that associates names with values
(e.g., a
Dictionary),
a
String,
or
NULL.
yoixToXML
processes arrays and compound objects recursively and uses the equivalent of
toString
to get the string value associated with any other object that is not a
String.
When
source
is an
Array
elements are grouped in key/value pairs and the string value associated with the element
at the odd index is mapped to an element in the generated XML that has a tag name that
is the string obtained directly (not recursively) from the element at the even index.
When
source
is a compound object the string value associated with each element is mapped to an
element in the generated XML that has a tag name that matches its name in
source.
When
source
is a
String
the result is an XML representation of
source
that uses
CDATA
sections, when necessary, to protect characters or sequences of characters that may need to
be escaped.
Control names used by
xmlToYoix
usually get the following special treatment when they are encountered by
yoixToXML:
-
$attributes
- if its value is an
Array
or a compound object, like a
Dictionary,
then the elements in it that are strings are used to build the XML attributes that are associated
with the element that
yoixToXML
is currently working on, otherwise it is ignored.
-
$text
- if its value is a string then it is immediately appended to the XML string
that is being built, otherwise it is ignored.
-
$ws
- any value associated with this name is currently ignored, which means
yoixToXML
does not reproduce boundary white-space recorded by
xmlToYoix.
The optional
flags
argument, which by default has the value
0,
can be used to control some of the low level details of the conversion process
and should be a bitmask created using one or more of the following
yoix.parser
constants:
-
ACCEPT_ALL_NAMES
- setting this bit means the
$attributes,
$text,
and
$ws
control names should be treated like regular element names, even though they are not valid XML names.
-
ADD_XML_DECLARATION
- setting this bit means the output starts with a simple XML declaration.
-
OMIT_NULL_ELEMENTS
- setting this bit means ignore
NULL
elements in an
Array
or compound object.
-
USE_EMPTY_ELEMENT_TAG
- setting this bit means empty elements are represented by a single empty-element tag that begins with
<
and ends with
/>.
The optional
indent
argument, which is
NULL
by default, can be used to add pretty-printing white-space to the output string.
When
indent
is not
NULL
each element is assigned a
level
that starts at
0
and is incremented by
1
whenever another
Array
or compound object is recursively processed.
Elements at the same level are separated by a newline which is immediately followed by the
indent
string concatenated
level
times.
| |
| Example: |
The program,
import yoix.*.*;
Array message = {
"$attributes",
new Dictionary {
String attr1 = "value 1";
String attr2 = "value 2";
},
"line",
" Now is the time",
"line",
"for all good men ",
"line",
"\tto come to the aid of their party.",
"line",
NULL,
};
Dictionary dict = {
Array message = message;
};
String indent = "\t";
int flags = 0;
printf("flags=0, indent=\"%s\"\n", cstring(indent));
printf("%s\n", yoixToXML(message, flags, indent));
printf("\nflags=0, indent=\"%s\"\n", cstring(indent));
printf("%s\n", yoixToXML(dict, flags, indent));
flags = ADD_XML_DECLARATION|OMIT_NULL_ELEMENTS;
indent = " ";
printf("\nflags=ADD_XML_DECLARATION|OMIT_NULL_ELEMENTS,
indent=\"%s\"\n", cstring(indent));
printf("%s\n", yoixToXML(dict, flags, indent));
prints something like
flags=0, indent="\t"
<line> Now is the time</line>
<line>for all good men </line>
<line> to come to the aid of their party.</line>
<line></line>
flags=0, indent="\t"
<message attr1="value 1" attr2="value 2">
<line> Now is the time</line>
<line>for all good men </line>
<line> to come to the aid of their party.</line>
<line></line>
</message>
flags=ADD_XML_DECLARATION|OMIT_NULL_ELEMENTS, indent=" "
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<message attr1="value 1" attr2="value 2">
<line> Now is the time</line>
<line>for all good men </line>
<line> to come to the aid of their party.</line>
</message>
on standard output.
Notice the differences in indentation,
the missing attributes in the output from the first
yoixToXML
call (because there is no current element), and the missing empty
line
when
OMIT_NULL_ELEMENTS
is added to
flags.
| | |
| Return: |
String
| | |
| See Also: |
ParseTree,
xmlAdd,
xmlGet,
xmlToYoix
|
|
