Atok is a fast, easy and dynamic tokenizer designed for use with node.js. It is based around the Stream concept and is implemented as a read/write one.
It was originally inspired by node-tokenizer, but quickly grew into its own form as I wanted it to be RegExp agnostic so it could be used on node Buffer intances and more importantly faster.
Atok is built using ekam as it abuses includes and dynamic method generation.
Atok is the fundation for the atok-parser, which provides the environment for quickly building efficient and easier to maintain parsers.
First let's see some definitions. In atok's terms:
- a
subrule
is an atomic check against the current data. It can be represented by a user defined function (rarely), a string or a number, or an array of those, as well as specific objects defining a range of values for instance (e.g. { start: 'a', end: 'z' } is equivalent to /[a-z]/ in RegExp) - a
rule
is an ordered combination of subrules. Each subrule is evaluated in order and if any fails, the whole rule is considered failed. If all of them are valid, then the handler supplied at rule instanciation is triggered, or if none was supplied, a data event is emitted instead. - a
ruleSet
is a list ofrules
that are saved under a given name. UsingruleSets
is useful when writting a parser to break down its complexity into smaller, easier to solve chunks. RuleSets can be created or altered on the fly by any of its handlers. - a
property
is an option applicable to the current rules being created.- properties are set using their own methods. For instance, a
rule
may load a differentruleSet
upon match usingnext()
- properties are defined before the rules they need to be applied to. E.g. atok.next('rules2').addRule(...)
- once defined, properties are applied to all subsequent rules, unless turned off by calling the property method with no argument or false. E.g. in atok.next('rules2').addRule(...).addRule(...).next().addRule(...) only rule 1 and 2 will load the
ruleSet
rules2 if they match.
- properties are set using their own methods. For instance, a
The default workflow in atok is as follow:
- data is provided to the tokenizer
- the tokenizer evaluates each of its
rules
against it (its currentruleSet
)- if none match, it stops and waits for more
- if one matches, it triggers the handler/emit an event, then go back to rules evaluation
The default workflow can be altered using the continue()
and next()
property methods:
continue(jump[, jumpOnFail])
: the nextrule
being checked is relative to the one that matched, downward if jump value is positive, upward if negative. In case therule
fails, by default, the tokenizer will process to the next one. This can be modified by specifying the jumpOnFail value.continue(0)
: go to the nextrule
on successcontinue(-1)
: reevaluate the currentrule
on successcontinue(-2)
: go to the previousrule
on success
next(ruleSet[, index])
: when the handler returns, the tokenizer will evaluate rules from the newruleSet
, starting at the first one or the one at index.
It is important to note that the tokenizer is highly dynamic:
ruleSets
can be changed by handlersrules
andruleSets
can be created by handlers based on the data being processed- after a match, the tokenizer can branch to a different
ruleSet
Atok is published on node package manager (npm). To install, do:
npm install atok
Given the following json to be parsed:
["Hello world!"]
The following code would be a very simple JSON parser for it.
var Tokenizer = require('atok')
var tok = new Tokenizer
// Define the parser rules
// By default it will emit data events when a rule is matched
tok
// Define the quiet property for the following rules (quiet=dont tokenize but emit/trigger the handler)
// Only used to improve performance
.quiet(true)
// first argument is a match on the current position in the buffer
.addRule('[', 'array-start')
.addRule(']', 'array-end')
.quiet() // Turn the quiet property off
// The second pattern will only match if it is not escaped (default escape character=\)
.escaped(true)
.addRule('"', '"', 'string')
.escaped()
// Array item separator
.addRule(',', 'separator')
// Skip the match, in this case whitespaces
.ignore(true)
.addRule([' ','\n', '\t','\r'], 'whitespaces')
.ignore()
// Setup some variables
var stack = []
var inArray = false
// Attach listeners to the tokenizer
tok.on('data', function (token, idx, type) {
// token=the matched data
// idx=when using array of patterns, the index of the matched pattern
// type=string identifiers used in the rule definition
switch (type) {
case 'array-start':
stack.push([])
inArray = true
break
case 'array-end':
inArray = false
break
case 'string':
if (inArray)
stack[ stack.length-1 ].push(token)
else
throw new Error('only Arrays supported')
break
case 'separator':
break
default:
throw new Error('Unknown type: ' + type)
}
})
tok.on('end', function () {
console.log('results is of type', typeof stack[0], 'with', stack[0].length, 'item(s)')
console.log('results:', stack[0])
})
// Send some data to be parsed!
tok.end('[ "Hello", "world!" ]')
Output
results is object with 1 item(s)
results: [ 'Hello world!' ]
See here.
Atok has a fairly extended set of tests written for mocha. See the test directory.
See the TODO file.
MIT Here