Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Date: Generated at 2024-11-17 22:25:37 -0700
Copyright: (C) 2008 Free Software Foundation, Inc.
- Declared in:
- GWSElement.h
- Conforms to:
- NSMutableCopying
This little class encapsulates an XML element as part of
a simple tree of elements in a document.
The
GWSCoder
class creates a tree of these elements when it parses
a document.
This class aims to produce the most
lightweight practical implementation of a
tree-structured representation of the
subset of XML documents required for web services,
so that we have the ease of use advantages of working
with an entire document as a tree structure, while
minimising performance/efficiency overheads.
You probably don't need to use this class
directly yourself unless you are writing a new
GWSCoder subclass to handle some form of XML
serialisation of data (or if you want to
bugfix/enhance the existing GWSCoder
subclasses or GWSDocument decodiong/encooding of
WSDL).
Method summary
- (void)
addChild: (
GWSElement*)child;
Adds an element to the list of elements which are
direct children of the receiver.
- (
GWSElement*)
addChildNamed: (NSString*)name
namespace: (NSString*)namespace
qualified: (NSString*)qualified
content: (NSString*)content
,...;
Creates a new child element of the receiver with
the specified name, namespace,
qualified name, and text
content (may be nil
).
The content is followed by a
nil
terminated list of strings in pairs
of attribute names and attribute values.
Alternatively, the content can be
followed by a single dictionary of attributes, in
which case the list of arguments does not need to be
nil
terminated.
The newly
created child element is returned.
- (void)
addContent: (NSString*)content;
Adds a string to the content of the
receiver. New content is appended to
any existing content.
- (NSString*)
attributeForName: (NSString*)name;
Returns the value of the named attribute, or
nil
if no such attribute has been
specified in the receiver.
- (NSDictionary*)
attributes;
Returns an autoreleased immutable copy of the
attributes of the receiver, or an empty
dictionary if no attributes are set.
- (
GWSElement*)
childAtIndex: (
NSUInteger)index;
Returns the child of the receiver at the specified
index in the list of children. Raises an
exception if the index does not lie in
the list.
- (NSArray*)
children;
Returns an autoreleased array containing all the
child elements of the receiver. Returns an empty
array if there are no children.
- (void)
condense: (BOOL)internal;
Condenses the character content of the receiver
by stripping leading and trailing white space. If the
internal flag is YES
, any
sequence of internal white space is
also condensed to a single character by deleting all
but the first character.
- (NSString*)
content;
Returns the content text of the receiver. This may
be an empty string if no content has been added to the
receiver (but will never be nil
).
- (
NSUInteger)
countChildren;
returns the number of direct child elements.
- (void)
encodeContentWith: (
GWSCoder*)coder;
Appends a string representation of the receiver's
content and/or child elements to the coder's
mutable string.
If the receiver is an empty
element, this does nothing.
If
-setLiteralValue:
has been called to set a string value for this element,
then this method does nothing.
- (void)
encodeEndWith: (
GWSCoder*)coder;
Appends a string representation of the receiver's
end tag to the coder's mutable string.
If
-setLiteralValue:
has been called to set a string value for this element,
then this method does nothing.
- (BOOL)
encodeStartWith: (
GWSCoder*)coder
collapse: (BOOL)flag;
Appends a string representation of the receiver's
start tag (including attributes) to the coder's
mutable string.
If the receiver is an empty
element and the collapse
flag is
YES
, this ends the start tag with '
/>' markup.
If
-setLiteralValue:
has been called to set a string value for this element,
then this method appends the entire literal value to
the coder's mutable string.
The return value of
this method is
YES
if either the element
has been collapsed into the start tage or a literal
string has been output to represent the whole
element. It returns
NO
if the content
and end tag of the element still need to be output.
- (void)
encodeWith: (
GWSCoder*)coder;
Appends a string representation of the receiver
(and its child elements) to the coder's mutable
string.
This method can be used to generate
an XML document from a tree of elements. Typically it is
called by a
GWSCoder
to output a tree of elements that the
coder
has built up from the items it is encoding.
If
-setLiteralValue:
has been called to set a string value for this
element, then this method appends that literal
value to the document text in
coder.
Otherwise, this method encodes a
representation of the receiver built from
its name, namespace, attributes, content and
children.
This method calls the other
encoding methods to perform its work.
- (NSArray*)
fetchElements: (NSString*)path;
A convenience method to search the receiver for those
elemements match the supplied path
(ignoring namespace prefixes).
The
path contains slash ('/') separated names,
and if it begins with a slash the search starts at the
top of the tree rather than at the receiver.
A
name in the path may be specified as an
asterisk ('*') in which case it matches any
element at that level in the path.
The order of the elements returned in the
array is the same as the order in which they occur in
the tree.
- (
GWSElement*)
findChild: (NSString*)name;
A convenience method to search the receiver's children
for an element whose name (ignoring any
namespace prefix) matches the method argument.
The return value is the first matching direct
child, or nil
if no such element is
found.
- (
GWSElement*)
findElement: (NSString*)name;
A convenience method to search the receiver for an
element whose name (ignoring any
namespace prefix) matches the method argument.
The return value could be the receiver
itsself, any of it's direct (or indirect)
children, or nil
if no such element
is found.
The search returns the first element
found searching the parse tree in 'natural' order.
- (
GWSElement*)
firstChild;
Returns the first child element or nil
if there are no children.
- (
NSUInteger)
index;
Returns the position of this element within the
list of siblings which are direct children of its
parent.
Returns NSNotFound if the receiver
has no parent.
- (id)
initWithName: (NSString*)name
namespace: (NSString*)namespace
qualified: (NSString*)qualified
attributes: (NSDictionary*)attributes;
Description forthcoming.
- (void)
insertChild: (
GWSElement*)child
atIndex: (
NSUInteger)index;
Inserts an element to the list of elements which
are direct children of the receiver.
Raises an
exception it the specified index is
greater than the number of children present.
If the element is already a child of the
receiver, this method moves it to the new
location.
- (BOOL)
isAncestorOf: (
GWSElement*)other;
Returns YES
if the receiver is a
direct or indirect parent of other.
- (BOOL)
isDescendantOf: (
GWSElement*)other;
Returns YES
if the receiver is a
direct or indirect child of other.
- (BOOL)
isNamed: (NSString*)aName;
Returns YES
if the name of the
receiver element is equal to aName
- (BOOL)
isSiblingOf: (
GWSElement*)other;
Returns YES
if the receiver and
other share the same direct parent.
- (
GWSElement*)
lastChild;
Returns the last child element or nil
if there are no children.
- (id)
mutableCopyWithZone: (NSZone*)aZone;
Perform a deep copy of the receiver.
- (NSString*)
name;
Returns the name of the receiver (as set when it
was initialised, or by using the
-setName:
method).
- (NSString*)
namespace;
Returns the namespace URI of the receiver (as set
when it was initialised or changed using setPrefix:).
- (NSString*)
namespaceForPrefix: (NSString*)prefix;
Returns the namespace URL for the specified
prefix by looking at the namespace
declarations in the receiver and its parents.
If the prefix is empty, this returns the
default namespace URL.
returns
nil
if no matching namespace is found.
- (NSDictionary*)
namespaces;
Returns the namespaces mappings introduced by this
element.
If there are no namespaces
introduced, this returns nil
.
- (
GWSElement*)
nextElement: (NSString*)name;
Searches the tree for the next element with the
specified name (ignoring any namespace
prefix). Children of the receiver are searched
first, then siblings of the receiver's parent, then
siblings of the parent's parent and so on.
If the supplied name is nil
, any
element matches, so this method may be used to
traverse the entire tree passing through all
nodes.
- (
GWSElement*)
parent;
Returns the parent of this element, or
nil
if the receiver has no parent.
- (NSMutableArray*)
path;
Convenience method to return the names of the
elements containing the receiver (including the
name of the receiver as the last item).
- (NSString*)
prefix;
Returns the prefix identifying the namespace of the
receiver.
The
-qualified
name of the receiver consists of the
-prefix
and the
-name
separated by a single colon.
* Returns
nil
if the receiver has no prefix.
- (NSString*)
prefixForNamespace: (NSString*)uri;
Searches the receiver and its parents for the
first usable prefix mapping to the specified
namespace. Returns nil
if there is
none.
- (
GWSElement*)
previous;
Returns the previous sibling of the receiver (if
any).
- (NSString*)
qualified;
Returns the fully qualified name of the receiver
(as set when it was initialised, or using the
-setName:
and
-setPrefix:
methods).
- (void)
remove;
Removes the receiver (and its children) from its
parent.
This may cause the receiver to be
deallocated.
- (void)
setAttribute: (NSString*)attribute
forKey: (NSString*)key;
Sets the value for the specified key.
If attribute is nil
then any existing value for the key is
removed.
If the key is
nil
, then all existing attributes are
removed.
- (void)
setContent: (NSString*)content;
Sets the value of the content string of the
receiver, replacing any content
already present.
You may use an empty string
or nil
to remove content from
the receiver.
- (void)
setLiteralValue: (NSString*)xml;
Sets the literal text to be used as the XML
representing this element and its content and
children when encoding to an XML document.
This overrides the default behavior which is to
traverse the tree of elements producing output to
the XML document.
Use with extreme care
... this method allows you to inject illegal data into
an XML document.
- (void)
setName: (NSString*)name;
Sets the name of the receiver to the
specified value.
- (void)
setNamespace: (NSString*)uri
forPrefix: (NSString*)prefix;
Sets the namespace URI for the specified
prefix.
If the uri is
nil
, this removes any existing mapping
for the prefix.
If the
prefix is empty or nil
, this
sets the default namespace.
- (void)
setPrefix: (NSString*)prefix;
Sets the namespace prefix of the receiver
to the specified value, which must be empty or a
namespace prefix declared in the
receiver or one of the its parent elements.
Changing the prefix also changes the
namespace of the receiver... setting an empty/nil
prefix causes the receiver to use the
default namespace.
- (
GWSElement*)
sibling;
Returns the next sibling of the receiver. In
conjunction with the
-firstChild
method, this can be used to step through all the
children of an element.