# The XML and HTML parsing system

mishel@berest.dp.ua
rfm@gnu.org
2000-2005 Free Software Foundation, Inc.
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
GNUstepBase/GSXML.h
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
GNUstepBase/GSXML.h
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
GNUstepBase/GSXML.h

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.

Description forthcoming.
Description forthcoming.
Description forthcoming.
handler
Create a new SAX handler.
attribute:
name
value:
value
Handle an attribute that has been read by the parser.
attributeDecl:
nameElement
name:
name
type:
type
typeDefValue:
defType
defaultValue:
value
An attribute definition has been parsed.
cdataBlock:
value
Called when a cdata block has been parsed.
characters:
name
Receiving some chars from the parser.
comment:
value
A comment has been parsed.
elementDecl:
name
type:
type
An element definition has been parsed.
endDocument
Called when the document end has been detected.
endElement:
elementName
Called when a closing tag has been processed.
endElement:
elementName
prefix:
prefix
href:
href
Called when a closing tag has been processed.
entityDecl:
name
type:
type
public:
publicId
system:
systemId
content:
content
An entity definition has been parsed.
error:
e
Called when an error message needs to be output.
error:
e
colNumber:
colNumber
lineNumber:
lineNumber
Called when an error message needs to be output.
externalSubset:
name
externalID:
externalID
systemID:
systemID
Called to find out whether there is an external subset.
fatalError:
e
Called when a fatal error message needs to be output.
fatalError:
e
colNumber:
colNumber
lineNumber:
lineNumber
Called when a fatal error message needs to be output.
getEntity:
name
get an entity by name
getParameterEntity:
name
get a parameter entity by name
globalNamespace:
name
href:
href
prefix:
prefix
An old global namespace has been parsed.
hasExternalSubset
Called to find out whether there is an external subset.
hasInternalSubset
Called to find out whether there is an internal subset.
ignoreWhitespace:
ch
Receiving some ignorable whitespaces from the parser.
internalSubset:
name
externalID:
externalID
systemID:
systemID
Called to find out whether there is an internal subset.
isStandalone
Called to detemrine if the document is standalone.
lib
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
loadEntity:
publicId
at:
location
Called to return the filename from which an entity should be loaded.
namespaceDecl:
name
href:
href
prefix:
prefix
An old global namespace has been parsed.
notationDecl:
name
public:
publicId
system:
systemId
What to do when a notation declaration has been parsed.
parser
Return the parser object with which this handler is associated. This may occasionally be useful.
processInstruction:
targetName
data:
PIdata
A processing instruction has been parsed.
reference:
name
Called when an entity reference is detected.
startDocument
Called when the document starts being processed.
startElement:
elementName
attributes:
elementAttributes
Called when an opening tag has been processed.
startElement:
elementName
prefix:
prefix
href:
href
attributes:
elementAttributes
namespaces:
elementNamespaces
Description forthcoming.
unparsedEntityDecl:
name
public:
publicId
system:
systemId
notationName:
notation
What to do when an unparsed entity declaration is parsed.
warning:
e
Called when a warning message needs to be output.
warning:
e
colNumber:
colNumber
lineNumber:
lineNumber
Called when a warning message needs to be output.
Software documentation for the GSTreeSAXHandler class
GNUstepBase/GSXML.h
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
GNUstepBase/GSXML.h
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.
value
Returns the string value of the attribute.
Software documentation for the GSXMLDocument class
GNUstepBase/GSXML.h
NSCopying
A GSXML document wraps the document structure of the underlying libxml library.
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.
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.
Description forthcoming.
documentWithVersion:
version
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
Returns a string representation of the document (ie the XML) or `nil` if the document does not have reasonable contents.
encoding
Returns the name of the encoding for this document.
lib
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
makeNodeWithNamespace:
ns
name:
name
content:
content
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
Returns the root node of the document.
setRoot:
node
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
Returns the version string for this document.
writeToFile:
filename
atomically:
useAuxilliaryFile
Uses the -description method to produce a string representation of the document and writes that to filename.
writeToURL:
url
atomically:
useAuxilliaryFile
Uses the -description method to produce a string representation of the document and writes that to url.
Software documentation for the GSXMLNamespace class
GNUstepBase/GSXML.h
NSCopying
A GSXMLNamespace object wraps part of the document structure of the underlying libxml library.
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.
Description forthcoming.
descriptionFromType:
type
Return the string representation of the specified numeric type.
typeFromDescription:
desc
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
Returns the namespace reference
lib
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
next
return the next namespace.
prefix
Return the namespace prefix.
type
Return type of namespace
typeDescription
Return string representation of the type of the namespace.
Software documentation for the GSXMLNode class
GNUstepBase/GSXML.h
NSCopying
A GSXMLNode object wraps part of the document structure of the underlying libxml library. It may have a parent, siblings, and children.
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.
Description forthcoming.
descriptionFromType:
type
Return the string constant value for the node type given.
typeFromDescription:
desc

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

Return attributes and values as a dictionary

content
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
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
Return the document in which this node exists.
escapedContent
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
Return the first attribute in this node.
firstChild
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
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
Convenience method, equivalent to calling -type and comparing it with the result of passing "XML_ELEMENT_NODE" to +typeFromDescription: (but faster).
isText
Convenience method, equivalent to calling -type and comparing it with the result of passing "XML_TEXT_NODE" to +typeFromDescription: (but faster).
lib
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
makeAttributeWithName:
name
value:
value
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:
ns
name:
name
content:
content

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:
content
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:
href
prefix:
prefix
Create a namespace attached to this node.
makePI:
name
content:
content
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:
content
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
Return the node-name
namespace
Return the namespace of the node.
namespaceDefinitions
Return namespace definitions for the node
next
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
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:
key
Return the attribute value for the specified key.
parent
Return the parent of this node.
previous
Return the previous node at this level.
previousElement
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:
keyTransformSel

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:
space
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:
value
forKey:
key
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
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
Return node type as a string.
Software documentation for the GSXMLParser class
GNUstepBase/GSXML.h

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.

Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
loadEntity:
publicId
at:
location

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
Creation of a new Parser (for incremental parsing) by calling -initWithSAXHandler:
parserWithContentsOfFile:
path
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:
url
Creation of a new Parser by calling -initWithSAXHandler:withContentsOfURL:
parserWithData:
data
Creation of a new Parser by calling -initWithSAXHandler:withData:
parserWithSAXHandler:
handler

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:
handler
withContentsOfFile:
path
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:
handler
withContentsOfURL:
url
Creation of a new Parser by calling -initWithSAXHandler:withContentsOfURL:
parserWithSAXHandler:
handler
withData:
data
Creation of a new Parser by calling -initWithSAXHandler:withData:
setDTDs:
aPath
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:
encoding
Return the name of the string encoding (for XML) to use for the specified OpenStep encoding.
abortParsing
If called by a SAX callback routine, this method will terminate the parsiong process.
columnNumber
If executed during a parse operation, returns the current column number.
doValidityChecking:
yesno
Sets whether the document needs to be validated.
document
Return the document produced as a result of parsing data.
errNo
Return error code for last parse operation.
getWarnings:
yesno
Sets whether warnings are generated.
initWithSAXHandler:
handler

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 GSXMLDocumenton 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:
handler
withContentsOfFile:
path

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:
handler
withContentsOfURL:
url

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:
handler
withData:
data

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:
yesno
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
If executed during a parse operation, returns the current line number.
messages
Returns the string into which warning and error messages are saved, or `nil` if they are being written to stderr.
parse
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:
data

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
Return the public ID of the document being parsed.
saveMessages:
yesno
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:
yesno
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
Return the system ID of the document being parsed.
Software documentation for the GSXMLRPC class
GNUstepBase/GSXML.h
NSURLHandleClient

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 -

i4 (or int) is an NSNumber other than a real/float or boolean.
boolean is an NSNumber created as a BOOL.
string is an NSString object.
double is an NSNumber created as a float or double.
dateTime.iso8601 is an NSDate object.
base64 is an NSData object.
array is an NSArray object.
struct is an NSDictionaryobject.

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

URLHandle:
sender
resourceDataDidBecomeAvailable:
newData
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
URLHandle:
sender
resourceDidFailLoadingWithReason:
reason
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
URLHandleResourceDidBeginLoading:
sender
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
URLHandleResourceDidCancelLoading:
sender
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
URLHandleResourceDidFinishLoading:
sender
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
buildMethod:
method
params:
params
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:
method
params:
params
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:
code
andString:
s
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:
params
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
Return the value set by a prior call to -setCompact: (or `NO`... the default).
delegate
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:
url
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:
url
certificate:
cert
privateKey:
pKey
password:
pwd
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:
method
params:
params
timeout:
seconds
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:
request
params:
params
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:
resp
params:
params
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
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:
method
params:
params
timeout:
seconds
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:
flag
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:
flag
Specify whether to perform debug trace on I/O
setDelegate:
aDelegate
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:
timeZone
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
Return the time zone currently set.
timeout:
t
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
GNUstepBase/GSXML.h
For XPath queries returning true/false.
booleanValue
Returns the the value of the receiver... YES/NO, true/false.
Software documentation for the GSXPathContext class
GNUstepBase/GSXML.h

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"); }
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.
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.
evaluateExpression:
XPathExpression
Evaluates the supplied expression and returns the resulting node or node set. If the expression is invalid, returns `nil`.
initWithDocument:
d
Initialises the receiver as an xpath parser for the supplied document.
registerNamespaceWithPrefix:
prefix
href:
href
Description forthcoming.
Software documentation for the GSXPathNodeSet class
GNUstepBase/GSXML.h
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.
count
Returns the number of nodes in the receiver.
length
Deprecated
nodeAtIndex:
index
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
GNUstepBase/GSXML.h
For XPath queries returning a number.
doubleValue
Returns the floating point (double ) value of the receiver.
Software documentation for the GSXPathObject class
GNUstepBase/GSXML.h
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.

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.
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
GNUstepBase/GSXML.h
For XPath queries returning a string.
stringValue
Returns the string value of the receiver.
Software documentation for the GSXMLDocument(XSLT) category
GNUstepBase/GSXML.h
Description forthcoming.
xsltTransformFile:
xmlFile
stylesheet:
xsltStylesheet
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:
xmlFile
stylesheet:
xsltStylesheet
params:
params
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:
xmlData
stylesheet:
xsltStylesheet
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:
xmlData
stylesheet:
xsltStylesheet
params:
params
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:
xsltStylesheet
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:
xsltStylesheet
params:
params
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
GNUstepBase/GSXML.h
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.
completedXMLRPC:
sender
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
GNUstepBase/GSXML.h
Convenience methods for managing XML escape sequences in an NSString.
stringByEscapingXML
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
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.