Priorities

Larry Wall suggests, ``In the absence of other considerations, I'd encourage you to provide the cleanest interface from the user's standpoint, and let the implementer worry about the details.''

Naming

Still Undecided:

All method names use lower-case, `_' seperated names.

or

All method names match their Java counterparts.

All options, parameters, and property names use mixed case names, with an initial upper case character. This eliminates a certain amount of potential confusion with reserved words, which, for the most part, are lower case.

The following words are abbreviated in method names and parameters:

 Declaration     decl     Decl
 Reference       ref      Ref
 Identifier      id       Id

Object Instantiation and Options

For creating new parser or handler objects, the `new' methods accept a list of key-value pairs (=>) or a hash containing the options. The key names are derived from the SAX positional parameter names (`Source' and `SystemId' in Parser's `parse()') or the name of option setting methods (`DocumentHandler', `DTDHandler', `EntityResolver', `ErrorHandler', and `Locale' in Parser).

Callers may get and set options directly in the object, for example:

    $parser = SAX::Parser->new( Source => { ByteStream => $fh },
                                DocumentHandler => $doc_handler );

    $parser->{Locale} = 'el_GR.ISO-8859-7';

There are no set/get methods in the Perl SAX API.

Handler Calls

Handler calls all take hashes instead of positional parameters. Key names are derived from SAX positional parameter names. This allows parsers and filters to provide additional parameters if they can or the user requests it.

Extending Handler Interfaces

Developers of event-generators can extend the handler interface as they need to. Event-generators that use an extended interface should accept generator options or use `can' to test whether a handler can support their extended interface.

For example, a DocumentHandler that wants to receive internal entity events instead of having them resolved and passed in to the `characters' method would define a `internal_entity' method and/or set a parser option to pass or not pass internal entity events.

Helper Classes

Perl SAX avoids helper classes (like SAXException and InputSource) where those classes only hold information and have no behavior. In those cases, simple hashes are used instead.

It is still undecided if these should be implemented anyway for easier portability.

Contributors

 Eduard (Enno) Derksen
 Ken MacLeod
 Eric Prud'hommeaux
 Larry Wall