PackageDescription: XtreamsDevelopment(Bundle)


Xtreams Development

Last published: November 2, 2011 by 'mkobetic'

This is the development bundle for the Xtreams packages. There is also project website at http://code.google.com/p/xtreams/.

TODO
- mk Ensure that recycled buffers are not shared between streams

FUTURE ENHANCEMENTS
* positioning sent to a non-positionable stream becomes relative to the position of the Position*Stream at the time of positioning. Should this be the same behavior for streams that are self-positioning, eg: #positioning always takes a "snapshot" of the position so that positioning always becomes relative.
* matching: for regex which will slice
Matching is not the same as ending, because it will consume characters off the stream while ever the regex pattern is matching. The result is a stream of streams over the data, because we will always run in "global /g" mode. We'd like to be able to have the non-greedy ? syntax which is supported by java, perl, python, etc (and is part of the regex standard now) which is not in Regex11. The greedy version is possibly likely to read the entire stream on the first read (eg: '.*hello') and that needs to be explained in the documentation (greedy vs non-greedy vs possessive).
stream := 'aaaabcaabcaaa' reading.
(stream matching: '.*abc' asRegex) get rest -> 'aaaabcaabc'; get rest -> 'aaa'
(stream matching: '.*?abc' asRegex) get rest -> 'aaaabc'; get rest -> 'aabc'; get rest -> 'aaa'
* xml parser (sax/dom?)
* wrapping an xtream as a smalltalk-80 stream


PROJECT CONVENTIONS

API SELECTORS
One of the unstated goals is to have our APIs be as unbumpy as possible.

COMMENTS
Rules for commenting packages:
a) The package comment is an introductory text that should provide good overview of what the package provides, including examples. Some overlap with class and method comments is likely.
b) At the moment we're trying to use wiki-style markup (using the google wiki conventions), to allow using the package comments as wiki pages on the project site

To update the doc pages on the project site from current version of package comments (you need 'mercurial' DVCS installed):
# clone the wiki project to a local directory, e.g. ./wiki (see the Sources>Wiki page for more details):
hg clone https://wiki.xtreams.googlecode.com/hg/ wiki
# regenerate the pages in the local directory
PEG.WikiGenerator generateWikiDocsInto: 'wiki' asFilename
# commit the changes
hg commit
# push the changes back to the site
hg push
For next update it is not necessary to clone the project again, just pull new changes into the existing clone
hg pull

Rules for commenting classes:
a) All classes are commented
b) Standard Cincom Smalltalk commenting conventions

Rules for commenting methods:
a) Only comment public API
b) Each comment section in its own comment
c) First comment, tabbed in, describes the method
d) Second comment, tabbed in, describes the types (return self is implicit and not included in the types)
e) Further comment*, examples - one example per comment
f) Final comment*, implementation details