home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / share / doc / libxml-perl / interface-style.pod < prev    next >
Encoding:
Text File  |  1999-05-17  |  2.6 KB  |  80 lines
  1. =head1 Priorities
  2.  
  3. Larry Wall suggests, ``In the absence of other considerations, I'd
  4. encourage you to provide the cleanest interface from the user's
  5. standpoint, and let the implementer worry about the details.''
  6.  
  7. =head1 Naming
  8.  
  9. B<Still Undecided:>
  10.  
  11. All method names use lower-case, `C<_>' seperated names.
  12.  
  13. B<or>
  14.  
  15. All method names match their Java counterparts.
  16.  
  17. All options, parameters, and property names use mixed case names, with
  18. an initial upper case character.  This eliminates a certain amount of
  19. potential confusion with reserved words, which, for the most part, are
  20. lower case.
  21.  
  22. The following words are abbreviated in method names and parameters:
  23.  
  24.  Declaration     decl     Decl
  25.  Reference       ref      Ref
  26.  Identifier      id       Id
  27.  
  28. =head1 Object Instantiation and Options
  29.  
  30. For creating new parser or handler objects, the `new' methods accept a
  31. list of key-value pairs (C<=E<gt>>) or a hash containing the options.
  32. The key names are derived from the SAX positional parameter names
  33. (`C<Source>' and `C<SystemId>' in Parser's `C<parse()>') or the name of
  34. option setting methods (`C<DocumentHandler>', `C<DTDHandler>',
  35. `C<EntityResolver>', `C<ErrorHandler>', and `C<Locale>' in Parser).
  36.  
  37. Callers may get and set options directly in the object, for example:
  38.  
  39.     $parser = SAX::Parser->new( Source => { ByteStream => $fh },
  40.                                 DocumentHandler => $doc_handler );
  41.  
  42.     $parser->{Locale} = 'el_GR.ISO-8859-7';
  43.  
  44. There are no set/get methods in the Perl SAX API.
  45.  
  46. =head1 Handler Calls
  47.  
  48. Handler calls all take hashes instead of positional parameters.  Key
  49. names are derived from SAX positional parameter names.  This allows
  50. parsers and filters to provide additional parameters if they can or
  51. the user requests it.
  52.  
  53. =head1 Extending Handler Interfaces
  54.  
  55. Developers of event-generators can extend the handler interface as
  56. they need to.  Event-generators that use an extended interface should
  57. accept generator options or use `C<can>' to test whether a handler can
  58. support their extended interface.
  59.  
  60. For example, a C<DocumentHandler> that wants to receive internal
  61. entity events instead of having them resolved and passed in to the
  62. `C<characters>' method would define a `C<internal_entity>' method
  63. and/or set a parser option to pass or not pass internal entity events.
  64.  
  65. =head1 Helper Classes
  66.  
  67. Perl SAX avoids helper classes (like SAXException and InputSource)
  68. where those classes only hold information and have no behavior.  In
  69. those cases, simple hashes are used instead.
  70.  
  71. B<It is still undecided> if these should be implemented anyway for
  72. easier portability.
  73.  
  74. =head1 Contributors
  75.  
  76.  Eduard (Enno) Derksen
  77.  Ken MacLeod
  78.  Eric Prud'hommeaux
  79.  Larry Wall
  80.