Up

# NSXMLParser class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Copyright: (C) 2004 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSXMLParser class
2. Software documentation for the NSObject(NSXMLParserDelegateEventAdditions) category
3. Software documentation for the NSXMLParser(NSXMLParserLocatorAdditions) category
4. Software documentation for the NSXMLParserDelegate protocol

# Software documentation for the NSXMLParser class

## NSXMLParser : NSObject

> Declared in:
>   Foundation/NSXMLParser.h

Availability: MacOS-X 10.3.0
This class is a PRE-ALPHA implementation. You should be prepared to track down and fix bugs and preferably contribute fixes back.
If you don't want to do that, use the GSXMLParser class instead... This NSXMLParser class is implemented as a wrapper round some of the functionality of the more powerful GSXML APIs, and is intended as a MacOSX compatibility feature.

This class implements an event driven parser handling the parsing process by sending messages to a delegate when certain parts of the XML document being parsed are encountered.

To use the class, you create and initialise an instance with a particular XML document, set the delegate of the instance, and send a -parse message to it. The delegate must then make use of the information it receives in the messages it gets from the parser.

The NSObject(NSXMLParserDelegateEventAdditions) informal protocol documents the methods which the delegate object may implement in order to handle the parsing process.

Instance Variables
Method summary

- -columnNumber
- -lineNumber
- -publicID
- -systemID
- -abortParsing
- -delegate
- -initWithContentsOfURL:
- -initWithData:
- -initWithStream:
- -parse
- -parserError
- -setDelegate:
- -setShouldProcessNamespaces:
- -setShouldReportNamespacePrefixes:
- -setShouldResolveExternalEntities:
- -shouldProcessNamespaces
- -shouldReportNamespacePrefixes
- -shouldResolveExternalEntities

### abortParsing

- (void) abortParsing;
Availability: MacOS-X 10.3.0
Terminates the current parse operation and sends an error to the delegate of the parser.

### delegate

- (id) delegate;
Availability: MacOS-X 10.3.0
Returns the delegate previously set using -setDelegate: or `nil` if no delegate is set.

### initWithContentsOfURL:

- (instancetype) initWithContentsOfURL: (NSURL*)anURL;
Availability: MacOS-X 10.3.0
Convenience method fetching data from anURL.

### initWithData:

- (instancetype) initWithData: (NSData*)data;
Availability: MacOS-X 10.3.0
This is a designated initialiser for the class.
Initialises the parser with the specified xml data.

### initWithStream:

- (instancetype) initWithStream: (NSInputStream*)stream;
Availability: MacOS-X 10.3.0
Initialises the parser with the specified input stream.

### parse

- (BOOL) parse;
Availability: MacOS-X 10.3.0
Parses the supplied data and returns `YES` on success, `NO` otherwise.

### parserError

- (NSError*) parserError;
Availability: MacOS-X 10.3.0
Returns the last error produced by parsing (if any).

### setDelegate:

- (void) setDelegate: (id)delegate;
Availability: MacOS-X 10.3.0
Sets the parser delegate (which is not retained).

### setShouldProcessNamespaces:

- (void) setShouldProcessNamespaces: (BOOL)aFlag;
Availability: MacOS-X 10.3.0
Set flag to determine whether the namespaceURI and the qualified name of an element is provided in the [NSObject(NSXMLParserDelegateEventAdditions) -parser:didStartElement:namespaceURI:qualifiedName:attributes:] and [NSObject(NSXMLParserDelegateEventAdditions) -parser:didEndElement:namespaceURI:qualifiedName:] methods.

### setShouldReportNamespacePrefixes:

- (void) setShouldReportNamespacePrefixes: (BOOL)aFlag;
Availability: MacOS-X 10.3.0
Sets a flag to specify whether the parser should call the [NSObject(NSXMLParserDelegateEventAdditions) -parser:didStartMappingPrefix:toURI:] and [NSObject(NSXMLParserDelegateEventAdditions) -parser:didEndMappingPrefix:] delegate methods.

### setShouldResolveExternalEntities:

- (void) setShouldResolveExternalEntities: (BOOL)aFlag;
Availability: MacOS-X 10.3.0
Sets flag to determine if declarations of external entities are reported using [NSObject(NSXMLParserDelegateEventAdditions) -parser:foundExternalEntityDeclarationWithName:publicID:systemID:]

### shouldProcessNamespaces

- (BOOL) shouldProcessNamespaces;
Availability: MacOS-X 10.3.0
Returns the value set by -setShouldProcessNamespaces:

### shouldReportNamespacePrefixes

- (BOOL) shouldReportNamespacePrefixes;
Availability: MacOS-X 10.3.0
Returns the value set by -setShouldReportNamespacePrefixes:

### shouldResolveExternalEntities

- (BOOL) shouldResolveExternalEntities;
Availability: MacOS-X 10.3.0
Returns the value set by -setShouldResolveExternalEntities:

## Instance Variables for NSXMLParser Class

### _handler

@public void* _handler;
Availability: MacOS-X 10.3.0
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.

### _parser

@public void* _parser;
Availability: MacOS-X 10.3.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSObject(NSXMLParserDelegateEventAdditions) category

## NSObject(NSXMLParserDelegateEventAdditions)

> Declared in:
>   Foundation/NSXMLParser.h

Availability: MacOS-X 10.3.0
Description forthcoming.
Method summary

- -parser:didEndElement:namespaceURI:qualifiedName:
- -parser:didEndMappingPrefix:
- -parser:didStartElement:namespaceURI:qualifiedName:attributes:
- -parser:didStartMappingPrefix:toURI:
- -parser:foundAttributeDeclarationWithName:forElement:type:defaultValue:
- -parser:foundCDATA:
- -parser:foundCharacters:
- -parser:foundComment:
- -parser:foundElementDeclarationWithName:model:
- -parser:foundExternalEntityDeclarationWithName:publicID:systemID:
- -parser:foundIgnorableWhitespace:
- -parser:foundInternalEntityDeclarationWithName:value:
- -parser:foundNotationDeclarationWithName:publicID:systemID:
- -parser:foundProcessingInstructionWithTarget:data:
- -parser:foundUnparsedEntityDeclarationWithName:publicID:systemID:notationName:
- -parser:parseErrorOccurred:
- -parser:resolveExternalEntityName:systemID:
- -parser:validationErrorOccurred:
- -parserDidEndDocument:
- -parserDidStartDocument:

### parser: didEndElement: namespaceURI: qualifiedName:

- (void) parser: (NSXMLParser*)aParser didEndElement: (NSString*)anElementName namespaceURI: (NSString*)aNamespaceURI qualifiedName: (NSString*)aQualifierName;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: didEndMappingPrefix:

- (void) parser: (NSXMLParser*)aParser didEndMappingPrefix: (NSString*)aPrefix;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: didStartElement: namespaceURI: qualifiedName: attributes:

- (void) parser: (NSXMLParser*)aParser didStartElement: (NSString*)anElementName namespaceURI: (NSString*)aNamespaceURI qualifiedName: (NSString*)aQualifierName attributes: (NSDictionary*)anAttributeDict;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Called when the start of an element is encountered in the document, this provides the name of the element, a dictionary containing the attributes (if any) and (where namespaces are used) the namespace information for the element.

### parser: didStartMappingPrefix: toURI:

- (void) parser: (NSXMLParser*)aParser didStartMappingPrefix: (NSString*)aPrefix toURI: (NSString*)aNamespaceURI;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundAttributeDeclarationWithName: forElement: type: defaultValue:

- (void) parser: (NSXMLParser*)aParser foundAttributeDeclarationWithName: (NSString*)anAttributeName forElement: (NSString*)anElementName type: (NSString*)aType defaultValue: (NSString*)aDefaultValue;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundCDATA:

- (void) parser: (NSXMLParser*)aParser foundCDATA: (NSData*)aBlock;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundCharacters:

- (void) parser: (NSXMLParser*)aParser foundCharacters: (NSString*)aString;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundComment:

- (void) parser: (NSXMLParser*)aParser foundComment: (NSString*)aComment;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundElementDeclarationWithName: model:

- (void) parser: (NSXMLParser*)aParser foundElementDeclarationWithName: (NSString*)anElementName model: (NSString*)aModel;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundExternalEntityDeclarationWithName: publicID: systemID:

- (void) parser: (NSXMLParser*)aParser foundExternalEntityDeclarationWithName: (NSString*)aName publicID: (NSString*)aPublicID systemID: (NSString*)aSystemID;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundIgnorableWhitespace:

- (void) parser: (NSXMLParser*)aParser foundIgnorableWhitespace: (NSString*)aWhitespaceString;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundInternalEntityDeclarationWithName: value:

- (void) parser: (NSXMLParser*)aParser foundInternalEntityDeclarationWithName: (NSString*)aName value: (NSString*)aValue;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundNotationDeclarationWithName: publicID: systemID:

- (void) parser: (NSXMLParser*)aParser foundNotationDeclarationWithName: (NSString*)aName publicID: (NSString*)aPublicID systemID: (NSString*)aSystemID;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundProcessingInstructionWithTarget: data:

- (void) parser: (NSXMLParser*)aParser foundProcessingInstructionWithTarget: (NSString*)aTarget data: (NSString*)aData;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: foundUnparsedEntityDeclarationWithName: publicID: systemID: notationName:

- (void) parser: (NSXMLParser*)aParser foundUnparsedEntityDeclarationWithName: (NSString*)aName publicID: (NSString*)aPublicID systemID: (NSString*)aSystemID notationName: (NSString*)aNotationName;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: parseErrorOccurred:

- (void) parser: (NSXMLParser*)aParser parseErrorOccurred: (NSError*)anError;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: resolveExternalEntityName: systemID:

- (NSData*) parser: (NSXMLParser*)aParser resolveExternalEntityName: (NSString*)aName systemID: (NSString*)aSystemID;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parser: validationErrorOccurred:

- (void) parser: (NSXMLParser*)aParser validationErrorOccurred: (NSError*)anError;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Description forthcoming.

### parserDidEndDocument:

- (void) parserDidEndDocument: (NSXMLParser*)aParser;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Called when parsing ends.

### parserDidStartDocument:

- (void) parserDidStartDocument: (NSXMLParser*)aParser;
Availability: MacOS-X 10.3.0
An empty method provided for subclasses to override.
Called when parsing begins.

# Software documentation for the NSXMLParser(NSXMLParserLocatorAdditions) category

## NSXMLParser(NSXMLParserLocatorAdditions)

> Declared in:
>   Foundation/NSXMLParser.h

Availability: MacOS-X 10.3.0
Description forthcoming.
Method summary

- -columnNumber
- -lineNumber
- -publicID
- -systemID

### columnNumber

- (NSInteger) columnNumber;
Availability: MacOS-X 10.3.0
Returns the current column number of the document being parsed.

### lineNumber

- (NSInteger) lineNumber;
Availability: MacOS-X 10.3.0
Returns the current line number of the document being parsed.

### publicID

- (NSString*) publicID;
Availability: MacOS-X 10.3.0
Returns the public identifier of the external entity in the document being parsed.

### systemID

- (NSString*) systemID;
Availability: MacOS-X 10.3.0
Returns the system identifier of the external entity in the document being parsed.

# Software documentation for the NSXMLParserDelegate protocol

## NSXMLParserDelegate

> Declared in:
>   Foundation/NSXMLParser.h

> Conforms to:
>   NSObject

Availability: MacOS-X 10.3.0
Methods implemented by a delegate in order to make use of the parser.
This is now a formal protocol.
Up