# GWSElement class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 25500

Date: 2007-09-24 14:19:12 +0100 (Mon, 24 Sep 2007)

Copyright: (C) 2008 Free Software Foundation, Inc.

# Software documentation for the GWSElement class

## GWSElement : NSObject

> 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

- -addChild:
- -addChildNamed:namespace:qualified:content:,...
- -addContent:
- -attributeForName:
- -attributes
- -childAtIndex:
- -children
- -content
- -countChildren
- -encodeContentWith:
- -encodeEndWith:
- -encodeStartWith:collapse:
- -encodeWith:
- -fetchElements:
- -findChild:
- -findElement:
- -firstChild
- -index
- -initWithName:namespace:qualified:attributes:
- -insertChild:atIndex:
- -isAncestorOf:
- -isDescendantOf:
- -isNamed:
- -isSiblingOf:
- -lastChild
- -mutableCopyWithZone:
- -name
- -namespace
- -namespaceForPrefix:
- -namespaces
- -nextElement:
- -parent
- -path
- -prefix
- -prefixForNamespace:
- -previous
- -qualified
- -remove
- -setAttribute:forKey:
- -setContent:
- -setLiteralValue:
- -setName:
- -setNamespace:forPrefix:
- -setPrefix:
- -sibling

### addChild:

- (void) addChild: (GWSElement*)child;
Adds an element to the list of elements which are direct children of the receiver.

### addChildNamed: namespace: qualified: content: ,...

- (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.

### addContent:

- (void) addContent: (NSString*)content;
Adds a string to the content of the receiver. New content is appended to any existing content (with any white space between the two parts being condensed to a single space).

### attributeForName:

- (NSString*) attributeForName: (NSString*)name;
Returns the value of the named attribute, or `nil` if no such attribute has been specified in the receiver.

### attributes

- (NSDictionary*) attributes;
Returns the attributes of the receiver, or an empty dictionary if no attributes are set.

### childAtIndex:

- (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.

### children

- (NSArray*) children;
Returns an autoreleased array containing all the child elements of the receiver. Returns an empty array if there are no children.

### content

- (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`).
The returned value will have no leading or trailing white space.

### countChildren

- (NSUInteger) countChildren;
returns the number of direct child elements.

### encodeContentWith:

- (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.

### encodeEndWith:

- (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.

### encodeStartWith: collapse:

- (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.

### encodeWith:

- (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.

### fetchElements:

- (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.

### findChild:

- (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.

### findElement:

- (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.

### firstChild

- (GWSElement*) firstChild;
Returns the first child element or `nil` if there are no children.

### index

- (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.

### initWithName: namespace: qualified: attributes:

- (id) initWithName: (NSString*)name namespace: (NSString*)namespace qualified: (NSString*)qualified attributes: (NSDictionary*)attributes;
Description forthcoming.

### insertChild: atIndex:

- (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.

### isAncestorOf:

- (BOOL) isAncestorOf: (GWSElement*)other;
Returns `YES` if the receiver is a direct or indirect parent of other.

### isDescendantOf:

- (BOOL) isDescendantOf: (GWSElement*)other;
Returns `YES` if the receiver is a direct or indirect child of other.

### isNamed:

- (BOOL) isNamed: (NSString*)aName;
Returns `YES` if the name of the receiver element is equal to aName

### isSiblingOf:

- (BOOL) isSiblingOf: (GWSElement*)other;
Returns `YES` if the receiver and other share the same direct parent.

### lastChild

- (GWSElement*) lastChild;
Returns the last child element or `nil` if there are no children.

### mutableCopyWithZone:

- (id) mutableCopyWithZone: (NSZone*)aZone;
Perform a deep copy of the receiver.

### name

- (NSString*) name;
Returns the name of the receiver (as set when it was initialised, or by using the -setName: method).

### namespace

- (NSString*) namespace;
Returns the namespace URI of the receiver (as set when it was initialised or changed using setPrefix:).

### namespaceForPrefix:

- (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.

### namespaces

- (NSDictionary*) namespaces;
Returns the namespaces mappings introduced by this element.
If there are no namespaces introduced, this returns `nil`.

### nextElement:

- (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.

### parent

- (GWSElement*) parent;
Returns the parent of this element, or `nil` if the receiver has no parent.

### path

- (NSMutableArray*) path;
Convenience method to return the names of the elements containing the receiver (including the name of the receiver as the last item).

### prefix

- (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.

### prefixForNamespace:

- (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.

### previous

- (GWSElement*) previous;
Returns the previous sibling of the receiver (if any).

### qualified

- (NSString*) qualified;
Returns the fully qualified name of the receiver (as set when it was initialised, or using the -setName: and -setPrefix: methods).

### remove

- (void) remove;
Removes the receiver (and its children) from its parent.
This may cause the receiver to be deallocated.

### setAttribute: forKey:

- (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.

### setContent:

- (void) setContent: (NSString*)content;
Sets the value of the content string of the receiver, replacing any content already present. Any leading white space is removed.
You may use an empty string or `nil` to remove content from the receiver.

### setLiteralValue:

- (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.

### setName:

- (void) setName: (NSString*)name;
Sets the name of the receiver to the specified value.

### setNamespace: forPrefix:

- (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.

### setPrefix:

- (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.

### sibling

- (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.