mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-26 18:21:04 +00:00
0a86bba7b0
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9698 72102866-910b-0410-8b05-ffd578937521
462 lines
13 KiB
HTML
462 lines
13 KiB
HTML
<html><head>
|
|
<title>GSXMLParser</title>
|
|
</head>
|
|
<body>
|
|
<a href ="GSXMLAttribute.html">[Previous] </a>
|
|
<a href ="GSXML.html">[Up] </a>
|
|
<a href ="GSSAXHandler.html">[Next] </a>
|
|
<h1>GSXMLParser</h1>
|
|
<h3>Authors </h3>
|
|
<dl>
|
|
<dt>Michael Pakhantsov
|
|
<dd>
|
|
<dt>Richard Frith-Macdonald
|
|
<dd>
|
|
</dl>
|
|
<p>Version: $Revision$</p>
|
|
<p>Date: $Date$</p>
|
|
<h2><a name ="cont-0">GSXMLParser</a></h2>
|
|
<h2><a name ="GSXMLParser">GSXMLParser</a></h2>
|
|
<p><b>Declared in: </b> GSXML.h</p>
|
|
<p><b>Inherits from: </b> NSObject</p>
|
|
<hr>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
|
|
<h2>Instance Variables </h2>
|
|
<ul>
|
|
</ul>
|
|
<h2>Methods </h2>
|
|
<ul>
|
|
<li ><a href ="GSXMLParser.html#method-0">+loadEntity:at:</a>
|
|
<li ><a href ="GSXMLParser.html#method-1">+parser</a>
|
|
<li ><a href ="GSXMLParser.html#method-2">+parserWithContentsOfFile:</a>
|
|
<li ><a href ="GSXMLParser.html#method-4">+parserWithContentsOfURL:</a>
|
|
<li ><a href ="GSXMLParser.html#method-5">+parserWithData:</a>
|
|
<li ><a href ="GSXMLParser.html#method-6">+parserWithSAXHandler:</a>
|
|
<li ><a href ="GSXMLParser.html#method-7">+parserWithSAXHandler:withContentsOfFile:</a>
|
|
<li ><a href ="GSXMLParser.html#method-9">+parserWithSAXHandler:withContentsOfURL:</a>
|
|
<li ><a href ="GSXMLParser.html#method-10">+parserWithSAXHandler:withData:</a>
|
|
<li ><a href ="GSXMLParser.html#method-11">+xmlEncodingStringForStringEncoding:</a>
|
|
<li ><a href ="GSXMLParser.html#method-25">-doValidityChecking:</a>
|
|
<li ><a href ="GSXMLParser.html#method-17">-doc</a>
|
|
<li ><a href ="GSXMLParser.html#method-26">-errNo</a>
|
|
<li ><a href ="GSXMLParser.html#method-24">-getWarnings:</a>
|
|
<li ><a href ="GSXMLParser.html#method-12">-initWithSAXHandler:</a>
|
|
<li ><a href ="GSXMLParser.html#method-13">-initWithSAXHandler:withContentsOfFile:</a>
|
|
<li ><a href ="GSXMLParser.html#method-14">-initWithSAXHandler:withContentsOfURL:</a>
|
|
<li ><a href ="GSXMLParser.html#method-15">-initWithSAXHandler:withData:</a>
|
|
<li ><a href ="GSXMLParser.html#method-23">-keepBlanks:</a>
|
|
<li ><a href ="GSXMLParser.html#method-16">-lib</a>
|
|
<li ><a href ="GSXMLParser.html#method-18">-parse</a>
|
|
<li ><a href ="GSXMLParser.html#method-20">-parse:</a>
|
|
<li ><a href ="GSXMLParser.html#method-22">-substituteEntites:</a>
|
|
</ul>
|
|
<hr><h2>Class Methods </h2>
|
|
<h3><a name ="method-0">loadEntity:at:</a></h3>
|
|
+ (NSString*) <b>loadEntity:</b> (NSString*)publicID <b>at:</b> (NSString*)locationURL;<br>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-1">parser</a></h3>
|
|
+ (GSXMLParser*) <b>parser</b>;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser (for incremental parsing)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-2">parserWithContentsOfFile:</a></h3>
|
|
+ (GSXMLParser*) <b>parserWithContentsOfFile:</b> (NSString*)path;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfFile:
|
|
</p>
|
|
|
|
<a name ="label-3">example </a>
|
|
<pre>
|
|
|
|
GSXMLParser *p = [GSXMLParser parserWithContentsOfFile: @"macos.xml"];
|
|
|
|
if ([p parse])
|
|
{
|
|
[[p doc] dump];
|
|
}
|
|
else
|
|
{
|
|
printf("error parse file\n");
|
|
}
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-4">parserWithContentsOfURL:</a></h3>
|
|
+ (GSXMLParser*) <b>parserWithContentsOfURL:</b> (NSURL*)url;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfURL:
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-5">parserWithData:</a></h3>
|
|
+ (GSXMLParser*) <b>parserWithData:</b> (NSData*)data;<br>
|
|
|
|
<p>
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withData:
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-6">parserWithSAXHandler:</a></h3>
|
|
+ (GSXMlParser*) <b>parserWithSAXHandler:</b> (GSSAXHandler*)handler;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser by calling initWithSAXHandler:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-7">parserWithSAXHandler:withContentsOfFile:</a></h3>
|
|
+ (GSXMlParser*) <b>parserWithSAXHandler:</b> (GSSAXHandler*)handler <b>withContentsOfFile:</b> (NSString*)path;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfFile:
|
|
</p>
|
|
|
|
<a name ="label-8">example </a>
|
|
<pre>
|
|
|
|
NSAutoreleasePool *arp = [[NSAutoreleasePool alloc] init];
|
|
GSSAXHandler *h = [GSDebugSAXHandler handler];
|
|
GSXMLParser *p = [GSXMLParser parserWithSAXHandler: h
|
|
withContentsOfFile: @"macos.xml"];
|
|
|
|
if ([p parse])
|
|
{
|
|
printf("ok\n");
|
|
}
|
|
|
|
|
|
[arp release];
|
|
|
|
</pre>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-9">parserWithSAXHandler:withContentsOfURL:</a></h3>
|
|
+ (GSXMlParser*) <b>parserWithSAXHandler:</b> (GSSAXHandler*)handler <b>withContentsOfURL:</b> (NSURL*)url;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withContentsOfURL:
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-10">parserWithSAXHandler:withData:</a></h3>
|
|
+ (GSXMlParser*) <b>parserWithSAXHandler:</b> (GSSAXHandler*)handler <b>withData:</b> (NSData*)data;<br>
|
|
|
|
<p>
|
|
|
|
Creation of a new Parser by calling
|
|
initWithSAXHandler:withData:
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-11">xmlEncodingStringForStringEncoding:</a></h3>
|
|
+ (NSString*) <b>xmlEncodingStringForStringEncoding:</b> (NSStringEncoding)encoding;<br>
|
|
|
|
Return the name of the string encoding (for XML) to use for the
|
|
specified OpenStep encoding.
|
|
|
|
<hr>
|
|
<hr><h2>Instances Methods </h2>
|
|
<h3><a name ="method-12">initWithSAXHandler:</a></h3>
|
|
<b>This is the designated initialiser </b><br>
|
|
- (id) <b>initWithSAXHandler:</b> (GSSAXHandler*)handler;<br>
|
|
|
|
<p>
|
|
|
|
Initialisation of a new Parser with SAX handler (if not nil).
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
|
|
The source for the parsing process is not specified - so
|
|
parsing must be done incrementally by feeding data to the
|
|
parser.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-13">initWithSAXHandler:withContentsOfFile:</a></h3>
|
|
- (id) <b>initWithSAXHandler:</b> (GSSAXHandler*)handler <b>withContentsOfFile:</b> (NSString*)path;<br>
|
|
|
|
<p>
|
|
|
|
Initialisation of a new Parser with SAX handler (if not nil)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-14">initWithSAXHandler:withContentsOfURL:</a></h3>
|
|
- (id) <b>initWithSAXHandler:</b> (GSSAXHandler*)handler <b>withContentsOfURL:</b> (NSURL*)url;<br>
|
|
|
|
<p>
|
|
|
|
Initialisation of a new Parser with SAX handler (if not nil)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-15">initWithSAXHandler:withData:</a></h3>
|
|
- (id) <b>initWithSAXHandler:</b> (GSSAXHandler*)handler <b>withData:</b> (NSData*)data;<br>
|
|
|
|
<p>
|
|
|
|
Initialisation of a new Parser with SAX handler (if not nil)
|
|
by calling initWithSAXHandler:
|
|
</p>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-16">lib</a></h3>
|
|
- (void*) <b>lib</b>;<br>
|
|
|
|
<p>
|
|
Return pointer to xmlParserCtxt structure.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-17">doc</a></h3>
|
|
- (GSXMLDocument*) <b>doc</b>;<br>
|
|
|
|
<p>
|
|
|
|
Return GSXMLDocument object.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-18">parse</a></h3>
|
|
- (BOOL) <b>parse</b>;<br>
|
|
|
|
<p>
|
|
|
|
Parse source. Return YES if parsed, otherwise NO.
|
|
This method should be called once to parse the entire document.
|
|
</p>
|
|
|
|
<a name ="label-19">example </a>
|
|
<pre>
|
|
|
|
GSXMLParser *p = [GSXMLParser parserWithContentsOfFile:@"macos.xml"];
|
|
|
|
if ([p parse])
|
|
{
|
|
[[p doc] dump];
|
|
}
|
|
else
|
|
{
|
|
printf("error parse file\n");
|
|
}
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-20">parse:</a></h3>
|
|
- (BOOL) <b>parse:</b> (NSData*)data;<br>
|
|
|
|
<p>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<a name ="label-21">example </a>
|
|
<pre>
|
|
|
|
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.
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-22">substituteEntites:</a></h3>
|
|
- (BOOL) <b>substituteEntites:</b> (BOOL)yesno;<br>
|
|
|
|
<p>
|
|
|
|
Set and return the previous value for entity support.
|
|
Initially the parser always keeps entity references instead
|
|
of substituting entity values in the output.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-23">keepBlanks:</a></h3>
|
|
- (BOOL) <b>keepBlanks:</b> (BOOL)yesno;<br>
|
|
|
|
<p>
|
|
|
|
Set and return the previous value for blank text nodes support.
|
|
ignorableWhitespace() are only generated when running
|
|
the parser in validating mode and when the current element
|
|
doesn't allow CDATA or mixed content.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-24">getWarnings:</a></h3>
|
|
- (BOOL) <b>getWarnings:</b> (BOOL)yesno;<br>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-25">doValidityChecking:</a></h3>
|
|
- (BOOL) <b>doValidityChecking:</b> (BOOL)yesno;<br>
|
|
|
|
<p>
|
|
|
|
Sets whether the document needs to be validated.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
<h3><a name ="method-26">errNo</a></h3>
|
|
- (int) <b>errNo</b>;<br>
|
|
|
|
<p>
|
|
|
|
Return error code for last parse operation.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
</body>
|
|
|
|
</html>
|