mishel@berest.dp.ua
)rfm@gnu.org
)Copyright: (C) 2000 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
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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.
Create a new SAX handler.
Handle an attribute that has been read by the parser.
An attribute definition has been parsed.
Called when a cdata block has been parsed.
Receiving some chars from the parser.
A comment has been parsed.
An element definition has been parsed.
Called when the document end has been detected.
Called when a closing tag has been processed.
Called when a closing tag has been processed.
An entity definition has been parsed.
Called when an error message needs to be output.
Called when an error message needs to be output.
Called to find out whether there is an external subset.
Called when a fatal error message needs to be output.
Called when a fatal error message needs to be output.
get an entity by name
get a parameter entity by name
An old global namespace has been parsed.
Called to find out whether there is an external subset.
Called to find out whether there is an internal subset.
Receiving some ignorable whitespaces from the parser.
Called to find out whether there is an internal subset.
Called to detemrine if the document is standalone.
Returns a pointer to the raw libxml data used by
this document.
Only for use by libxml experts!
Called to return the filename from which an entity should be loaded.
An old global namespace has been parsed.
What to do when a notation declaration has been parsed.
Return the parser object with which this handler is associated. This may occasionally be useful.
A processing instruction has been parsed.
Called when an entity reference is detected.
Called when the document starts being processed.
Called when an opening tag has been processed.
Description forthcoming.
What to do when an unparsed entity declaration is parsed.
Called when a warning message needs to be output.
Called when a warning message needs to be output.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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 summaryReturns the string value of the attribute.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSCopying
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
A GSXML document wraps the document structure of the underlying libxml library.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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"];
Returns a string representation of the document (ie
the XML) or nil
if the document does not
have reasonable contents.
Returns the name of the encoding for this document.
Returns a pointer to the raw libxml data used by
this document.
Only for use by libxml experts!
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];
Returns the root node of the document.
Sets the root node of the document.
Returns the version string for this document.
Uses the -description method to produce a string representation of the document and writes that to filename.
Uses the -description method to produce a string representation of the document and writes that to url.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSCopying
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
A GSXMLNamespace object wraps part of the document structure of the underlying libxml library.
Description forthcoming.
Description forthcoming.
Return the string representation of the specified numeric type.
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 -
Returns the namespace reference
Returns a pointer to the raw libxml data used by
this document.
Only for use by libxml experts!
return the next namespace.
Return the namespace prefix.
Return type of namespace
Return string representation of the type of the namespace.
- Declared in:
- GNUstepBase/GSXML.h
- Conforms to:
- NSCopying
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
A GSXMLNode object wraps part of the document structure of the underlying libxml library. It may have a parent, siblings, and children.
Description forthcoming.
Description forthcoming.
Return the string constant value for the node type given.
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 -
Return attributes and values as a dictionary
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.
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.
Return the document in which this node exists.
This performs the same function as the
-content
method, but retains the standard five entities
(<, >, ', ", and
&) which are normally replaced with
their standard equivalents (<, >, ',
", and &).
Return the first attribute in this node.
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; }
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.
Convenience method, equivalent to calling -type and comparing it with the result of passing "XML_ELEMENT_NODE" to +typeFromDescription: (but faster).
Convenience method, equivalent to calling -type and comparing it with the result of passing "XML_TEXT_NODE" to +typeFromDescription: (but faster).
Returns a pointer to the raw libxml data used by
this document.
Only for use by libxml experts!
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.
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];
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 "];
Create a namespace attached to this node.
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"];
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 "];
Return the node-name
Return the namespace of the node.
Return namespace definitions for the node
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.
Returns the next element node, skipping past any
oyther 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.
Return the attribute value for the specified key.
Return the parent of this node.
Return the previous node at this level.
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.
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.
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.
Set (or reset) an attribute carried by a node.
[n1 setObject: @"prop1" forKey: @"name1"]; [n1 setObject: @"prop2" forKey: @"name2"]; [n1 setObject: @"prop3" forKey: @"name3"];
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.
Return node type as a string.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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.
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
.
Creation of a new Parser (for incremental parsing) by calling -initWithSAXHandler:
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"); }
Creation of a new Parser by calling -initWithSAXHandler:withContentsOfURL:
Creation of a new Parser by calling -initWithSAXHandler:withData:
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.
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);
Creation of a new Parser by calling -initWithSAXHandler:withContentsOfURL:
Creation of a new Parser by calling -initWithSAXHandler:withData:
Return the name of the string encoding (for XML) to use for the specified OpenStep encoding.
If executed during a parse operation, returns the current column number.
Sets whether the document needs to be validated.
Return the document produced as a result of parsing data.
Return error code for last parse operation.
Sets whether warnings are generated.
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.
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.
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.
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.
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.
If executed during a parse operation, returns the current line number.
Returns the string into which warning and error
messages are saved, or nil
if they
are being written to stderr.
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"); }
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.
Return the public ID of the document being parsed.
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.
Set and return the previous value for entity support. Initially the parser always keeps entity references instead of substituting entity values in the output.
Return the system ID of the document being parsed.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
For XPath queries returning true/false.
Method summaryReturns the the value of the receiver... YES/NO, true/false.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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"); }
Description forthcoming.
Description forthcoming.
Evaluates the supplied expression and returns the
resulting node or node set. If the expression is
invalid, returns nil
.
Initialises the receiver as an xpath parser for the supplied document.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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.
Returns the number of nodes in the receiver.
Deprecated
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
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
For XPath queries returning a number.
Method summaryReturns the floating point (double) value of the receiver.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
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.
Description forthcoming.
Description forthcoming.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
For XPath queries returning a string.
Method summaryReturns the string value of the receiver.
- Declared in:
- GNUstepBase/GSXML.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Description forthcoming.
Method summary
Performs an XSLT transformation on the specified
file using the stylesheet provided.
Returns an
autoreleased GSXMLDocument containing the
transformed XML, or nil
on
failure.
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.
Performs an XSLT transformation on the specified
file using the stylesheet provided.
Returns an
autoreleased GSXMLDocument containing the
transformed XML, or nil
on
failure.
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.
Performs an XSLT transformation on the current
document using the supplied stylesheet.
Returns an autoreleased GSXMLDocument containing
the transformed XML, or nil
on failure.
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.