Returns an
Object
that represents all instances of
name
in
target,
which currently must be an
Array
or
Dictionary,
or
NULL
if no matches are found.
When
target
is an
Array
elements are assumed to be arranged in key/value pairs;
the element of the pair at the even index must be a
String
that is the key and the element at the odd index is the value.
Although not required,
target
is often created by applying
xmlToYoix
to an XML string.
name
identifies the elements in
target
that are collected and returned to the caller.
A slash character (i.e.,
/)
in
name
marks a transition to a new level in the
target
structure, but leading and trailing slashes are always ignored and multiple consecutive slashes
are treated as a single slash.
Each level represented in
name
must correspond to an
Array
or
compound object (e.g., a
Dictionary)
in the
target
structure.
For example, if
target
is defined as
Dictionary target = {
Dictionary key1 = {
Array key2 = {
"key3", "some text",
};
};
};
then
printf("key1=%.3O\n\n", xmlGet("key1", target));
printf("key1/key2=%.3O\n\n", xmlGet("key1/key2", target));
printf("key1/key2/key3=%O\n", xmlGet("key1/key2/key3", target));
prints
key1=Dictionary[1:0]
>key2=Array[2:0]
>^"key3"
^"some text"
key1/key2=Array[2:0]
>^"key3"
^"some text"
key1/key2/key3=some text
on standard output.
In case you are wondering, one of the reasons why slash is used as the separator character
is because dot is allowed in XML names.
The optional
extract
argument gives you some control over how the results are returned.
Internally
xmlGet
always collects the matching elements in an array, but if
extract
is non-zero, which it is by default, and that array contains a single element then the
value returned is that single element.
The problem with the default behavior is that when an array is returned your script can not
reliably tell the difference between the array used by
xmlGet
to collect the elements and an array that was in the
target
structure.
Calling
xmlGet
with
extract
set to zero disables the code that extracts single elements and means the array used to
collect elements is the value that is always returned.
| |
| Example: |
The program,
import yoix.*.*;
String xml = @<<
<message>
<line attr1="value 1" attr2="value 2">
<![CDATA[ Now is the]]> time
</line>
<line>
for all good men
</line>
<line>
to come to the aid of their party.
</line>
</message>
>>@;
Object target = xmlToYoix(xml, 1, TOSS_WS_CHARDATA);
String name = "message/line";
int extract = 1;
printf("name=%s, extract=%d\n", name, extract);
printf("%.5O\n", xmlGet(name, target, extract));
name = "message/line/$attributes";
printf("\nname=%s, extract=%d\n", name, extract);
printf("%.5O\n", xmlGet(name, target, extract));
extract = 0;
printf("\nname=%s, extract=%d\n", name, extract);
printf("%.5O\n", xmlGet(name, target, extract));
prints something like
name=message/line, extract=1
Array[3:0]
>Dictionary[2:0]
$attributes=Dictionary[2:0]
>attr1=^"value 1"
attr2=^"value 2"
>$text=^" Now is the time\n "
^"\n for all good men\n "
^"\n to come to the aid of their party.\n "
name=message/line/$attributes, extract=1
Dictionary[2:0]
>attr1=^"value 1"
attr2=^"value 2"
name=message/line/$attributes, extract=0
Array[1:0]
>Dictionary[2:0]
>attr1=^"value 1"
attr2=^"value 2"
on standard output.
Notice how three matches are returned in an array when
name
is
message/line
and how the result changes from a dictionary to an array when
extract
changes from
1
to
0
and
name
is
message/line/$attributes
| | |
| Return: |
Object
| | |
| See Also: |
ParseTree,
xmlAdd,
xmlToYoix,
yoixToXML
|
|
