190 lines
6.5 KiB
Markdown
190 lines
6.5 KiB
Markdown
|
### Qap
|
|||
|
|
|
|||
|
|
[](https://www.npmjs.org/package/qap)
|
|||
|
|
[](https://www.codacy.com/public/44gatti/qap)
|
|||
|
|
[](https://codeclimate.com/github/rootslab/qap)
|
|||
|
|
[](https://codeclimate.com/github/rootslab/qap)
|
|||
|
|
[](https://github.com/rootslab/qap#mit-license)
|
|||
|
|
|
|||
|
|
[](http://travis-ci.org/rootslab/qap)
|
|||
|
|
[](https://david-dm.org/rootslab/qap)
|
|||
|
|
[](https://david-dm.org/rootslab/qap#info=devDependencies)
|
|||
|
|
[](http://npm-stat.com/charts.html?package=qap)
|
|||
|
|
|
|||
|
|
[](https://nodei.co/npm/qap/)
|
|||
|
|
|
|||
|
|
[](https://nodei.co/npm/qap/)
|
|||
|
|
|
|||
|
|
[](https://sourcegraph.com/github.com/rootslab/qap)
|
|||
|
|
[](https://sourcegraph.com/github.com/rootslab/qap)
|
|||
|
|
[](https://sourcegraph.com/github.com/rootslab/qap)
|
|||
|
|
|
|||
|
|
* __Qap__ is a quick parser for string or buffer patterns.
|
|||
|
|
* It is optimized for using with pattern strings <= 255 bytes.
|
|||
|
|
* Better results are achieved with long and sparse patterns.
|
|||
|
|
* It is an implementation of QuickSearch algorithm.
|
|||
|
|
|
|||
|
|
###Main features
|
|||
|
|
|
|||
|
|
> Given a m-length pattern and n-length data and σ-length alphabet ( σ = 256 ):
|
|||
|
|
|
|||
|
|
- simplification of the Boyer-Moore algorithm ( *see [Bop](https://github.com/rootslab/bop)* ).
|
|||
|
|
- uses only a bad-character shift table.
|
|||
|
|
- preprocessing phase in __O(m+σ)__ time and __O(σ)__ space complexity.
|
|||
|
|
- searching phase in __O(m*n)__ time complexity.
|
|||
|
|
- very fast in practice for short patterns and large alphabets.
|
|||
|
|
|
|||
|
|
> See __[Lecroq](http://www-igm.univ-mlv.fr/~lecroq/string/node19.html)__ for reference and also __[Bop](https://github.com/rootslab/bop)__, a Boyer-Moore parser.
|
|||
|
|
|
|||
|
|
###Install
|
|||
|
|
```bash
|
|||
|
|
$ npm install qap [-g]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> __require__:
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var Qap = require( 'qap' );
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
###Run Tests
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
$cd qap/
|
|||
|
|
$npm test
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
###Run Benchmarks
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
$ cd qap/
|
|||
|
|
$ npm run-script bench
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
###Constructor
|
|||
|
|
|
|||
|
|
> Create an instance with a Buffer or String pattern.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
Qap( Buffer || String pattern )
|
|||
|
|
// or
|
|||
|
|
neq Qap( Buffer || String pattern )
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
###Methods
|
|||
|
|
|
|||
|
|
> List all pattern occurrences into a String or Buffer data.
|
|||
|
|
> It returns a new array of indexes, or populates an array passed as the last argument to parse method.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// slower with String
|
|||
|
|
Qap#parse( String data [, Number startFromIndex [, Number limitResultsTo [, Array array ] ] ] ) : Array
|
|||
|
|
|
|||
|
|
// faster with Buffer
|
|||
|
|
Qap#parse( Buffer data [, Number startFromIndex [, Number limitResultsTo [, Array array ] ] ] ) : Array
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> Change the pattern :
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
Qap#set( Buffer || String pattern ) : Buffer
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
###Usage Example
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var log = console.log
|
|||
|
|
, assert = require( 'assert' )
|
|||
|
|
, Qap = require( 'qap' )
|
|||
|
|
, pattern = 'hellofolks\r\n\r\n'
|
|||
|
|
, text = 'hehe' + pattern +'loremipsumhellofolks\r\n' + pattern
|
|||
|
|
, bresult = null
|
|||
|
|
;
|
|||
|
|
|
|||
|
|
// create an instance and parse the pattern
|
|||
|
|
var qap = Qap( pattern )
|
|||
|
|
// parse data from beginning
|
|||
|
|
, results = qap.parse( text )
|
|||
|
|
;
|
|||
|
|
|
|||
|
|
// set a new Buffer pattern
|
|||
|
|
qap.set( new Buffer( pattern ) );
|
|||
|
|
|
|||
|
|
// parse data uffer instead of a String
|
|||
|
|
bresults = qap.parse( new Buffer( text ) );
|
|||
|
|
|
|||
|
|
// parser results ( starting indexes ) [ 4, 40 ]
|
|||
|
|
log( results, bresults );
|
|||
|
|
|
|||
|
|
// results are the same
|
|||
|
|
assert.deepEqual( results, bresults );
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
####Benchmark for a small pattern ( length <= 255 bytes )
|
|||
|
|
|
|||
|
|
> Parser uses a Buffer 256-bytes long to build the shifting table, then:
|
|||
|
|
|
|||
|
|
> - Pattern parsing / table creation space and time complexity is O(σ).
|
|||
|
|
> - Very low memory footprint.
|
|||
|
|
> - Ultra fast to preprocess pattern ( = table creation ).
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
$ node bench/small-pattern-data-rate
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
for default it:
|
|||
|
|
|
|||
|
|
> - uses a pattern string of 57 bytes/chars
|
|||
|
|
> - builds a data buffer of 700 MB in memory
|
|||
|
|
> - uses a redundancy/distance factor for pattern strings equal to 2. The bigger the value,
|
|||
|
|
the lesser are occurrences of pattern string into the text buffer.
|
|||
|
|
|
|||
|
|
**Custom Usage**:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# with [testBufferSizeInMB] [distanceFactor] [aStringPattern]
|
|||
|
|
$ node bench/small-pattern-data-rate.js 700 4 "that'sallfolks"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
####Benchmark for a big pattern ( length > 255 bytes )
|
|||
|
|
|
|||
|
|
> Parser uses one Array to build the shifting table for a big pattern, then:
|
|||
|
|
|
|||
|
|
> - table has a size of 256 elements, every element is an integer value that
|
|||
|
|
> could be between 0 and the pattern length.
|
|||
|
|
> - Fast to preprocess pattern ( = table creation ).
|
|||
|
|
> - Low memory footprint
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
$ node bench/big-pattern-data-rate
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> - it uses a pattern size of 20MB
|
|||
|
|
> - builds a data buffer of 300MB copying pattern 12 times
|
|||
|
|
|
|||
|
|
See __[bench](./bench)__ dir.
|
|||
|
|
|
|||
|
|
### MIT License
|
|||
|
|
|
|||
|
|
> Copyright (c) 2015 < 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.
|