Up

The XML and HTML parsing system

Authors

Michael Pakhantsov (mishel@berest.dp.ua)
Richard Frith-Macdonald (rfm@gnu.org)

Copyright: (C) 2000-2005 Free Software Foundation, Inc.


Contents -

  1. The XML and HTML parsing system
  2. Software documentation for the GSHTMLParser class
  3. Software documentation for the GSHTMLSAXHandler class
  4. Software documentation for the GSSAXHandler class
  5. Software documentation for the GSTreeSAXHandler class
  6. Software documentation for the GSXMLAttribute class
  7. Software documentation for the GSXMLDocument class
  8. Software documentation for the GSXMLNamespace class
  9. Software documentation for the GSXMLNode class
  10. Software documentation for the GSXMLParser class
  11. Software documentation for the GSXMLRPC class
  12. Software documentation for the GSXPathBoolean class
  13. Software documentation for the GSXPathContext class
  14. Software documentation for the GSXPathNodeSet class
  15. Software documentation for the GSXPathNumber class
  16. Software documentation for the GSXPathObject class
  17. Software documentation for the GSXPathString class
  18. Software documentation for the GSXMLDocument(XSLT) category
  19. Software documentation for the GSXMLRPC(Delegate) category
  20. Software documentation for the NSString(GSXML) category

The XML and HTML parsing system

The GNUstep XML parser is a collection Objective-C classes wrapping the C XML parsing library (libxml).

The underlying C library handles high performance parsing, while the ObjectiveC classes provide ease of use/integration.

Software documentation for the GSHTMLParser class

GSHTMLParser : GSXMLParser

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

The GSHTMLParser class is a simple subclass of GSXMLParser which should parse reasonably well formed HTML documents. If you wish to parse XHTML documents, you should use GSXMLParser... the GSHTMLParser class is for older 'legacy' documents.

Software documentation for the GSHTMLSAXHandler class

GSHTMLSAXHandler : GSSAXHandler

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

You may create a subclass of this class to handle incremental parsing of html documents... this is provided for handling legacy documents, as modern html documents should use xhtml, and for those you should simply subclass GSSAXHandler

Software documentation for the GSSAXHandler class

GSSAXHandler : NSObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

XML SAX Handler.

GSSAXHandler is a callback-based interface to the GSXMLParser which operates in a similar (though not identical) manner to SAX.

Each GSSAXHandler object is associated with a GSXMLParser object. As parsing progresses, the methods of the GSSAXHandler are invoked by the parser, so the handler is able to deal with the elements and entities being parsed.

The callback methods in the GSSAXHandler class do nothing - it is intended that you subclass GSSAXHandler and override them.

If you create a GSXMLParser passing nil as the GSSAXHandler, the parser will parse data to create a GSXMLDocument instance which you can then examine as a whole ... this is generally the preferred mechanism for parsing as it permits the parser to validate the parsed document againts a DTD, and your software can then examine the document secure in the knowledge that it contains the expected structure. Use of a GSSAXHandler is preferred for very large documents with simple structure... in which case incremental parsing is more efficient.


Instance Variables

Method summary

handler 

+ (GSSAXHandler*) handler;
Availability: Not in OpenStep/MacOS-X

Create a new SAX handler.

attribute: value: 

- (void) attribute: (NSString*)name value: (NSString*)value;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Handle an attribute that has been read by the parser.

attributeDecl: name: type: typeDefValue: defaultValue: 

- (void) attributeDecl: (NSString*)nameElement name: (NSString*)name type: (NSInteger)type typeDefValue: (NSInteger)defType defaultValue: (NSString*)value;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

An attribute definition has been parsed.

cdataBlock: 

- (void) cdataBlock: (NSData*)value;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when a cdata block has been parsed.

characters: 

- (void) characters: (NSString*)name;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Receiving some chars from the parser.

comment: 

- (void) comment: (NSString*)value;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

A comment has been parsed.

elementDecl: type: 

- (void) elementDecl: (NSString*)name type: (NSInteger)type;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

An element definition has been parsed.

endDocument 

- (void) endDocument;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when the document end has been detected.

endElement: 

- (void) endElement: (NSString*)elementName;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when a closing tag has been processed.

endElement: prefix: href: 

- (void) endElement: (NSString*)elementName prefix: (NSString*)prefix href: (NSString*)href;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when a closing tag has been processed.

entityDecl: type: public: system: content: 

- (void) entityDecl: (NSString*)name type: (NSInteger)type public: (NSString*)publicId system: (NSString*)systemId content: (NSString*)content;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

An entity definition has been parsed.

error: 

- (void) error: (NSString*)e;
Availability: Not in OpenStep/MacOS-X

Called when an error message needs to be output.

error: colNumber: lineNumber: 

- (void) error: (NSString*)e colNumber: (NSInteger)colNumber lineNumber: (NSInteger)lineNumber;
Availability: Not in OpenStep/MacOS-X

Called when an error message needs to be output.

externalSubset: externalID: systemID: 

- (BOOL) externalSubset: (NSString*)name externalID: (NSString*)externalID systemID: (NSString*)systemID;
Availability: Not in OpenStep/MacOS-X

Called to find out whether there is an external subset.

fatalError: 

- (void) fatalError: (NSString*)e;
Availability: Not in OpenStep/MacOS-X

Called when a fatal error message needs to be output.

fatalError: colNumber: lineNumber: 

- (void) fatalError: (NSString*)e colNumber: (NSInteger)colNumber lineNumber: (NSInteger)lineNumber;
Availability: Not in OpenStep/MacOS-X

Called when a fatal error message needs to be output.

getEntity: 

- (void*) getEntity: (NSString*)name;
Availability: Not in OpenStep/MacOS-X

get an entity by name

getParameterEntity: 

- (void*) getParameterEntity: (NSString*)name;
Availability: Not in OpenStep/MacOS-X

get a parameter entity by name

globalNamespace: href: prefix: 

- (void) globalNamespace: (NSString*)name href: (NSString*)href prefix: (NSString*)prefix;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

An old global namespace has been parsed.

hasExternalSubset 

- (NSInteger) hasExternalSubset;
Availability: Not in OpenStep/MacOS-X

Called to find out whether there is an external subset.

hasInternalSubset 

- (NSInteger) hasInternalSubset;
Availability: Not in OpenStep/MacOS-X

Called to find out whether there is an internal subset.

ignoreWhitespace: 

- (void) ignoreWhitespace: (NSString*)ch;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Receiving some ignorable whitespaces from the parser.

internalSubset: externalID: systemID: 

- (BOOL) internalSubset: (NSString*)name externalID: (NSString*)externalID systemID: (NSString*)systemID;
Availability: Not in OpenStep/MacOS-X

Called to find out whether there is an internal subset.

isStandalone 

- (NSInteger) isStandalone;
Availability: Not in OpenStep/MacOS-X

Called to detemrine if the document is standalone.

lib 

- (void*) lib;
Availability: Not in OpenStep/MacOS-X

Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!

loadEntity: at: 

- (NSString*) loadEntity: (NSString*)publicId at: (NSString*)location;
Availability: Not in OpenStep/MacOS-X

Called to return the filename from which an entity should be loaded.

namespaceDecl: href: prefix: 

- (void) namespaceDecl: (NSString*)name href: (NSString*)href prefix: (NSString*)prefix;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

An old global namespace has been parsed.

notationDecl: public: system: 

- (void) notationDecl: (NSString*)name public: (NSString*)publicId system: (NSString*)systemId;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

What to do when a notation declaration has been parsed.

parser 

- (GSXMLParser*) parser;
Availability: Not in OpenStep/MacOS-X

Return the parser object with which this handler is associated. This may occasionally be useful.

processInstruction: data: 

- (void) processInstruction: (NSString*)targetName data: (NSString*)PIdata;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

A processing instruction has been parsed.

reference: 

- (void) reference: (NSString*)name;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when an entity reference is detected.

startDocument 

- (void) startDocument;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when the document starts being processed.

startElement: attributes: 

- (void) startElement: (NSString*)elementName attributes: (NSMutableDictionary*)elementAttributes;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

Called when an opening tag has been processed.

startElement: prefix: href: attributes: namespaces: 

- (void) startElement: (NSString*)elementName prefix: (NSString*)prefix href: (NSString*)href attributes: (NSMutableDictionary*)elementAttributes namespaces: (NSMutableDictionary*)elementNamespaces;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Description forthcoming.

unparsedEntityDecl: public: system: notationName: 

- (void) unparsedEntityDecl: (NSString*)name public: (NSString*)publicId system: (NSString*)systemId notationName: (NSString*)notation;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.

What to do when an unparsed entity declaration is parsed.

warning: 

- (void) warning: (NSString*)e;
Availability: Not in OpenStep/MacOS-X

Called when a warning message needs to be output.

warning: colNumber: lineNumber: 

- (void) warning: (NSString*)e colNumber: (NSInteger)colNumber lineNumber: (NSInteger)lineNumber;
Availability: Not in OpenStep/MacOS-X

Called when a warning message needs to be output.



Instance Variables for GSSAXHandler Class

isHtmlHandler

@protected BOOL isHtmlHandler;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

lib

@protected void* lib;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

parser

@protected GSXMLParser* parser;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.




Software documentation for the GSTreeSAXHandler class

GSTreeSAXHandler : GSSAXHandler

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

The default handler for parsing documents... this will build a GSXMLDocument for you. This handler may not currently be subclassed, though that capability may be added at a later date.

Software documentation for the GSXMLAttribute class

GSXMLAttribute : GSXMLNode

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

A class wrapping attributes of an XML element node. Generally when examining a GSXMLDocument, you need not concern yourself with GSXMLAttribute objects as you will probably use the [GSXMLNode -objectForKey:] method to return the string value of any attribute you are interested in.
Method summary

value 

- (NSString*) value;
Availability: Not in OpenStep/MacOS-X

Returns the string value of the attribute.

Software documentation for the GSXMLDocument class

GSXMLDocument : NSObject

Declared in:
GNUstepBase/GSXML.h
Conforms to:
NSCopying
Availability: Not in OpenStep/MacOS-X

A GSXML document wraps the document structure of the underlying libxml library.

Instance Variables

Method summary

documentWithVersion: 

+ (GSXMLDocument*) documentWithVersion: (NSString*)version;
Availability: Not in OpenStep/MacOS-X

Create a new document with the specified version.
 id d = [GSXMLDocument documentWithVersion: @"1.0"];

 [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]];
 [[d root] setObject: @"0.9" forKey: @"version"];
 n1 = [[d root] makeChildWithNamespace: nil name: @"dict" content: nil];
 [n1 makeComment: @" this is a comment "];
 [n1 makePI: @"pi1" content: @"this is a process instruction"];
 [n1 makeChildWithNamespace: nil name: @"key" content: @"Year Of Birth"];
 [n1 makeChildWithNamespace: nil name: @"integer" content: @"65"];
 [n1 makeChildWithNamespace: nil name: @"key" content: @"Pets Names"];
 

description 

- (NSString*) description;
Availability: Not in OpenStep/MacOS-X

Returns a string representation of the document (ie the XML) or nil if the document does not have reasonable contents.

encoding 

- (NSString*) encoding;
Availability: Not in OpenStep/MacOS-X

Returns the name of the encoding for this document.

lib 

- (void*) lib;
Availability: Not in OpenStep/MacOS-X

Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!

makeNodeWithNamespace: name: content: 

- (GSXMLNode*) makeNodeWithNamespace: (GSXMLNamespace*)ns name: (NSString*)name content: (NSString*)content;
Availability: Not in OpenStep/MacOS-X

Creates a new node within the document.
 GSXMLNode *n1, *n2;
 GSXMLDocument *d;

 d = [GSXMLDocument documentWithVersion: @"1.0"];
 [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]];
 [[d root] setObject: @"0.9" forKey: @"version"];
 n1 = [[d root] makeChildWithNamespace: nil name: @"dict" content: nil];
 

root 

- (GSXMLNode*) root;
Availability: Not in OpenStep/MacOS-X

Returns the root node of the document.

setRoot: 

- (GSXMLNode*) setRoot: (GSXMLNode*)node;
Availability: Not in OpenStep/MacOS-X

Sets the root of the document.
NB. The node must have been created as part of the receiving document (eg. using the -makeNodeWithNamespace:name:content: method).

version 

- (NSString*) version;
Availability: Not in OpenStep/MacOS-X

Returns the version string for this document.

writeToFile: atomically: 

- (BOOL) writeToFile: (NSString*)filename atomically: (BOOL)useAuxilliaryFile;
Availability: Not in OpenStep/MacOS-X

Uses the -description method to produce a string representation of the document and writes that to filename.

writeToURL: atomically: 

- (BOOL) writeToURL: (NSURL*)url atomically: (BOOL)useAuxilliaryFile;
Availability: Not in OpenStep/MacOS-X

Uses the -description method to produce a string representation of the document and writes that to url.



Instance Variables for GSXMLDocument Class

_ownsLib

@protected BOOL _ownsLib;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_parent

@protected id _parent;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

lib

@protected void* lib;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.




Software documentation for the GSXMLNamespace class

GSXMLNamespace : NSObject

Declared in:
GNUstepBase/GSXML.h
Conforms to:
NSCopying
Availability: Not in OpenStep/MacOS-X

A GSXMLNamespace object wraps part of the document structure of the underlying libxml library.

Instance Variables

Method summary

descriptionFromType: 

+ (NSString*) descriptionFromType: (NSInteger)type;
Availability: Not in OpenStep/MacOS-X

Return the string representation of the specified numeric type.

typeFromDescription: 

+ (NSInteger) typeFromDescription: (NSString*)desc;
Availability: Not in OpenStep/MacOS-X

Return the numeric constant value for the namespace type named. This method is inefficient, so the returned value should be saved for re-use later. The possible values are -
  • XML_LOCAL_NAMESPACE

href 

- (NSString*) href;
Availability: Not in OpenStep/MacOS-X

Returns the namespace reference

lib 

- (void*) lib;
Availability: Not in OpenStep/MacOS-X

Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!

next 

- (GSXMLNamespace*) next;
Availability: Not in OpenStep/MacOS-X

return the next namespace.

prefix 

- (NSString*) prefix;
Availability: Not in OpenStep/MacOS-X

Return the namespace prefix.

type 

- (NSInteger) type;
Availability: Not in OpenStep/MacOS-X

Return type of namespace

typeDescription 

- (NSString*) typeDescription;
Availability: Not in OpenStep/MacOS-X

Return string representation of the type of the namespace.



Instance Variables for GSXMLNamespace Class

_parent

@protected id _parent;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

lib

@protected void* lib;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.




Software documentation for the GSXMLNode class

GSXMLNode : NSObject

Declared in:
GNUstepBase/GSXML.h
Conforms to:
NSCopying
Availability: Not in OpenStep/MacOS-X

A GSXMLNode object wraps part of the document structure of the underlying libxml library. It may have a parent, siblings, and children.

Instance Variables

Method summary

descriptionFromType: 

+ (NSString*) descriptionFromType: (NSInteger)type;
Availability: Not in OpenStep/MacOS-X

Return the string constant value for the node type given.

typeFromDescription: 

+ (NSInteger) typeFromDescription: (NSString*)desc;
Availability: Not in OpenStep/MacOS-X

Converts a node type string to a numeric constant which can be compared with the result of the -type method to determine what sort of node an instance is. Because this method is quite inefficient, you should cache the numeric type returned and re-use the cached value.

The node type names are -

  • XML_ELEMENT_NODE
  • XML_ATTRIBUTE_NODE
  • XML_TEXT_NODE
  • XML_CDATA_SECTION_NODE
  • XML_ENTITY_REF_NODE
  • XML_ENTITY_NODE
  • XML_PI_NODE
  • XML_COMMENT_NODE
  • XML_DOCUMENT_NODE
  • XML_DOCUMENT_TYPE_NODE
  • XML_DOCUMENT_FRAG_NODE
  • XML_NOTATION_NODE
  • XML_HTML_DOCUMENT_NODE
  • XML_DTD_NODE
  • XML_ELEMENT_DECL
  • XML_ATTRIBUTE_DECL
  • XML_ENTITY_DECL

attributes 

- (NSDictionary*) attributes;
Availability: Not in OpenStep/MacOS-X

Return attributes and values as a dictionary


content 

- (NSString*) content;
Availability: Not in OpenStep/MacOS-X

Return node content as a string. This should return meaningful information for text nodes and for entity nodes containing only text nodes.
If entity substitution was not enabled during parsing, an element containing text may actually contain both text nodes and entity reference nodes, in this case you should not use this method to get the content of the element, but should examine the child nodes of the element individually and perform any entity reference you need to do explicitly.
NB. There are five standard entities which are automatically substituted into the content text rather than appearing as entity nodes in their own right. These are '<', '>', ''', '"' and '&'. If you with to receive content in which these characters are represented by the original entity escapes, you need to use the -escapedContent method.

description 

- (NSString*) description;
Availability: Not in OpenStep/MacOS-X

Returns a string representation of the node and all its children (ie the XML text) or nil if the node does not have reasonable contents.

document 

- (GSXMLDocument*) document;
Availability: Not in OpenStep/MacOS-X

Return the document in which this node exists.

escapedContent 

- (NSString*) escapedContent;
Availability: Not in OpenStep/MacOS-X

This performs the same function as the -content method, but retains escaped character information (the standard five entities &lt;, &gt;, &apos;, &quot;, and &amp;) which are normally replaced with their standard equivalents (<, >, ', ", and &).

firstAttribute 

- (GSXMLAttribute*) firstAttribute;
Availability: Not in OpenStep/MacOS-X

Return the first attribute in this node.

firstChild 

- (GSXMLNode*) firstChild;
Availability: Not in OpenStep/MacOS-X

Return the first child node of this node.
    - (GSXMLNode*) elementRecursive: (GSXMLNode*)node
    {
      while (node != nil)
        {
          if ([node type] == XML_ELEMENT_NODE)
            {
              return node;
            }
          if ([node firstChild] != nil)
            {
              node = [self elementRecursive: [node firstChild]];
            }
          else
            {
              node = [node next];
            }
        }
      return node;
    }
  

firstChildElement 

- (GSXMLNode*) firstChildElement;
Availability: Not in OpenStep/MacOS-X

Return the first child element of this node. If you wish to step through all children of the node (including non-element nodes) you should use the -firstChild method instead.

isElement 

- (BOOL) isElement;
Availability: Not in OpenStep/MacOS-X

Convenience method, equivalent to calling -type and comparing it with the result of passing "XML_ELEMENT_NODE" to +typeFromDescription: (but faster).

isText 

- (BOOL) isText;
Availability: Not in OpenStep/MacOS-X

Convenience method, equivalent to calling -type and comparing it with the result of passing "XML_TEXT_NODE" to +typeFromDescription: (but faster).

lib 

- (void*) lib;
Availability: Not in OpenStep/MacOS-X

Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!

makeAttributeWithName: value: 

- (GSXMLAttribute*) makeAttributeWithName: (NSString*)name value: (NSString*)value;
Availability: Not in OpenStep/MacOS-X

Create and return an attribute (unless the named attribute already exists, in which case we update them value of the existing attribute and return it.

makeChildWithNamespace: name: content: 

- (GSXMLNode*) makeChildWithNamespace: (GSXMLNamespace*)ns name: (NSString*)name content: (NSString*)content;
Availability: Not in OpenStep/MacOS-X

Creation of a new child element, added at the end of parent children list. ns and content parameters are optional (may be nil). If content is non nil, a child list containing the TEXTs and ENTITY_REFs node will be created. Return previous node.


 GSXMLNode *n1, *n2;
 GSXMLDocument *d, *d1;

 d = [GSXMLDocument documentWithVersion: @"1.0"];
 [d setRoot: [d makeNodeWithNamespace: nil
                                 name: @"plist"
                              content: nil]];
 [[d root] setObject: @"0.9" forKey: @"version"];
 n1 = [[d root] makeChildWithNamespace: nil
                                  name: @"dict"
                               content: nil];
 [n1 makeChildWithNamespace: nil name: @"key" content: @"Year Of Birth"];
 [n1 makeChildWithNamespace: nil name: @"integer" content: @"65"];

 [n1 makeChildWithNamespace: nil name: @"key" content: @"Pets Names"];
 [n1 makeChildWithNamespace: nil name: @"array" content: nil];

 

makeComment: 

- (GSXMLNode*) makeComment: (NSString*)content;
Availability: Not in OpenStep/MacOS-X

Creation of a new comment element, added at the end of parent children list.
 d = [GSXMLDocument documentWithVersion: @"1.0"];

 [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]];
 [[d root] setObject: @"0.9" forKey: @"version"];
 n1 = [[d root] makeChildWithNamespace: nil name: @"dict" content: nil];
 [n1 makeComment: @" this is a comment "];
 

makeNamespaceHref: prefix: 

- (GSXMLNamespace*) makeNamespaceHref: (NSString*)href prefix: (NSString*)prefix;
Availability: Not in OpenStep/MacOS-X

Create a namespace attached to this node.

makePI: content: 

- (GSXMLNode*) makePI: (NSString*)name content: (NSString*)content;
Availability: Not in OpenStep/MacOS-X

Creation of a new process instruction element, added at the end of parent children list.
 d = [GSXMLDocument documentWithVersion: @"1.0"];

 [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]];
 [[d root] setObject: @"0.9" forKey: @"version"];
 n1 = [[d root] makeChildWithNamespace: nil name: @"dict" content: nil];
 [n1 makeComment: @" this is a comment "];
 [n1 makePI: @"pi1" content: @"this is a process instruction"];
 

makeText: 

- (GSXMLNode*) makeText: (NSString*)content;
Availability: Not in OpenStep/MacOS-X

Creation of a new text element, added at the end of parent children list.
 d = [GSXMLDocument documentWithVersion: @"1.0"];

 [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]];
 [[d root] setObject: @"0.9" forKey: @"version"];
 n1 = [[d root] makeChildWithNamespace: nil name: @"dict" content: nil];
 [n1 makeText: @" this is a text "];
 

name 

- (NSString*) name;
Availability: Not in OpenStep/MacOS-X

Return the node-name

namespace 

- (GSXMLNamespace*) namespace;
Availability: Not in OpenStep/MacOS-X

Return the namespace of the node.

namespaceDefinitions 

- (GSXMLNamespace*) namespaceDefinitions;
Availability: Not in OpenStep/MacOS-X

Return namespace definitions for the node

next 

- (GSXMLNode*) next;
Availability: Not in OpenStep/MacOS-X

Return the next node at this level. This method can return any type of node, and it may be more convenient to use the -nextElement node if you are parsing a document where you wish to ignore non-element nodes such as whitespace text separating elements.

nextElement 

- (GSXMLNode*) nextElement;
Availability: Not in OpenStep/MacOS-X

Returns the next element node, skipping past any other node types (such as text nodes). If there is no element node to be returned, this method returns nil.
NB. This method is not available in java, as the method name conflicts with that of java's Enumerator class.

objectForKey: 

- (NSString*) objectForKey: (NSString*)key;
Availability: Not in OpenStep/MacOS-X

Return the attribute value for the specified key.

parent 

- (GSXMLNode*) parent;
Availability: Not in OpenStep/MacOS-X

Return the parent of this node.

previous 

- (GSXMLNode*) previous;
Availability: Not in OpenStep/MacOS-X

Return the previous node at this level.

previousElement 

- (GSXMLNode*) previousElement;
Availability: Not in OpenStep/MacOS-X

Return the previous element node at this level.
NB. This method is not available in java, as the method name conflicts with that of java's Enumerator class.

propertiesAsDictionaryWithKeyTransformationSel: 

- (NSMutableDictionary*) propertiesAsDictionaryWithKeyTransformationSel: (SEL)keyTransformSel;
Availability: Not in OpenStep/MacOS-X

Return attributes and values as a dictionary, but applies the specified selector to each key before adding the key and value to the dictionary. The selector must be a method of NSString taking no arguments and returning an object suitable for use as a dictionary key.

This method exists for the use of GSWeb... it is probably not of much use elsewhere.


setNamespace: 

- (void) setNamespace: (GSXMLNamespace*)space;
Availability: Not in OpenStep/MacOS-X

Sets the namespace of the receiver to the value specified.
Supplying a nil namespace removes any namespace previously set or any namespace that the node inherited from a parent when it was created.

setObject: forKey: 

- (void) setObject: (NSString*)value forKey: (NSString*)key;
Availability: Not in OpenStep/MacOS-X

Set (or reset) an attribute carried by a node.
   [n1 setObject: @"prop1" forKey: @"name1"];
   [n1 setObject: @"prop2" forKey: @"name2"];
   [n1 setObject: @"prop3" forKey: @"name3"];
 

type 

- (NSInteger) type;
Availability: Not in OpenStep/MacOS-X

Return node-type. The most efficient way of testing node types is to use this method and compare the return value with a value you previously obtained using the +typeFromDescription: method.

typeDescription 

- (NSString*) typeDescription;
Availability: Not in OpenStep/MacOS-X

Return node type as a string.



Instance Variables for GSXMLNode Class

_parent

@protected id _parent;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

lib

@protected void* lib;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.




Software documentation for the GSXMLParser class

GSXMLParser : NSObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

The XML parser object is the pivotal part of parsing an XML document - it will either build a tree representing the document (if initialized without a GSSAXHandler), or will cooperate with a GSSAXHandler object to provide parsing without the overhead of building a tree.

The parser may be initialized with an input source (in which case it will expect to be asked to parse the entire input in a single operation), or without. If it is initialised without an input source, incremental parsing can be done by feeding successive parts of the XML document into the parser as NSData objects.


Instance Variables

Method summary

loadEntity: at: 

+ (NSString*) loadEntity: (NSString*)publicId at: (NSString*)location;
Availability: Not in OpenStep/MacOS-X

This method controls the loading of external entities into the system. If it returns an empty string, the entity is not loaded. If it returns a filename, the entity is loaded from that file. If it returns nil, the default entity loading mechanism is used.

The default entity loading mechanism is to construct a file name from the locationURL, by replacing all path separators with underscores, then attempt to locate that file in the DTDs resource directory of the main bundle, and all the standard system locations.

As a special case, the default loader examines the publicID and if it is a GNUstep DTD, the loader constructs a special name from the ID (by replacing dots with underscores and spaces with hyphens) and looks for a file with that name and a '.dtd' extension in the GNUstep bundles.

NB. This method will only be called if there is no SAX handler in use, or if the corresponding method in the SAX handler returns nil.


parser 

+ (GSXMLParser*) parser;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser (for incremental parsing) by calling -initWithSAXHandler:

parserWithContentsOfFile: 

+ (GSXMLParser*) parserWithContentsOfFile: (NSString*)path;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:withContentsOfFile:
 GSXMLParser       *p = [GSXMLParser parserWithContentsOfFile: @"macos.xml"];

 if ([p parse])
   {
     [[p document] dump];
   }
 else
   {
     printf("error parse file\n");
   }
 

parserWithContentsOfURL: 

+ (GSXMLParser*) parserWithContentsOfURL: (NSURL*)url;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:withContentsOfURL:

parserWithData: 

+ (GSXMLParser*) parserWithData: (NSData*)data;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:withData:

parserWithSAXHandler: 

+ (GSXMLParser*) parserWithSAXHandler: (GSSAXHandler*)handler;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:

If the handler object supplied is nil, the parser will build a tree representing the parsed file rather than attempting to get the handler to deal with the parsed elements and entities.


parserWithSAXHandler: withContentsOfFile: 

+ (GSXMLParser*) parserWithSAXHandler: (GSSAXHandler*)handler withContentsOfFile: (NSString*)path;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:withContentsOfFile:
 NSAutoreleasePool *arp = [NSAutoreleasePool new];
 GSSAXHandler *h = [GSDebugSAXHandler handler];
 GSXMLParser  *p = [GSXMLParser parserWithSAXHandler: h
                                  withContentsOfFile: @"macos.xml"];
 if ([p parse])
   {
      printf("ok\n");
   }
 RELEASE(arp);
 

parserWithSAXHandler: withContentsOfURL: 

+ (GSXMLParser*) parserWithSAXHandler: (GSSAXHandler*)handler withContentsOfURL: (NSURL*)url;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:withContentsOfURL:

parserWithSAXHandler: withData: 

+ (GSXMLParser*) parserWithSAXHandler: (GSSAXHandler*)handler withData: (NSData*)data;
Availability: Not in OpenStep/MacOS-X

Creation of a new Parser by calling -initWithSAXHandler:withData:

setDTDs: 

+ (void) setDTDs: (NSString*)aPath;
Availability: Not in OpenStep/MacOS-X

Sets a directory in which to look for DTDs when resolving external references. Can be used whjen DTDs have not been installed in the normal locatioons.

xmlEncodingStringForStringEncoding: 

+ (NSString*) xmlEncodingStringForStringEncoding: (NSStringEncoding)encoding;
Availability: Not in OpenStep/MacOS-X

Return the name of the string encoding (for XML) to use for the specified OpenStep encoding.

abortParsing 

- (void) abortParsing;
Availability: Not in OpenStep/MacOS-X

If called by a SAX callback routine, this method will terminate the parsiong process.

columnNumber 

- (NSInteger) columnNumber;
Availability: Not in OpenStep/MacOS-X

If executed during a parse operation, returns the current column number.

doValidityChecking: 

- (BOOL) doValidityChecking: (BOOL)yesno;
Availability: Not in OpenStep/MacOS-X

Sets whether the document needs to be validated.

document 

- (GSXMLDocument*) document;
Availability: Not in OpenStep/MacOS-X

Return the document produced as a result of parsing data.

errNo 

- (NSInteger) errNo;
Availability: Not in OpenStep/MacOS-X

Return error code for last parse operation.

getWarnings: 

- (BOOL) getWarnings: (BOOL)yesno;
Availability: Not in OpenStep/MacOS-X

Sets whether warnings are generated.

initWithSAXHandler: 

- (id) initWithSAXHandler: (GSSAXHandler*)handler;
Availability: Not in OpenStep/MacOS-X

This is a designated initialiser for the class.

Initialisation of a new Parser with SAX handler.

If the handler object supplied is nil, the parser will use an instance of GSTreeSAXHandler to build a tree representing the parsed file. This tree will then be available (via the -document method) as a GSXMLDocument on completion of parsing.

The source for the parsing process is not specified - so parsing must be done incrementally by feeding data to the parser.


initWithSAXHandler: withContentsOfFile: 

- (id) initWithSAXHandler: (GSSAXHandler*)handler withContentsOfFile: (NSString*)path;
Availability: Not in OpenStep/MacOS-X

Initialisation of a new Parser with SAX handler (if not nil) by calling -initWithSAXHandler:

Sets the input source for the parser to be the specified file - so parsing of the entire file will be performed rather than incremental parsing.


initWithSAXHandler: withContentsOfURL: 

- (id) initWithSAXHandler: (GSSAXHandler*)handler withContentsOfURL: (NSURL*)url;
Availability: Not in OpenStep/MacOS-X

Initialisation of a new Parser with SAX handler (if not nil) by calling -initWithSAXHandler:

Sets the input source for the parser to be the specified URL - so parsing of the entire document will be performed rather than incremental parsing.


initWithSAXHandler: withData: 

- (id) initWithSAXHandler: (GSSAXHandler*)handler withData: (NSData*)data;
Availability: Not in OpenStep/MacOS-X

Initialisation of a new Parser with SAX handler (if not nil) by calling -initWithSAXHandler:

Sets the input source for the parser to be the specified data object (which must contain an XML document), so parsing of the entire document will be performed rather than incremental parsing.


keepBlanks: 

- (BOOL) keepBlanks: (BOOL)yesno;
Availability: Not in OpenStep/MacOS-X

Set and return the previous value for blank text nodes support. ignorableWhitespace nodes are only generated when running the parser in validating mode and when the current element doesn't allow CDATA or mixed content.

lineNumber 

- (NSInteger) lineNumber;
Availability: Not in OpenStep/MacOS-X

If executed during a parse operation, returns the current line number.

messages 

- (NSString*) messages;
Availability: Not in OpenStep/MacOS-X

Returns the string into which warning and error messages are saved, or nil if they are being written to stderr.

parse 

- (BOOL) parse;
Availability: Not in OpenStep/MacOS-X

Parse source. Return YES if parsed, otherwise NO. This method should be called once to parse the entire document.
 GSXMLParser       *p = [GSXMLParser parserWithContentsOfFile:@"macos.xml"];

 if ([p parse])
   {
     [[p doc] dump];
   }
 else
   {
     printf("error parse file\n");
   }
 

parse: 

- (BOOL) parse: (NSData*)data;
Availability: Not in OpenStep/MacOS-X

Pass data to the parser for incremental parsing. This method should be called many times, with each call passing another block of data from the same document. After the whole of the document has been parsed, the method should be called with an empty or nil data object to indicate end of parsing. On this final call, the return value indicates whether the document was valid or not.

 GSXMLParser       *p = [GSXMLParser parserWithSAXHandler: nil source: nil];

 while ((data = getMoreData()) != nil)
   {
     if ([p parse: data] == NO)
       {
         NSLog(@"parse error");
       }
   }
   // Do something with document parsed
 [p parse: nil];  // Completed parsing of document.
 

publicID 

- (NSString*) publicID;
Availability: Not in OpenStep/MacOS-X

Return the public ID of the document being parsed.

saveMessages: 

- (void) saveMessages: (BOOL)yesno;
Availability: Not in OpenStep/MacOS-X

Sets up (or removes) a mutable string to which error and warning messages are saved. Using an argument of NO will cause these messages to be written to stderr (the default).
NB. A SAX handler which overrides the error and warning logging messages may stop this mechanism operating.

substituteEntities: 

- (BOOL) substituteEntities: (BOOL)yesno;
Availability: Not in OpenStep/MacOS-X

Set and return the previous value for entity support. Initially the parser always keeps entity references instead of substituting entity values in the output.

systemID 

- (NSString*) systemID;
Availability: Not in OpenStep/MacOS-X

Return the system ID of the document being parsed.



Instance Variables for GSXMLParser Class

lib

@protected void* lib;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

messages

@protected NSMutableString* messages;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

saxHandler

@protected GSSAXHandler* saxHandler;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

src

@protected id src;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.




Software documentation for the GSXMLRPC class

GSXMLRPC : NSObject

Declared in:
GNUstepBase/GSXML.h
Conforms to:
NSURLHandleClient
Availability: Not in OpenStep/MacOS-X

The GSXMLRPC class provides methods for constructing and parsing XMLRPC method call and response documents ... so that calls may be constructed of standard objects.

The correspondence between XMLRPC values and Objective-C objects is as follows -

If you attempt to use any other type of object in the construction of an XMLRPC document, the [NSObject -description] method of that object will be used to create a striong, and the resulting object will be encoded as an XMLRPC string element.

In particular, the names of members in a struct must be strings, so if you provide an NSDictionary object to represent a struct the keys of the dictionary will be converted to strings if necessary.

The class also provides a method for making a synchronous XMLRPC method call (with timeout), or an asynchronous call in which the call completion is handled by a delegate.

You may also use the class to implement an XMLRPC server, by calling the -parseMethod:params: method to parse the data POSTed to your server, and -buildResponseWithParams: (or -buildResponseWithFaultCode:andString:) to produce the data to be sent back to the client.

In order to simply make a synchronous XMLRPC call to a server, all you need to do is write code like:

   GSXMLRPC	*server = [[GSXMLRPC alloc] initWithURL: @"http://server/path"];
   id		result = [server makeMethodCall: name params: p timeout: 30];
 

Saying that you want to call the specified method ('name') on the server, passing the parameters ('p') and with a 30 second timeout.
If there is a network or http-level error or a timeout, the result will be an error string, otherwise it will be an array (on success) or a dictionary containing the fault details.

Method summary

URLHandle: resourceDataDidBecomeAvailable: 

- (void) URLHandle: (NSURLHandle*)sender resourceDataDidBecomeAvailable: (NSData*)newData;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.

URLHandle: resourceDidFailLoadingWithReason: 

- (void) URLHandle: (NSURLHandle*)sender resourceDidFailLoadingWithReason: (NSString*)reason;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.

URLHandleResourceDidBeginLoading: 

- (void) URLHandleResourceDidBeginLoading: (NSURLHandle*)sender;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.

URLHandleResourceDidCancelLoading: 

- (void) URLHandleResourceDidCancelLoading: (NSURLHandle*)sender;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.

URLHandleResourceDidFinishLoading: 

- (void) URLHandleResourceDidFinishLoading: (NSURLHandle*)sender;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.

buildMethod: params: 

- (NSData*) buildMethod: (NSString*)method params: (NSArray*)params;
Availability: Not in OpenStep/MacOS-X

Given a method name and an array of parameters, this method constructs the XML document for the corresponding XMLRPC call and returns the document as an NSData object containing UTF-8 text.
The params array may be empty or nil if there are no parameters to be passed.
The method returns nil if passed an invalid method name (a method name may contain any of the ascii alphanumeric characters and underscore, fullstop, colon, or slash).
This method is used internally when sending an XMLRPC method call to a remote system, but you can also call it yourself.

buildMethodCall: params: 

- (NSString*) buildMethodCall: (NSString*)method params: (NSArray*)params;
Availability: Not in OpenStep/MacOS-X

Given a method name and an array of parameters, this method constructs the XML document for the corresponding XMLRPC call and returns the document as a string.
The params array may be empty or nil if there are no parameters to be passed.
The method returns nil if passed an invalid method name (a method name may contain any of the ascii alphanumeric characters and underscore, fullstop, colon, or slash).

buildResponseWithFaultCode: andString: 

- (NSString*) buildResponseWithFaultCode: (NSInteger)code andString: (NSString*)s;
Availability: Not in OpenStep/MacOS-X

Constructs an XML document for an XMLRPC fault response with the specified code and string. The resulting document is returned as a string.
This method is intended for use by applications acting as XMLRPC servers.

buildResponseWithParams: 

- (NSString*) buildResponseWithParams: (NSArray*)params;
Availability: Not in OpenStep/MacOS-X

Builds an XMLRPC response with the specified array of parameters and returns the document as a string.
The params array may be empty or nil if there are no parameters to be returned (an empty params element will be created).
This method is intended for use by applications acting as XMLRPC servers.

compact 

- (BOOL) compact;
Availability: Not in OpenStep/MacOS-X

Return the value set by a prior call to -setCompact: (or NO... the default).

delegate 

- (id) delegate;
Availability: Not in OpenStep/MacOS-X

Returns the delegate previously set by the -setDelegate: method.
The delegate handles completion of asynchronous method calls to the URL specified when the receiver was initialised (if any).

initWithURL: 

- (id) initWithURL: (NSString*)url;
Availability: Not in OpenStep/MacOS-X

Initialise the receiver to make XMLRPC calls to the specified URL.
This method just calls -initWithURL:certificate:privateKey:password: with nil arguments for the SSL credentials.

initWithURL: certificate: privateKey: password: 

- (id) initWithURL: (NSString*)url certificate: (NSString*)cert privateKey: (NSString*)pKey password: (NSString*)pwd;
Availability: Not in OpenStep/MacOS-X

This is a designated initialiser for the class.
Initialise the receiver to make XMLRPC calls to the specified url and (optionally) with the specified SSL parameters.
The url argument may be nil, in which case the receiver will be unable to make XMLRPC calls, but can be used to parse incoming requests and build responses.
If the SSL credentials are non-nil, connections to the remote server will be authenticated using the supplied certificate so that the remote system knows who is contacting it.

makeMethodCall: params: timeout: 

- (id) makeMethodCall: (NSString*)method params: (NSArray*)params timeout: (NSInteger)seconds;
Availability: Not in OpenStep/MacOS-X

Calls -sendMethodCall:params:timeout: and waits for the response.
Returns the response parameters (an array), the response fault (a dictionary), or a failure reason (a string).

parseMethod: params: 

- (NSString*) parseMethod: (NSData*)request params: (NSMutableArray*)params;
Availability: Not in OpenStep/MacOS-X

Parses XML data containing an XMLRPC method call.
Returns the name of the method call.
Empties, and then places the method parameters (if any) in the params argument.
NB. Any containers (arrays or dictionaries) in the parsed parameters will be mutable, so you can modify this data structure as you like.
Raises an exception if parsing fails.
This method is intended for the use of XMLRPC server applications.

parseResponse: params: 

- (NSDictionary*) parseResponse: (NSData*)resp params: (NSMutableArray*)params;
Availability: Not in OpenStep/MacOS-X

Parses XML data containing an XMLRPC method response.
Returns nil for success, the fault dictionary on failure.
Places the response parameters (if any) in the params argument.
NB. Any containers (arrays or dictionaries) in the parsed parameters will be mutable, so you can modify this data structure as you like.
Raises an exception if parsing fails.
Used internally when making a method call to a remote server.

result 

- (id) result;
Availability: Not in OpenStep/MacOS-X

Returns the result of the last method call, or nil if there has been no method call or one is in progress.
The result may be one of -
  • A mutable array... the parameters of a success response.
  • A dictionary... containing a fault response.
  • A string... describing a low-level failure (eg. timeout).
NB. Any containers (arrays or dictionaries) in the parsed parameters of a success response will be mutable, so you can modify this data structure as you like.

sendMethodCall: params: timeout: 

- (BOOL) sendMethodCall: (NSString*)method params: (NSArray*)params timeout: (NSInteger)seconds;
Availability: Not in OpenStep/MacOS-X

Send an asynchronous XMLRPC method call with the specified timeout.
A delegate should have been set to handle the result of this call, but if one was not set the state of the asynchronous call may be polled by calling the -result method, which will return nil as long as the call has not completed.
The call may be cancelled by calling the -timeout: method
This method returns YES if the call was started, NO if it could not be started (eg because another call is in progress or because of bad arguments).
NB. For the asynchronous operation to proceed, the current NSRunLoop must be run.

setCompact: 

- (void) setCompact: (BOOL)flag;
Availability: Not in OpenStep/MacOS-X

Specify whether to generate compact XML (omit indentation and other white space and omit <string> element markup).
Compact representation saves some space (can be important when sent over slow/low bandwidth connections), but sacrifices readability.

setDebug: 

- (void) setDebug: (BOOL)flag;
Availability: Not in OpenStep/MacOS-X

Specify whether to perform debug trace on I/O

setDelegate: 

- (void) setDelegate: (id)aDelegate;
Availability: Not in OpenStep/MacOS-X

Sets the delegate object which will receive callbacks when an XMLRPC call completes.
NB. this delegate is not retained, and should be removed before it is deallocated (call -setDelegate: again with a nil argument to remove the delegate).

setTimeZone: 

- (void) setTimeZone: (NSTimeZone*)timeZone;
Availability: Not in OpenStep/MacOS-X

Sets the time zone for use when sending/receiving date/time values.
The XMLRPC specification says that timezone is server dependent so you will need to set it according to the server you are connecting to.
If this is not set, UCT is assumed.

timeZone 

- (NSTimeZone*) timeZone;
Availability: Not in OpenStep/MacOS-X

Return the time zone currently set.

timeout: 

- (void) timeout: (NSTimer*)t;
Availability: Not in OpenStep/MacOS-X

Handles timeouts, passing information to delegate ... you don't need to call this method, but you may call it in order to cancel an asynchronous request as if it had timed out.

Software documentation for the GSXPathBoolean class

GSXPathBoolean : GSXPathObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

For XPath queries returning true/false.
Method summary

booleanValue 

- (BOOL) booleanValue;
Availability: Not in OpenStep/MacOS-X

Returns the the value of the receiver... YES/NO, true/false.

Software documentation for the GSXPathContext class

GSXPathContext : NSObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

Use of the GSXPathContext class is simple... you just need to look up xpath to learn the syntax of xpath expressions, then you can apply those expressions to a context to retrieve data from a document.

 GSXMLParser       *p = [GSXMLParser parserWithContentsOfFile: @"xp.xml"];

 if ([p parse])
   {
     GSXMLDocument *d = [p document];
     GSXPathContext *c = [[GSXPathContext alloc] initWithDocument: document];
     GSXPathString *result = [c evaluateExpression: @"string(/body/text())"];

     GSPrintf(stdout, @"Got %@", [result stringValue]);
   }
 else
   {
     GSPrintf(stderr, "error parsing file\n");
   }
 

Instance Variables

Method summary

evaluateExpression: 

- (GSXPathObject*) evaluateExpression: (NSString*)XPathExpression;
Availability: Not in OpenStep/MacOS-X

Evaluates the supplied expression and returns the resulting node or node set. If the expression is invalid, returns nil.

initWithDocument: 

- (id) initWithDocument: (GSXMLDocument*)d;
Availability: Not in OpenStep/MacOS-X

Initialises the receiver as an xpath parser for the supplied document.

registerNamespaceWithPrefix: href: 

- (BOOL) registerNamespaceWithPrefix: (NSString*)prefix href: (NSString*)href;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.



Instance Variables for GSXPathContext Class

_document

@protected GSXMLDocument* _document;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_lib

@protected void* _lib;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.




Software documentation for the GSXPathNodeSet class

GSXPathNodeSet : GSXPathObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

For XPath queries returning a node set.
An XPATH node set is an ordered set of nodes returned as a result of an expression. The order of the nodes in the set is the same as the order in the xml document from which they were extracted.
Method summary

count 

- (NSUInteger) count;
Availability: Not in OpenStep/MacOS-X

Returns the number of nodes in the receiver.

length 

- (NSUInteger) length;
Availability: Not in OpenStep/MacOS-X

Deprecated

nodeAtIndex: 

- (GSXMLNode*) nodeAtIndex: (NSUInteger)index;
Availability: Not in OpenStep/MacOS-X

Please note that index starts from 0.
Returns the node from the receiver at the specified index, or nil if no such node exists.

Software documentation for the GSXPathNumber class

GSXPathNumber : GSXPathObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

For XPath queries returning a number.
Method summary

doubleValue 

- (double) doubleValue;
Availability: Not in OpenStep/MacOS-X

Returns the floating point (double ) value of the receiver.

Software documentation for the GSXPathObject class

GSXPathObject : NSObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

XPath queries return a GSXPathObject. GSXPathObject in itself is an abstract class; there are four types of completely different GSXPathObject types, listed below. I'm afraid you need to check the returned type of each GSXPath query to make sure it's what you meant it to be.

You don't create GSXPathObject instances, instead the XPATH system creates them and returns them as the result of the [GSXPathContext -evaluateExpression:] method.


Instance Variables



Instance Variables for GSXPathObject Class

_context

@protected GSXPathContext* _context;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_lib

@protected void* _lib;
Availability: Not in OpenStep/MacOS-X

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.




Software documentation for the GSXPathString class

GSXPathString : GSXPathObject

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

For XPath queries returning a string.
Method summary

stringValue 

- (NSString*) stringValue;
Availability: Not in OpenStep/MacOS-X

Returns the string value of the receiver.

Software documentation for the GSXMLDocument(XSLT) category

GSXMLDocument(XSLT)

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

Description forthcoming.
Method summary

xsltTransformFile: stylesheet: 

+ (GSXMLDocument*) xsltTransformFile: (NSString*)xmlFile stylesheet: (NSString*)xsltStylesheet;
Availability: Not in OpenStep/MacOS-X

Performs an XSLT transformation on the specified file using the stylesheet provided.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil on failure.

xsltTransformFile: stylesheet: params: 

+ (GSXMLDocument*) xsltTransformFile: (NSString*)xmlFile stylesheet: (NSString*)xsltStylesheet params: (NSDictionary*)params;
Availability: Not in OpenStep/MacOS-X

Performs an XSLT transformation on the specified file using the stylesheet and parameters provided. See the libxslt documentation for details of the supported parameters.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil on failure.

xsltTransformXml: stylesheet: 

+ (GSXMLDocument*) xsltTransformXml: (NSData*)xmlData stylesheet: (NSData*)xsltStylesheet;
Availability: Not in OpenStep/MacOS-X

Performs an XSLT transformation on the specified file using the stylesheet provided.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil on failure.

xsltTransformXml: stylesheet: params: 

+ (GSXMLDocument*) xsltTransformXml: (NSData*)xmlData stylesheet: (NSData*)xsltStylesheet params: (NSDictionary*)params;
Availability: Not in OpenStep/MacOS-X

Performs an XSLT transformation on the specified file using the stylesheet and parameters provided.See the libxslt documentation for details of the supported parameters.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil on failure.

xsltTransform: 

- (GSXMLDocument*) xsltTransform: (GSXMLDocument*)xsltStylesheet;
Availability: Not in OpenStep/MacOS-X

Performs an XSLT transformation on the current document using the supplied stylesheet.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil on failure.

xsltTransform: params: 

- (GSXMLDocument*) xsltTransform: (GSXMLDocument*)xsltStylesheet params: (NSDictionary*)params;
Availability: Not in OpenStep/MacOS-X

Performs an XSLT transformation on the current document using the supplied stylesheet and paramaters (params may be nil). See the libxslt documentation for details of the supported parameters.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil on failure.

Software documentation for the GSXMLRPC(Delegate) category

GSXMLRPC(Delegate)

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

Delegates should implement this method in order to be informed of the success or failure of an XMLRPC method call which was initiated by the -sendMethodCall:params:timeout: method.
Method summary

completedXMLRPC: 

- (void) completedXMLRPC: (GSXMLRPC*)sender;
Availability: Not in OpenStep/MacOS-X

An empty method provided for subclasses to override.
Called by the sender when an XMLRPC method call completes (either success or failure). The delegate may then call the -result method to retrieve the result of the method call from the sender.

Software documentation for the NSString(GSXML) category

NSString(GSXML)

Declared in:
GNUstepBase/GSXML.h
Availability: Not in OpenStep/MacOS-X

Convenience methods for managing XML escape sequences in an NSString.
Method summary

stringByEscapingXML 

- (NSString*) stringByEscapingXML;
Availability: Not in OpenStep/MacOS-X

Deals with standard XML internal entities.
Converts the five XML special characters in the receiver ('>', '<', '&', ''' and '"') to their escaped equivalents, and return the escaped string.
Also converts non-ascii characters to the corresponding numeric entity escape sequences.
You should perform any non-standard entity substitution you require after you have called this method.

stringByUnescapingXML 

- (NSString*) stringByUnescapingXML;
Availability: Not in OpenStep/MacOS-X

Deals with standard XML internal entities.
Converts the five XML escape sequences ('&gt;', '&lt;', '&amp;', '&apos;' and '&quot;') to the unicode characters they represent, and returns the unescaped string.
Also converts numeric entity escape sequences to the corresponding unicode characters.
You should perform any non-standard entity substitution you require before you have called this method.


Up