libs-base/Documentation/gsdoc/GSXMLParser.html

435 lines
12 KiB
HTML
Raw Normal View History

<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: 0.1</p>
<p>Date: 15 September, 2000</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">+parser</a>
<li><a href ="GSXMLParser.html#method-1">+parserWithContentsOfFile:</a>
<li><a href ="GSXMLParser.html#method-3">+parserWithContentsOfURL:</a>
<li><a href ="GSXMLParser.html#method-4">+parserWithData:</a>
<li><a href ="GSXMLParser.html#method-5">+parserWithSAXHandler:</a>
<li><a href ="GSXMLParser.html#method-6">+parserWithSAXHandler:withContentsOfFile:</a>
<li><a href ="GSXMLParser.html#method-8">+parserWithSAXHandler:withContentsOfURL:</a>
<li><a href ="GSXMLParser.html#method-9">+parserWithSAXHandler:withData:</a>
<li><a href ="GSXMLParser.html#method-10">+xmlEncodingStringForStringEncoding:</a>
<li><a href ="GSXMLParser.html#method-24">-doValidityChecking:</a>
<li><a href ="GSXMLParser.html#method-16">-doc</a>
<li><a href ="GSXMLParser.html#method-25">-errNo</a>
<li><a href ="GSXMLParser.html#method-23">-getWarnings:</a>
<li><a href ="GSXMLParser.html#method-11">-initWithSAXHandler:</a>
<li><a href ="GSXMLParser.html#method-12">-initWithSAXHandler:withContentsOfFile:</a>
<li><a href ="GSXMLParser.html#method-13">-initWithSAXHandler:withContentsOfURL:</a>
<li><a href ="GSXMLParser.html#method-14">-initWithSAXHandler:withData:</a>
<li><a href ="GSXMLParser.html#method-22">-keepBlanks:</a>
<li><a href ="GSXMLParser.html#method-15">-lib</a>
<li><a href ="GSXMLParser.html#method-17">-parse</a>
<li><a href ="GSXMLParser.html#method-19">-parse:</a>
<li><a href ="GSXMLParser.html#method-26">-setExternalEntityLoader</a>
<li><a href ="GSXMLParser.html#method-21">-substituteEntites:</a>
</ul>
<hr><h2>Class Methods </h2>
<h3><a name ="method-0">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-1">parserWithContentsOfFile:</a></h3>
+ (GSXMLParser*) <b>parserWithContentsOfFile:</b> (NSString*)path;<br>
<p>
Creation of a new Parser by calling
initWithSAXHandler:withContentsOfFile:
</p>
<a name ="label-2">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-3">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-4">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-5">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-6">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-7">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-8">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-9">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-10">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-11">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 incfrementally by feeding data to the
parser.
</p>
<hr>
<h3><a name ="method-12">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-13">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-14">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 a nul terminated XML document),
so parsing of the entire document will be performed rather than
incremental parsing.
</p>
<hr>
<h3><a name ="method-15">lib</a></h3>
- (void*) <b>lib</b>;<br>
<p>
Return pointer to xmlParserCtxt structure.
</p>
<hr>
<h3><a name ="method-16">doc</a></h3>
- (GSXMLDocument*) <b>doc</b>;<br>
<p>
Return GSXMLDocument object.
</p>
<hr>
<h3><a name ="method-17">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 entiore document.
</p>
<a name ="label-18">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-19">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.
Once this has been done, the method may be used again to
parse a new document.
</p>
<a name ="label-20">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]; // Ready to parse another document.
</pre>
<hr>
<h3><a name ="method-21">substituteEntites:</a></h3>
- (BOOL) <b>substituteEntites:</b> (BOOL)yesno;<br>
<p>
Set and return the previous value for default entity support.
Initially the parser always keeps entity references instead
of substituting entity values in the output.
</p>
<hr>
<h3><a name ="method-22">keepBlanks:</a></h3>
- (BOOL) <b>keepBlanks:</b> (BOOL)yesno;<br>
<p>
Set and return the previous value for default blanks
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-23">getWarnings:</a></h3>
- (BOOL) <b>getWarnings:</b> (BOOL)yesno;<br>
<hr>
<h3><a name ="method-24">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-25">errNo</a></h3>
- (int) <b>errNo</b>;<br>
<p>
Return error code.
</p>
<hr>
<h3><a name ="method-26">setExternalEntityLoader</a></h3>
- (void) <b>setExternalEntityLoader</b> (void*)function;<br>
<p>
Set a external entity loader.
</p>
<hr>
</body>
</html>