<commit_before>RFC 0179: Add stream support to XML parser
========================================================================
$Id$

@authors: friebe
@created: Sun Feb 15 21:42:40     2009
@status: discussion, ends Sat Mon 18 18:21:18     2009
@category: xml.parser

Scope of Change
---------------
The xml.parser.XMLParser class will support parsing streams.


Rationale
---------
Not having to load file contents into memory completely before being
ablt to parse them.


Functionality
-------------
The <tt>xml.parser.XMLParser::parse()</tt> method will be changed to accept 
either strings (as it does now) or <tt>xml.parser.InputSource</tt> objects.

Current API
~~~~~~~~~~~
This shows that before parsing XML, it needs to be loaded into a string.
This may be best for small files but will create memory problems when
the file size increases:

<code>
  $xml= FileUtil::getContents(new File('example.xml'));
  
  $parser= new XMLParser();
  $parser->parse($xml);
</code>


New API
~~~~~~~
Here, the parsing is done while loading the file from the stream. Also,
because FileInputStream can easily be substituted for any other input
stream, it's more flexible.

<code>
  $parser= new XMLParser();
  $parser->parse(new InputSource(new FileInputStream(new File('example.xml'))));
</code>


Security considerations
-----------------------
None.


Speed impact
------------
Faster for the stream case.


Dependencies
------------
None, the old behaviour of passing a string to <tt>parse()</tt> will be 
kept.


Related documents
-----------------
http://xp-framework.net/rfc/contrib/rfc0179.diff

Comments
--------
friebe, Sun Feb 15 21:45:00     2009
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Not sure whether it wouldn't be more elegant if the InputSource class
was an interface, and instead of an if/else on types in the constructor, 
different implementations of it were shipped.

Examples:
<code>
  $parser->parse(new StringInputSource($xml));
  $parser->parse(new FileInputSource(new File('example.xml')));
  $parser->parse(new StreamInputSource(new FileInputStream(new File('example.xml'))));
</code>

<EOF>
<commit_msg>- Decide in favor of the interface approach.<commit_after>RFC 0179: Add stream support to XML parser
========================================================================
$Id$

@authors: friebe
@created: Sun Feb 15 21:42:40     2009
@status: discussion, ends Sat Mon 18 18:21:18     2009
@category: xml.parser

Scope of Change
---------------
The xml.parser.XMLParser class will support parsing streams.


Rationale
---------
Not having to load file contents into memory completely before being
ablt to parse them.


Functionality
-------------
The <tt>xml.parser.XMLParser::parse()</tt> method will be changed to accept 
either strings (as it does now) or <tt>xml.parser.InputSource</tt> objects.

Current API
~~~~~~~~~~~
This shows that before parsing XML, it needs to be loaded into a string.
This may be best for small files but will create memory problems when
the file size increases:

<code>
  $xml= FileUtil::getContents(new File('example.xml'));
  
  $parser= new XMLParser();
  $parser->parse($xml);
</code>


New API
~~~~~~~
Here, the parsing is done while loading the file from the stream. Also,
because FileInputStream can easily be substituted for any other input
stream, it's more flexible.

<code>
  $parser= new XMLParser();
  $parser->parse(new FileInputSource(new File('example.xml')));
</code>

More examples:
<code>
  $parser->parse(new StringInputSource($xml));
  $parser->parse(new FileInputSource(new File('example.xml')));
  $parser->parse(new StreamInputSource(new FileInputStream(new File('example.xml'))));
</code>



Security considerations
-----------------------
None.


Speed impact
------------
Faster for the stream case.


Dependencies
------------
None, the old behaviour of passing a string to <tt>parse()</tt> will be 
kept.


Related documents
-----------------
http://xp-framework.net/rfc/contrib/rfc0179.diff

Comments
--------
friebe, Sun Feb 15 21:45:00     2009
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Not sure whether it wouldn't be more elegant if the InputSource class
was an interface, and instead of an if/else on types in the constructor, 
different implementations of it were shipped.

Examples:
<code>
  $parser->parse(new StringInputSource($xml));
  $parser->parse(new FileInputSource(new File('example.xml')));
  $parser->parse(new StreamInputSource(new FileInputStream(new File('example.xml'))));
</code>

friebe, Wed May 20 09:50:24     2009
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Decided in favor of the interface approach.

<EOF>

{'fraction_non_alphanumeric': 0.19852462573226295, 'fraction_numerical': 0.02169668040789759, 'mean_word_length': 3.8526315789473684, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 44, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 25}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3575655', 'n_tokens_mistral': 1381, 'n_tokens_neox': 1242, 'n_words': 490}