Up
Authors
- Michael Pakhantsov (
mishel@berest.dp.ua
)
-
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Copyright: (C) 2000-2005 Free Software Foundation, Inc.
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
+ (
GSSAXHandler*)
handler;
Availability: BaseAdditions 0.0.0
Create a new SAX handler.
- (void)
attribute: (NSString*)name
value: (NSString*)value;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Handle an attribute that has been read by the parser.
- (void)
attributeDecl: (NSString*)nameElement
name: (NSString*)name
type: (int)type
typeDefValue: (int)defType
defaultValue: (NSString*)value;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
An attribute definition has been parsed.
- (void)
cdataBlock: (NSData*)value;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when a cdata block has been parsed.
- (void)
characters: (NSString*)name;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Receiving some chars from the parser.
- (void)
comment: (NSString*)value;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
A comment has been parsed.
- (void)
elementDecl: (NSString*)name
type: (int)type;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
An element definition has been parsed.
- (void)
endDocument;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when the document end has been detected.
- (void)
endElement: (NSString*)elementName;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when a closing tag has been processed.
- (void)
endElement: (NSString*)elementName
prefix: (NSString*)prefix
href: (NSString*)href;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when a closing tag has been processed.
- (void)
entityDecl: (NSString*)name
type: (int)type
public: (NSString*)publicId
system: (NSString*)systemId
content: (NSString*)content;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
An entity definition has been parsed.
- (void)
error: (NSString*)e;
Availability: BaseAdditions 0.0.0
Called when an error message needs to be output.
- (void)
error: (NSString*)e
colNumber: (int)colNumber
lineNumber: (int)lineNumber;
Availability: BaseAdditions 0.0.0
Called when an error message needs to be output.
- (BOOL)
externalSubset: (NSString*)name
externalID: (NSString*)externalID
systemID: (NSString*)systemID;
Availability: BaseAdditions 0.0.0
Called to find out whether there is an external subset.
- (void)
fatalError: (NSString*)e;
Availability: BaseAdditions 0.0.0
Called when a fatal error message needs to be output.
- (void)
fatalError: (NSString*)e
colNumber: (int)colNumber
lineNumber: (int)lineNumber;
Availability: BaseAdditions 0.0.0
Called when a fatal error message needs to be output.
- (void*)
getEntity: (NSString*)name;
Availability: BaseAdditions 0.0.0
get an entity by name
- (void*)
getParameterEntity: (NSString*)name;
Availability: BaseAdditions 0.0.0
get a parameter entity by name
- (void)
globalNamespace: (NSString*)name
href: (NSString*)href
prefix: (NSString*)prefix;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
An old global namespace has been parsed.
- (int)
hasExternalSubset;
Availability: BaseAdditions 0.0.0
Called to find out whether there is an external subset.
- (int)
hasInternalSubset;
Availability: BaseAdditions 0.0.0
Called to find out whether there is an internal subset.
- (void)
ignoreWhitespace: (NSString*)ch;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Receiving some ignorable whitespaces from the parser.
- (BOOL)
internalSubset: (NSString*)name
externalID: (NSString*)externalID
systemID: (NSString*)systemID;
Availability: BaseAdditions 0.0.0
Called to find out whether there is an internal subset.
- (int)
isStandalone;
Availability: BaseAdditions 0.0.0
Called to detemrine if the document is standalone.
- (void*)
lib;
Availability: BaseAdditions 0.0.0
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
- (NSString*)
loadEntity: (NSString*)publicId
at: (NSString*)location;
Availability: BaseAdditions 0.0.0
Called to return the filename from which an entity should be loaded.
- (void)
namespaceDecl: (NSString*)name
href: (NSString*)href
prefix: (NSString*)prefix;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
An old global namespace has been parsed.
- (void)
notationDecl: (NSString*)name
public: (NSString*)publicId
system: (NSString*)systemId;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
What to do when a notation declaration has been parsed.
- (
GSXMLParser*)
parser;
Availability: BaseAdditions 0.0.0
Return the parser object with which this handler is associated. This may occasionally be useful.
- (void)
processInstruction: (NSString*)targetName
data: (NSString*)PIdata;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
A processing instruction has been parsed.
- (void)
reference: (NSString*)name;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when an entity reference is detected.
- (void)
startDocument;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when the document starts being processed.
- (void)
startElement: (NSString*)elementName
attributes: (NSMutableDictionary*)elementAttributes;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Called when an opening tag has been processed.
- (void)
startElement: (NSString*)elementName
prefix: (NSString*)prefix
href: (NSString*)href
attributes: (NSMutableDictionary*)elementAttributes;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Description forthcoming.
- (void)
unparsedEntityDecl: (NSString*)name
public: (NSString*)publicId
system: (NSString*)systemId
notationName: (NSString*)notation;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
What to do when an unparsed entity declaration is parsed.
- (void)
warning: (NSString*)e;
Availability: BaseAdditions 0.0.0
Called when a warning message needs to be output.
- (void)
warning: (NSString*)e
colNumber: (int)colNumber
lineNumber: (int)lineNumber;
Availability: BaseAdditions 0.0.0
Called when a warning message needs to be output.
Instance Variables for GSSAXHandler Class
@protected BOOL isHtmlHandler;
Description forthcoming.
@protected void* lib;
Description forthcoming.
@protected GSXMLParser* parser;
Description forthcoming.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
- (NSString*)
value;
Availability: BaseAdditions 0.0.0
Returns the string value of the attribute.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSCopying
Availability: BaseAdditions 0.0.0
A GSXML document wraps the document structure of the underlying libxml library.
Instance Variables
Method summary
+ (
GSXMLDocument*)
documentWithVersion: (NSString*)version;
Availability: BaseAdditions 0.0.0
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"];
- (NSString*)
description;
Availability: BaseAdditions 0.0.0
Returns a string representation of the document (ie the XML) or nil
if the document does not have reasonable contents.
- (NSString*)
encoding;
Availability: BaseAdditions 0.0.0
Returns the name of the encoding for this document.
- (void*)
lib;
Availability: BaseAdditions 0.0.0
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
- (
GSXMLNode*)
makeNodeWithNamespace: (
GSXMLNamespace*)ns
name: (NSString*)name
content: (NSString*)content;
Availability: BaseAdditions 0.0.0
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];
- (
GSXMLNode*)
root;
Availability: BaseAdditions 0.0.0
Returns the root node of the document.
- (
GSXMLNode*)
setRoot: (
GSXMLNode*)node;
Availability: BaseAdditions 0.0.0
Sets the root node of the document.
- (NSString*)
version;
Availability: BaseAdditions 0.0.0
Returns the version string for this document.
- (BOOL)
writeToFile: (NSString*)filename
atomically: (BOOL)useAuxilliaryFile;
Availability: BaseAdditions 0.0.0
Uses the
-description
method to produce a string representation of the document and writes that to
filename.
- (BOOL)
writeToURL: (NSURL*)url
atomically: (BOOL)useAuxilliaryFile;
Availability: BaseAdditions 0.0.0
Uses the
-description
method to produce a string representation of the document and writes that to
url.
Instance Variables for GSXMLDocument Class
@protected BOOL _ownsLib;
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.
@protected id _parent;
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.
@protected void* lib;
Description forthcoming.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSCopying
Availability: BaseAdditions 0.0.0
A GSXMLNamespace object wraps part of the document structure of the underlying libxml library.
Instance Variables
Method summary
+ (NSString*)
descriptionFromType: (int)type;
Availability: BaseAdditions 0.0.0
Return the string representation of the specified numeric type.
+ (int)
typeFromDescription: (NSString*)desc;
Availability: BaseAdditions 0.0.0
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 -
- (NSString*)
href;
Availability: BaseAdditions 0.0.0
Returns the namespace reference
- (void*)
lib;
Availability: BaseAdditions 0.0.0
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
- (
GSXMLNamespace*)
next;
Availability: BaseAdditions 0.0.0
return the next namespace.
- (NSString*)
prefix;
Availability: BaseAdditions 0.0.0
Return the namespace prefix.
- (int)
type;
Availability: BaseAdditions 0.0.0
Return type of namespace
- (NSString*)
typeDescription;
Availability: BaseAdditions 0.0.0
Return string representation of the type of the namespace.
Instance Variables for GSXMLNamespace Class
@protected id _parent;
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.
@protected void* lib;
Description forthcoming.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSCopying
Availability: BaseAdditions 0.0.0
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
+ (NSString*)
descriptionFromType: (int)type;
Availability: BaseAdditions 0.0.0
Return the string constant value for the node type given.
+ (int)
typeFromDescription: (NSString*)desc;
Availability: BaseAdditions 0.0.0
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
- (NSDictionary*)
attributes;
Availability: BaseAdditions 0.0.0
Return attributes and values as a dictionary
- (NSString*)
content;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
description;
Availability: BaseAdditions 0.0.0
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.
- (
GSXMLDocument*)
document;
Availability: BaseAdditions 0.0.0
Return the document in which this node exists.
- (NSString*)
escapedContent;
Availability: BaseAdditions 0.0.0
This performs the same function as the
-content
method, but retains escaped character information (the standard five entities <, >, ', ", and &) which are normally replaced with their standard equivalents (<, >, ', ", and &).
- (
GSXMLAttribute*)
firstAttribute;
Availability: BaseAdditions 0.0.0
Return the first attribute in this node.
- (
GSXMLNode*)
firstChild;
Availability: BaseAdditions 0.0.0
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; }
- (
GSXMLNode*)
firstChildElement;
Availability: BaseAdditions 0.0.0
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.
- (BOOL)
isElement;
Availability: BaseAdditions 0.0.0
Convenience method, equivalent to calling
-type
and comparing it with the result of passing "XML_ELEMENT_NODE" to
+typeFromDescription:
(but faster).
- (BOOL)
isText;
Availability: BaseAdditions 0.0.0
Convenience method, equivalent to calling
-type
and comparing it with the result of passing "XML_TEXT_NODE" to
+typeFromDescription:
(but faster).
- (void*)
lib;
Availability: BaseAdditions 0.0.0
Returns a pointer to the raw libxml data used by this document.
Only for use by libxml experts!
- (
GSXMLAttribute*)
makeAttributeWithName: (NSString*)name
value: (NSString*)value;
Availability: BaseAdditions 0.0.0
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.
- (
GSXMLNode*)
makeChildWithNamespace: (
GSXMLNamespace*)ns
name: (NSString*)name
content: (NSString*)content;
Availability: BaseAdditions 0.0.0
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];
- (
GSXMLNode*)
makeComment: (NSString*)content;
Availability: BaseAdditions 0.0.0
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 "];
- (
GSXMLNamespace*)
makeNamespaceHref: (NSString*)href
prefix: (NSString*)prefix;
Availability: BaseAdditions 0.0.0
Create a namespace attached to this node.
- (
GSXMLNode*)
makePI: (NSString*)name
content: (NSString*)content;
Availability: BaseAdditions 0.0.0
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"];
- (
GSXMLNode*)
makeText: (NSString*)content;
Availability: BaseAdditions 0.0.0
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 "];
- (NSString*)
name;
Availability: BaseAdditions 0.0.0
Return the node-name
- (
GSXMLNamespace*)
namespace;
Availability: BaseAdditions 0.0.0
Return the namespace of the node.
- (
GSXMLNamespace*)
namespaceDefinitions;
Availability: BaseAdditions 0.0.0
Return namespace definitions for the node
- (
GSXMLNode*)
next;
Availability: BaseAdditions 0.0.0
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.
- (
GSXMLNode*)
nextElement;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
objectForKey: (NSString*)key;
Availability: BaseAdditions 0.0.0
Return the attribute value for the specified key.
- (
GSXMLNode*)
parent;
Availability: BaseAdditions 0.0.0
Return the parent of this node.
- (
GSXMLNode*)
previous;
Availability: BaseAdditions 0.0.0
Return the previous node at this level.
- (
GSXMLNode*)
previousElement;
Availability: BaseAdditions 0.0.0
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.
- (NSMutableDictionary*)
propertiesAsDictionaryWithKeyTransformationSel: (SEL)keyTransformSel;
Availability: BaseAdditions 0.0.0
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.
- (void)
setNamespace: (
GSXMLNamespace*)space;
Availability: BaseAdditions 0.0.0
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.
- (void)
setObject: (NSString*)value
forKey: (NSString*)key;
Availability: BaseAdditions 0.0.0
Set (or reset) an attribute carried by a node.
[n1 setObject: @"prop1" forKey: @"name1"]; [n1 setObject: @"prop2" forKey: @"name2"]; [n1 setObject: @"prop3" forKey: @"name3"];
- (int)
type;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
typeDescription;
Availability: BaseAdditions 0.0.0
Return node type as a string.
Instance Variables for GSXMLNode Class
@protected id _parent;
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.
@protected void* lib;
Description forthcoming.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
+ (NSString*)
loadEntity: (NSString*)publicId
at: (NSString*)location;
Availability: BaseAdditions 0.0.0
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
.
+ (
GSXMLParser*)
parser;
Availability: BaseAdditions 0.0.0
+ (
GSXMLParser*)
parserWithContentsOfFile: (NSString*)path;
Availability: BaseAdditions 0.0.0
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"); }
+ (
GSXMLParser*)
parserWithContentsOfURL: (NSURL*)url;
Availability: BaseAdditions 0.0.0
+ (
GSXMLParser*)
parserWithData: (NSData*)data;
Availability: BaseAdditions 0.0.0
+ (
GSXMLParser*)
parserWithSAXHandler: (
GSSAXHandler*)handler;
Availability: BaseAdditions 0.0.0
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.
+ (
GSXMLParser*)
parserWithSAXHandler: (
GSSAXHandler*)handler
withContentsOfFile: (NSString*)path;
Availability: BaseAdditions 0.0.0
Creation of a new Parser by calling
-initWithSAXHandler:withContentsOfFile:
CREATE_AUTORELEASE_POOL(arp); GSSAXHandler *h = [GSDebugSAXHandler handler]; GSXMLParser *p = [GSXMLParser parserWithSAXHandler: h withContentsOfFile: @"macos.xml"]; if ([p parse]) { printf("ok\n"); } RELEASE(arp);
+ (
GSXMLParser*)
parserWithSAXHandler: (
GSSAXHandler*)handler
withContentsOfURL: (NSURL*)url;
Availability: BaseAdditions 0.0.0
+ (
GSXMLParser*)
parserWithSAXHandler: (
GSSAXHandler*)handler
withData: (NSData*)data;
Availability: BaseAdditions 0.0.0
+ (NSString*)
xmlEncodingStringForStringEncoding: (NSStringEncoding)encoding;
Availability: BaseAdditions 0.0.0
Return the name of the string encoding (for XML) to use for the specified OpenStep encoding.
- (void)
abortParsing;
Availability: BaseAdditions 0.0.0
If called by a SAX callback routine, this method will terminate the parsiong process.
- (int)
columnNumber;
Availability: BaseAdditions 0.0.0
If executed during a parse operation, returns the current column number.
- (BOOL)
doValidityChecking: (BOOL)yesno;
Availability: BaseAdditions 0.0.0
Sets whether the document needs to be validated.
- (
GSXMLDocument*)
document;
Availability: BaseAdditions 0.0.0
Return the document produced as a result of parsing data.
- (int)
errNo;
Availability: BaseAdditions 0.0.0
Return error code for last parse operation.
- (BOOL)
getWarnings: (BOOL)yesno;
Availability: BaseAdditions 0.0.0
Sets whether warnings are generated.
- (id)
initWithSAXHandler: (
GSSAXHandler*)handler;
Availability: BaseAdditions 0.0.0
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.
- (id)
initWithSAXHandler: (
GSSAXHandler*)handler
withContentsOfFile: (NSString*)path;
Availability: BaseAdditions 0.0.0
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.
- (id)
initWithSAXHandler: (
GSSAXHandler*)handler
withContentsOfURL: (NSURL*)url;
Availability: BaseAdditions 0.0.0
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.
- (id)
initWithSAXHandler: (
GSSAXHandler*)handler
withData: (NSData*)data;
Availability: BaseAdditions 0.0.0
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.
- (BOOL)
keepBlanks: (BOOL)yesno;
Availability: BaseAdditions 0.0.0
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.
- (int)
lineNumber;
Availability: BaseAdditions 0.0.0
If executed during a parse operation, returns the current line number.
- (NSString*)
messages;
Availability: BaseAdditions 0.0.0
Returns the string into which warning and error messages are saved, or nil
if they are being written to stderr.
- (BOOL)
parse;
Availability: BaseAdditions 0.0.0
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"); }
- (BOOL)
parse: (NSData*)data;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
publicID;
Availability: BaseAdditions 0.0.0
Return the public ID of the document being parsed.
- (void)
saveMessages: (BOOL)yesno;
Availability: BaseAdditions 0.0.0
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.
- (BOOL)
substituteEntities: (BOOL)yesno;
Availability: BaseAdditions 0.0.0
Set and return the previous value for entity support. Initially the parser always keeps entity references instead of substituting entity values in the output.
- (NSString*)
systemID;
Availability: BaseAdditions 0.0.0
Return the system ID of the document being parsed.
Instance Variables for GSXMLParser Class
@protected void* lib;
Description forthcoming.
@protected NSMutableString* messages;
Description forthcoming.
@protected GSSAXHandler* saxHandler;
Description forthcoming.
@protected id src;
Description forthcoming.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSURLHandleClient
Availability: BaseAdditions 0.0.0
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 NSDictionary
object.
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
- (void)
URLHandle: (NSURLHandle*)sender
resourceDataDidBecomeAvailable: (NSData*)newData;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
- (void)
URLHandle: (NSURLHandle*)sender
resourceDidFailLoadingWithReason: (NSString*)reason;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
- (void)
URLHandleResourceDidBeginLoading: (NSURLHandle*)sender;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
- (void)
URLHandleResourceDidCancelLoading: (NSURLHandle*)sender;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
- (void)
URLHandleResourceDidFinishLoading: (NSURLHandle*)sender;
Availability: BaseAdditions 0.0.0
An empty method provided for subclasses to override.
Allows GSXMLRPC to act as a client of NSURLHandle. Internal use only.
- (NSData*)
buildMethod: (NSString*)method
params: (NSArray*)params;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
buildMethodCall: (NSString*)method
params: (NSArray*)params;
Availability: BaseAdditions 0.0.0
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).
- (NSString*)
buildResponseWithFaultCode: (int)code
andString: (NSString*)s;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
buildResponseWithParams: (NSArray*)params;
Availability: BaseAdditions 0.0.0
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.
- (BOOL)
compact;
Availability: BaseAdditions 0.0.0
Return the value set by a prior call to
-setCompact:
(or
NO
... the default).
- (id)
delegate;
Availability: BaseAdditions 0.0.0
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).
- (id)
initWithURL: (NSString*)url;
Availability: BaseAdditions 0.0.0
- (id)
initWithURL: (NSString*)url
certificate: (NSString*)cert
privateKey: (NSString*)pKey
password: (NSString*)pwd;
Availability: BaseAdditions 0.0.0
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.
- (id)
makeMethodCall: (NSString*)method
params: (NSArray*)params
timeout: (int)seconds;
Availability: BaseAdditions 0.0.0
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).
- (NSString*)
parseMethod: (NSData*)request
params: (NSMutableArray*)params;
Availability: BaseAdditions 0.0.0
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.
- (NSDictionary*)
parseResponse: (NSData*)response
params: (NSMutableArray*)params;
Availability: BaseAdditions 0.0.0
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.
- (id)
result;
Availability: BaseAdditions 0.0.0
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.
- (BOOL)
sendMethodCall: (NSString*)method
params: (NSArray*)params
timeout: (int)seconds;
Availability: BaseAdditions 0.0.0
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.
- (void)
setCompact: (BOOL)flag;
Availability: BaseAdditions 0.0.0
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.
- (void)
setDebug: (BOOL)flag;
Availability: BaseAdditions 0.0.0
Specify whether to perform debug trace on I/O
- (void)
setDelegate: (id)aDelegate;
Availability: BaseAdditions 0.0.0
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).
- (void)
setTimeZone: (NSTimeZone*)timeZone;
Availability: BaseAdditions 0.0.0
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.
- (NSTimeZone*)
timeZone;
Availability: BaseAdditions 0.0.0
Return the time zone currently set.
- (void)
timeout: (NSTimer*)t;
Availability: BaseAdditions 0.0.0
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
For XPath queries returning true/false.
Method summary
- (BOOL)
booleanValue;
Availability: BaseAdditions 0.0.0
Returns the the value of the receiver... YES/NO, true/false.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
Use of the GSXPathContext claass 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
- (
GSXPathObject*)
evaluateExpression: (NSString*)XPathExpression;
Availability: BaseAdditions 0.0.0
Evaluates the supplied expression and returns the resulting node or node set. If the expression is invalid, returns nil
.
- (id)
initWithDocument: (
GSXMLDocument*)d;
Availability: BaseAdditions 0.0.0
Initialises the receiver as an xpath parser for the supplied document.
Instance Variables for GSXPathContext Class
@protected GSXMLDocument* _document;
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.
@protected void* _lib;
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
- (unsigned int)
count;
Availability: BaseAdditions 0.0.0
Returns the number of nodes in the receiver.
- (unsigned int)
length;
Availability: BaseAdditions 0.0.0
Deprecated
- (
GSXMLNode*)
nodeAtIndex: (unsigned)index;
Availability: BaseAdditions 0.0.0
Please note that index starts from 0.
Returns the node from the receiver at the specified index, or nil
if no such node exists.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
For XPath queries returning a number.
Method summary
- (double)
doubleValue;
Availability: BaseAdditions 0.0.0
Returns the floating point (double ) value of the receiver.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
@protected GSXPathContext* _context;
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.
@protected void* _lib;
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
For XPath queries returning a string.
Method summary
- (NSString*)
stringValue;
Availability: BaseAdditions 0.0.0
Returns the string value of the receiver.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
Description forthcoming.
Method summary
+ (
GSXMLDocument*)
xsltTransformFile: (NSString*)xmlFile
stylesheet: (NSString*)xsltStylesheet;
Availability: BaseAdditions 0.0.0
Performs an XSLT transformation on the specified file using the stylesheet provided.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil
on failure.
+ (
GSXMLDocument*)
xsltTransformFile: (NSString*)xmlFile
stylesheet: (NSString*)xsltStylesheet
params: (NSDictionary*)params;
Availability: BaseAdditions 0.0.0
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.
+ (
GSXMLDocument*)
xsltTransformXml: (NSData*)xmlData
stylesheet: (NSData*)xsltStylesheet;
Availability: BaseAdditions 0.0.0
Performs an XSLT transformation on the specified file using the stylesheet provided.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil
on failure.
+ (
GSXMLDocument*)
xsltTransformXml: (NSData*)xmlData
stylesheet: (NSData*)xsltStylesheet
params: (NSDictionary*)params;
Availability: BaseAdditions 0.0.0
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.
- (
GSXMLDocument*)
xsltTransform: (
GSXMLDocument*)xsltStylesheet;
Availability: BaseAdditions 0.0.0
Performs an XSLT transformation on the current document using the supplied stylesheet.
Returns an autoreleased GSXMLDocument containing the transformed XML, or nil
on failure.
- (
GSXMLDocument*)
xsltTransform: (
GSXMLDocument*)xsltStylesheet
params: (NSDictionary*)params;
Availability: BaseAdditions 0.0.0
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
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
- (void)
completedXMLRPC: (
GSXMLRPC*)sender;
Availability: BaseAdditions 0.0.0
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.
- Declared in:
- GNUstepBase/GSXML.h
Availability: BaseAdditions 0.0.0
Convenience methods for managing XML escape sequences in an NSString.
Method summary
- (NSString*)
stringByEscapingXML;
Availability: BaseAdditions 0.0.0
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.
- (NSString*)
stringByUnescapingXML;
Availability: BaseAdditions 0.0.0
Deals with standard XML internal entities.
Converts the five XML escape sequences ('>', '<', '&', ''' and '"') 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