auntie

$3


!NODE VERSION



> __Auntie__, _my dear_ __ultra-fast__ module for __untying/splitting/counting__
> a stream of data by a __chosen separator sequence__.

> It uses __Bop__ under the hood, a _Boyer-Moore_ parser,
> optimized for sequence lengths up to 255 bytes.

$3

- __Install__
- __Run Tests__
- __Run Benchmarks__
- __Constructor__
- __Properties__
- __Methods__
- __count__
- __dist__
- __do__
- __flush__
- __set__
- __comb__
- __Events__
- __Examples__
- __split lines (streaming) from a CSV file__
- __count lines from a file__
- __snap event and collect__
- __ToDo__
- __MIT License__

------------------------------------------------------------------------------

$3

``bash
$ npm install auntie [-g]
`

> __require__:

`javascript
const Auntie = require( 'auntie' );
`

$3

> __to run all test files, install devDependencies:__

`bash
$ cd auntie/
# install or update devDependencies
$ npm install
# run tests
$ npm test
`

> __to execute a single test file, simply do__:

`bash
$ node test/file-name.js
`

> __output example and running time__:

`bash
...
- current path is 'test'.
- time elapsed: 106.596 secs.

26 test files were loaded.
26 test files were launched.
1272671 assertions succeeded.
`


$3

`bash
$ cd auntie/
$ npm run bench
`

> __to execute a single bench file, simply do__:

`bash
$ node bench/file-name.js
`

------------------------------------------------------------------------------

$3

> Arguments between [ ] are optional.

`javascript
Auntie( [ Buffer | String | Number sequence ] )
`
> or
`javascript
new Auntie( [ Buffer | String | Number sequence ] )
`
> __NOTE__: default is the CRLF sequence \r\n.

$3

> __NOTE__: do not mess up with these properties.

##### The current sequence for splitting data
`javascript
Auntie.seq : Buffer
`

##### the Boyer-Moore parser, under the hood.
`javascript
Auntie.bop : Bop
`

##### a Boyer-Moore parser, to search for generic (sub)sequences
`javascript
Auntie.gbop : Bop
`

##### the remaining data, without any match found.
`javascript
Auntie.snip : Buffer
`

##### the remaining data, used for counting.
`javascript
Auntie.csnip : Buffer
`

##### the current number of matches, min/max distance, remaining bytes.
`javascript
Auntie.cnt : Array
`

------------------------------------------------------------------------------

$3

| name | description |
|:--------------------------|:---------------------------------------------------------------------------------|
| __count__ | count (only) how many times the sequence appears in the current data. |
| __dist__ | count occurrences, min and max distance between sequences and remaining bytes. |
| __do__ | split data or a stream of data by the current sequence. |
| __flush__ | flush the remaining data, resetting internal state/counters. |
| __set__ | set a new sequence for splitting data. |
| __comb__ | search a char or a sequence into the current data. |

> Arguments between [ ] are optional.

#### Auntie.count
> ##### the fastest/lightest way to count how many times the sequence appears in the current data.
`javascript
/*
* it returns an Array with the current number of occurrences.
*
* NOTE: it saves the minimum necessary data that does not contains
* the sequence, for the next #count call with fresh data (to check
* for single occurrences between 2 chunks of data.
*/
'count' : function ( Buffer data ) : Array
`

#### Auntie.dist
> ##### count occurrences, min and max distance between sequences and remaining bytes.
`javascript
/*
* it returns an Array with:
* - the current number of occurrences
* - the minimum distance, in bytes, between any 2 sequences
* - the maximum distance, in bytes, between any 2 sequences
* - the remaining bytes to the end of data (without any matching sequence)
*
* NOTE:
* - also the distance from index 0 to the first match will be considered
* - it saves the remaining data that does not contains the sequence,
* for the next #dist call with fresh data, to check for occurrences
* between chunks).
*/
'dist' : function ( Buffer data ) : Array
`

#### Auntie.do
> ##### split data or a stream of data by the current sequence
`javascript
/*
* if collect is true, it returns an Array of data slices; otherwise, it
* emits a 'snap' event for every slice; then, after having finished to
* parse data, it emits a 'snip' event, with the remaining data that does
* not contain the sequence ( the current Auntie.snip property ).
*
* NOTE: it saves the remaining data that does not contains the
* sequence, for the next #do call on fresh data (to check for
* occurrences between chunks).
*/
'do' : function ( Buffer data [, Boolean collect ] ) : [ Array ]
`

#### Auntie.flush
> ##### flush the remaining data, resetting internal state/counters
`javascript
/*
* if collect is true it returns a Buffer, otherwise it emits
* a 'snip' event with data. Obviously the snip doesn't contain
* the sequence (no match). It is equal to get and reset the
* internal me.snip property.
*/
'flush' : function ( [ Boolean collect ] ) : [ Buffer ]
`

#### Auntie.set
> ##### set a new sequence for splitting data.
`javascript
// default sequence is '\r\n' or CRLF sequence.
'set' : function ( [ Buffer | String | Number sequence ] ) : Auntie
`

#### Auntie.comb
> ##### search for a char or a sequence into the current data.
`javascript
/*
* parse current data for a generic sequence. It returns an Array of indexes.
* NOTE: it doesn't affect the current streaming parser and it doesn't save
* any data. It simply parses a chunk of data for the specified sequence,
* optionally from a starting index and limiting results to a specified number
* of occurrences (like Bop.parse does).
*/
'comb' : function ( Buffer | String seq, Buffer data [, Number from [, Number limit ] ] ) : Array
`

------------------------------------------------------------------------------

$3

> Auntie emits only __2__ types of events: __snap__ and __snip__.

##### !snap a result.
`javascript
'snap' : function ( Buffer result )
`

##### !snip current remaining data (with no match found).
`javascript
'snip' : function ( Buffer result )
``

> __NOTE__: if the '_collect_' switch for the __do__/__flush__ was set (true),
> then no event will be emitted.

------------------------------------------------------------------------------

$3

#### split lines from a CSV file (CRLF):

> - __do, comb: streaming data__

#### count lines from a file (CRLF):

> - __count: sync load__
> - __dist: sync load__
> - __count: streaming data__
> - __dist: streaming data__

#### snap event and collect (CRLF):

> - __do snap: streaming data__
> - __do collect: streaming data__

> See __ All examples__.

$3

> Copyright (c) 2017-present < Guglielmo Ferri : 44gatti@gmail.com >

> Permission is hereby granted, free of charge, to any person obtaining
> a copy of this software and associated documentation files (the
> 'Software'), to deal in the Software without restriction, including
> without limitation the rights to use, copy, modify, merge, publish,
> distribute, sublicense, and/or sell copies of the Software, and to
> permit persons to whom the Software is furnished to do so, subject to
> the following conditions:

> __The above copyright notice and this permission notice shall be
> included in all copies or substantial portions of the Software.__

> THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.