<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN" "http://www.gnustep.org/gsdoc-1_0_4.dtd">
<gsdoc base="GWSElement">
  <head>
    <title>GWSElement class documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <version>25500</version>
    <date>2007-09-24 14:19:12 +0100 (Mon, 24 Sep 2007)</date>
    <copy>2008 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the GWSElement class
      </heading>
      <class name="GWSElement" super="NSObject">
        <declared>GWSElement.h</declared>
        <conform>NSMutableCopying</conform>
        <desc>
          This little class encapsulates an XML element as part of
          a simple tree of elements in a document. <br /> The
          <ref type="class" id="GWSCoder">GWSCoder</ref>
            class creates a tree of these elements when it parses
            a document. <br /> 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.
            <br /> 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).
        </desc>
        <method type="void">
          <sel>addChild:</sel>
          <arg type="GWSElement*">child</arg>
          <desc>
            Adds an element to the list of elements which are
            direct children of the receiver.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>addChildNamed:</sel>
          <arg type="NSString*">name</arg>
          <sel>namespace:</sel>
          <arg type="NSString*">namespace</arg>
          <sel>qualified:</sel>
          <arg type="NSString*">qualified</arg>
          <sel>content:</sel>
          <arg type="NSString*">content</arg>
          <vararg />
          <desc>
            Creates a new child element of the receiver with
            the specified <var>name</var>, <var>namespace</var>,
            <var>qualified</var> <var>name</var>, and text
            <var>content</var> (may be <code>nil</code>). <br />
            The <var>content</var> is followed by a
            <code>nil</code> terminated list of strings in pairs
            of attribute names and attribute values. <br />
            Alternatively, the <var>content</var> can be
            followed by a single dictionary of attributes, in
            which case the list of arguments does not need to be
            <code>nil</code> terminated. <br /> The newly
            created child element is returned.
          </desc>
        </method>
        <method type="void">
          <sel>addContent:</sel>
          <arg type="NSString*">content</arg>
          <desc>
            Adds a string to the <var>content</var> of the
            receiver. New <var>content</var> is appended to
            any existing <var>content</var> (with any white space
            between the two parts being condensed to a single
            space).
          </desc>
        </method>
        <method type="NSString*">
          <sel>attributeForName:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Returns the value of the named attribute, or
            <code>nil</code> if no such attribute has been
            specified in the receiver.
          </desc>
        </method>
        <method type="NSDictionary*">
          <sel>attributes</sel>
          <desc>
            Returns the attributes of the receiver, or an empty
            dictionary if no attributes are set.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>childAtIndex:</sel>
          <arg type="NSUInteger">index</arg>
          <desc>
            Returns the child of the receiver at the specified
            <var>index</var> in the list of children. Raises an
            exception if the <var>index</var> does not lie in
            the list.
          </desc>
        </method>
        <method type="NSArray*">
          <sel>children</sel>
          <desc>
            Returns an autoreleased array containing all the
            child elements of the receiver. Returns an empty
            array if there are no children.
          </desc>
        </method>
        <method type="NSString*">
          <sel>content</sel>
          <desc>
            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 <code>nil</code>).
            <br /> The returned value will have no leading or
            trailing white space.
          </desc>
        </method>
        <method type="NSUInteger">
          <sel>countChildren</sel>
          <desc>
            returns the number of direct child elements.
          </desc>
        </method>
        <method type="void">
          <sel>encodeContentWith:</sel>
          <arg type="GWSCoder*">coder</arg>
          <desc>
            Appends a string representation of the receiver's
            content and/or child elements to the coder's
            mutable string. <br /> If the receiver is an empty
            element, this does nothing. <br /> If
            <ref type="method" id="-setLiteralValue:">
              -setLiteralValue:
            </ref>
            has been called to set a string value for this element,
            then this method does nothing.
          </desc>
        </method>
        <method type="void">
          <sel>encodeEndWith:</sel>
          <arg type="GWSCoder*">coder</arg>
          <desc>
            Appends a string representation of the receiver's
            end tag to the coder's mutable string. <br /> If
            <ref type="method" id="-setLiteralValue:">
              -setLiteralValue:
            </ref>
            has been called to set a string value for this element,
            then this method does nothing.
          </desc>
        </method>
        <method type="BOOL">
          <sel>encodeStartWith:</sel>
          <arg type="GWSCoder*">coder</arg>
          <sel>collapse:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Appends a string representation of the receiver's
            start tag (including attributes) to the coder's
            mutable string. <br /> If the receiver is an empty
            element and the collapse <var>flag</var> is
            <code>YES</code>, this ends the start tag with '
            /&gt;' markup. <br /> If
            <ref type="method" id="-setLiteralValue:">
              -setLiteralValue:
            </ref>
            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. <br /> The return value of
            this method is <code>YES</code> 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 <code>NO</code> if the content
            and end tag of the element still need to be output.
          </desc>
        </method>
        <method type="void">
          <sel>encodeWith:</sel>
          <arg type="GWSCoder*">coder</arg>
          <desc>
            Appends a string representation of the receiver
            (and its child elements) to the coder's mutable
            string. <br /> This method can be used to generate
            an XML document from a tree of elements. Typically it is
            called by a
            <ref type="class" id="GWSCoder">GWSCoder</ref>
              to output a tree of elements that the <var>coder</var>
              has built up from the items it is encoding. <br /> If
              <ref type="method" id="-setLiteralValue:">
                -setLiteralValue:
              </ref>
              has been called to set a string value for this
              element, then this method appends that literal
              value to the document text in <var>coder</var>.
              Otherwise, this method encodes a
              representation of the receiver built from
              its name, namespace, attributes, content and
              children. <br /> This method calls the other
              encoding methods to perform its work.
          </desc>
        </method>
        <method type="NSArray*">
          <sel>fetchElements:</sel>
          <arg type="NSString*">path</arg>
          <desc>
            A convenience method to search the receiver for those
            elemements match the supplied <var>path</var>
            (ignoring namespace prefixes). <br /> The
            <var>path</var> 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. <br /> A
            name in the <var>path</var> may be specified as an
            asterisk ('*') in which case it matches any
            element at that level in the <var>path</var>.
            <br /> The order of the elements returned in the
            array is the same as the order in which they occur in
            the tree.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>findChild:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            A convenience method to search the receiver's children
            for an element whose <var>name</var> (ignoring any
            namespace prefix) matches the method argument.
            <br /> The return value is the first matching direct
            child, or <code>nil</code> if no such element is
            found.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>findElement:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            A convenience method to search the receiver for an
            element whose <var>name</var> (ignoring any
            namespace prefix) matches the method argument.
            <br /> The return value could be the receiver
            itsself, any of it's direct (or indirect)
            children, or <code>nil</code> if no such element
            is found. <br /> The search returns the first element
            found searching the parse tree in 'natural' order.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>firstChild</sel>
          <desc>
            Returns the first child element or <code>nil</code>
            if there are no children.
          </desc>
        </method>
        <method type="NSUInteger">
          <sel>index</sel>
          <desc>
            Returns the position of this element within the
            list of siblings which are direct children of its
            parent. <br /> Returns NSNotFound if the receiver
            has no parent.
          </desc>
        </method>
        <method type="id">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <sel>namespace:</sel>
          <arg type="NSString*">namespace</arg>
          <sel>qualified:</sel>
          <arg type="NSString*">qualified</arg>
          <sel>attributes:</sel>
          <arg type="NSDictionary*">attributes</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="void">
          <sel>insertChild:</sel>
          <arg type="GWSElement*">child</arg>
          <sel>atIndex:</sel>
          <arg type="NSUInteger">index</arg>
          <desc>
            Inserts an element to the list of elements which
            are direct children of the receiver. <br /> Raises an
            exception it the specified <var>index</var> is
            greater than the number of children present. <br />
            If the element is already a <var>child</var> of the
            receiver, this method moves it to the new
            location.
          </desc>
        </method>
        <method type="BOOL">
          <sel>isAncestorOf:</sel>
          <arg type="GWSElement*">other</arg>
          <desc>
            Returns <code>YES</code> if the receiver is a
            direct or indirect parent of <var>other</var>.
          </desc>
        </method>
        <method type="BOOL">
          <sel>isDescendantOf:</sel>
          <arg type="GWSElement*">other</arg>
          <desc>
            Returns <code>YES</code> if the receiver is a
            direct or indirect child of <var>other</var>.
          </desc>
        </method>
        <method type="BOOL">
          <sel>isNamed:</sel>
          <arg type="NSString*">aName</arg>
          <desc>
            Returns <code>YES</code> if the name of the
            receiver element is equal to <var>aName</var>
          </desc>
        </method>
        <method type="BOOL">
          <sel>isSiblingOf:</sel>
          <arg type="GWSElement*">other</arg>
          <desc>
            Returns <code>YES</code> if the receiver and
            <var>other</var> share the same direct parent.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>lastChild</sel>
          <desc>
            Returns the last child element or <code>nil</code>
            if there are no children.
          </desc>
        </method>
        <method type="id">
          <sel>mutableCopyWithZone:</sel>
          <arg type="NSZone*">aZone</arg>
          <desc>
            Perform a deep copy of the receiver.
          </desc>
        </method>
        <method type="NSString*">
          <sel>name</sel>
          <desc>
            Returns the name of the receiver (as set when it
            was initialised, or by using the
            <ref type="method" id="-setName:">
              -setName:
            </ref>
            method).
          </desc>
        </method>
        <method type="NSString*">
          <sel>namespace</sel>
          <desc>
            Returns the namespace URI of the receiver (as set
            when it was initialised or changed using setPrefix:).
          </desc>
        </method>
        <method type="NSString*">
          <sel>namespaceForPrefix:</sel>
          <arg type="NSString*">prefix</arg>
          <desc>
            Returns the namespace URL for the specified
            <var>prefix</var> by looking at the namespace
            declarations in the receiver and its parents.
            If the <var>prefix</var> is empty, this returns the
            default namespace URL. <br /> returns
            <code>nil</code> if no matching namespace is found.
          </desc>
        </method>
        <method type="NSDictionary*">
          <sel>namespaces</sel>
          <desc>
            Returns the namespaces mappings introduced by this
            element. <br /> If there are no namespaces
            introduced, this returns <code>nil</code>.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>nextElement:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Searches the tree for the next element with the
            specified <var>name</var> (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. <br />
            If the supplied <var>name</var> is <code>nil</code>, any
            element matches, so this method may be used to
            traverse the entire tree passing through all
            nodes.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>parent</sel>
          <desc>
            Returns the parent of this element, or
            <code>nil</code> if the receiver has no parent.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>path</sel>
          <desc>
            Convenience method to return the names of the
            elements containing the receiver (including the
            name of the receiver as the last item).
          </desc>
        </method>
        <method type="NSString*">
          <sel>prefix</sel>
          <desc>
            Returns the prefix identifying the namespace of the
            receiver. <br /> The
            <ref type="method" id="-qualified">
              -qualified
            </ref>
            name of the receiver consists of the
            <ref type="method" id="-prefix">
              -prefix
            </ref>
            and the <ref type="method" id="-name">-name</ref>
            separated by a single colon. <br /> * Returns
            <code>nil</code> if the receiver has no prefix.
          </desc>
        </method>
        <method type="NSString*">
          <sel>prefixForNamespace:</sel>
          <arg type="NSString*">uri</arg>
          <desc>
            Searches the receiver and its parents for the
            first usable prefix mapping to the specified
            namespace. Returns <code>nil</code> if there is
            none.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>previous</sel>
          <desc>
            Returns the previous sibling of the receiver (if
            any).
          </desc>
        </method>
        <method type="NSString*">
          <sel>qualified</sel>
          <desc>
            Returns the fully qualified name of the receiver
            (as set when it was initialised, or using the
            <ref type="method" id="-setName:">
              -setName:
            </ref>
            and
            <ref type="method" id="-setPrefix:">
              -setPrefix:
            </ref>
            methods).
          </desc>
        </method>
        <method type="void">
          <sel>remove</sel>
          <desc>
            Removes the receiver (and its children) from its
            parent. <br /> This may cause the receiver to be
            deallocated.
          </desc>
        </method>
        <method type="void">
          <sel>setAttribute:</sel>
          <arg type="NSString*">attribute</arg>
          <sel>forKey:</sel>
          <arg type="NSString*">key</arg>
          <desc>
            Sets the value for the specified <var>key</var>.
            <br /> If <var>attribute</var> is <code>nil</code>
            then any existing value for the <var>key</var> is
            removed. <br /> If the <var>key</var> is
            <code>nil</code>, then all existing attributes are
            removed.
          </desc>
        </method>
        <method type="void">
          <sel>setContent:</sel>
          <arg type="NSString*">content</arg>
          <desc>
            Sets the value of the <var>content</var> string of the
            receiver, replacing any <var>content</var>
            already present. Any leading white space is
            removed. <br /> You may use an empty string or
            <code>nil</code> to remove <var>content</var> from
            the receiver.
          </desc>
        </method>
        <method type="void">
          <sel>setLiteralValue:</sel>
          <arg type="NSString*">xml</arg>
          <desc>
            Sets the literal text to be used as the XML
            representing this element and its content and
            children when encoding to an XML document. <br />
            This overrides the default behavior which is to
            traverse the tree of elements producing output to
            the XML document. <br /> Use with <em>extreme</em> care
            ... this method allows you to inject illegal data into
            an XML document.
          </desc>
        </method>
        <method type="void">
          <sel>setName:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Sets the <var>name</var> of the receiver to the
            specified value.
          </desc>
        </method>
        <method type="void">
          <sel>setNamespace:</sel>
          <arg type="NSString*">uri</arg>
          <sel>forPrefix:</sel>
          <arg type="NSString*">prefix</arg>
          <desc>
            Sets the namespace URI for the specified
            <var>prefix</var>. <br /> If the <var>uri</var> is
            <code>nil</code>, this removes any existing mapping
            for the <var>prefix</var>. <br /> If the
            <var>prefix</var> is empty or <code>nil</code>, this
            sets the default namespace.
          </desc>
        </method>
        <method type="void">
          <sel>setPrefix:</sel>
          <arg type="NSString*">prefix</arg>
          <desc>
            Sets the namespace <var>prefix</var> of the receiver
            to the specified value, which must be empty or a
            namespace <var>prefix</var> declared in the
            receiver or one of the its parent elements. <br />
            Changing the <var>prefix</var> also changes the
            namespace of the receiver... setting an empty/nil
            <var>prefix</var> causes the receiver to use the
            default namespace.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>sibling</sel>
          <desc>
            Returns the next sibling of the receiver. In
            conjunction with the
            <ref type="method" id="-firstChild">
              -firstChild
            </ref>
            method, this can be used to step through all the
            children of an element.
          </desc>
        </method>
      </class>
    </chapter>
  </body>
</gsdoc>
