Class: Rule | CS Parser

Rule(Df)

A nestable parsing rule

Constructor

new Rule(Df)

Creates a rule instance with the options in the specified object.

Parameters:

Name Type Default Description

Df

object

null

The rule definition object that contains the options as its properties. Definition objects can be nested. A nested definition is interpreted as a sub-rule. The property name for a nested definition must start with $ (dollar sign)

Available Options:

Properties

Name Type Default Description

name

string

The name of this rule. Only for debug purpose

from

string | RegExp

The pattern that indicates the begining point of this rule. If the current chunk matched with this pattern, this rule will be activated, and the new context will start parsing from the next chunk

start

Alias of from

to

string | RegExp

The pattern that indicates the end point of this rule. If the current chunk matched with this pattern, this rule will be deactivated, and the current context will be finalized

end

Alias of to

onStart

function

The callback which is called when this rule gets activated.
If this returns false, the Parser will read the current chunk again

Parameters:

Properties

Name	Type	Description
`cx`	Context	The current context
`chunk`	string	The current chunk which has matched with `from`
`matches`	number \| Array.<string>	If the `from` pattern is a string, the index of the matched string in the chunk. If the `from` pattern is a RegExp, the regex matching results array

init

Alias of onStart

onActive

function

The callback which is called for every single chunk.
If this returns false, the Parser will read the current chunk again

Parameters:

Properties

Name	Type	Description
`cx`	Context	The current context
`chunk`	string	The current chunk

parse

Alias of onActive

onEnd

function

The callback which is called when this rule gets deactivated. If this returns false, the Parser will read the current chunk again

Parameters:

Properties

Name	Type	Description
`cx`	Context	The current context
`chunk`	string	The current chunk which has matched with `to`
`matches`	number \| Array.<string>	If the `to` pattern is a string, the index of the matched string in the chunk. If the `to` pattern is a RegExp, the regex matching results array

fin

Alias of onEnd

onOutline

function

Debug purpose only. You can customize the output of Context#outline with this callback

Must Return:

The output string

Parameters:

Properties

Name	Type	Description
`cx`	Context	The context to express

express

Alias of onOutline

on

object

The container for the another aliases of onStart, onActive, onEnd, onOutline

Properties:

Properties

Name	Type	Description
`start`	function	Alias of `onStart`
`active`	function	Alias of `onActive`
`end`	function	Alias of `onEnd`
`outline`	function	Alias of `onOutline`

isRecursive

boolean

false

Whether this rule is recursive

recursive

Alias of isRecursive

recurse

Alias of isRecursive

endsWithParent

boolean

false

If true, the parent rule can end even when this rule is active

splitter

string | RegExp

'\n'

The chunk splitter. When the Parser reached at the chunk splitter, the substring from the previous chunk splitter is passed to the rule as a chunk. The default splitter is a line-break

encoding

string

Rule.INHERIT

The encoding to use for converting the buffer to a chunk string. Falls back to 'utf8'

$any

object

A sub-rule definition. The property name can be any string but must start with $ (dollar sign)

Source:: Rule.js, line 9

Extends

Composite

Members

staticconstantINHERIT Symbol

The enum for rule properties, which means the actual property value inherits from the parent rule

Source:: Rule.js, line 137

readonlyancestors Array.<Composite>

The ancestor composites ordered by closest to furthest

Overrides:: Composite#ancestors
Source:: Composite.js, line 43

encoding string

The encoding to decode buffers. Falls back to 'utf8'

Default Value:: Rule.INHERIT
Source:: Rule.js, line 309

end RegExp

The end pattern

Deprecated:: Use Rule#to instead
Default Value:: null
Source:: Rule.js, line 202

endsWithParent boolean

Whether the current context can also be ended by the parent context rule

Default Value:: false
Source:: Rule.js, line 283

from RegExp

The start pattern

Default Value:: null
Source:: Rule.js, line 159

readonlyhasChild boolean

Whether this has one or more child composites

Overrides:: Composite#hasChild
Source:: Composite.js, line 25

readonlyhasParent boolean

Whether this has parent composite

Overrides:: Composite#hasParent
Source:: Composite.js, line 16

isRecursive boolean

Whether this rule is recursive

Default Value:: false
Source:: Rule.js, line 270

readonlylength number

The number of child composites

Overrides:: Composite#length
Source:: Composite.js, line 69

name string

The name of this rule

Default Value:: ''
Source:: Rule.js, line 146

onActive function

The event handler which is called every time the parser reached at Rule#splitter

Default Value:: null
Source:: Rule.js, line 231

onEnd function

The event handler which is called when this rule is deactivated

Default Value:: null
Source:: Rule.js, line 243

onOutline function

Debug purpose only. The callback which runs when Context#outline is called

Default Value:: null
Source:: Rule.js, line 257

onStart function

The event handler which is called when this rule is activated

Default Value:: null
Source:: Rule.js, line 217

readonlyparent Composite

The parent composite

Overrides:: Composite#parent
Source:: Composite.js, line 34

readonlyroot Composite

The root of composition

Overrides:: Composite#root
Source:: Composite.js, line 58

splitter stringRegExp

The chunk splitter

Default Value:: '\n'
Source:: Rule.js, line 296

start RegExp

The start pattern

Deprecated:: Use Rule#from instead
Default Value:: null
Source:: Rule.js, line 173

to RegExp

The end pattern

Default Value:: null
Source:: Rule.js, line 188

Methods

addChild(Cp) → Composite

Adds a child composite

Parameters:

Name	Type	Description
`Cp`	Composite	The composite to add as a child

Overrides:: Composite#addChild
Source:: Composite.js, line 89

Returns:

This

Type:: Composite

addChildren(Cps) → Composite

Adds multiple child composites

Parameters:

Name	Type	Description
`Cps`	Array.<Composite>	The array of the composites to add

Overrides:: Composite#addChildren
Source:: Composite.js, line 106

Returns:

This

Type:: Composite

endsWith(Chunk) → mixed

Performs matching the specified chunk with the end pattern

Parameters:

Name	Type	Description
`Chunk`	string	The chunk to match

Source:: Rule.js, line 357

Returns:

The matching result

Type:: mixed

express(Cx) → string

Expresses a context. Debug purpose only.

Parameters:

Name	Type	Description
`Cx`	Context	The context to express

Source:: Rule.js, line 480

Returns:

Type:: string

fin(Cx, Chunk, MatchResult) → boolean

Finalizes a context

Parameters:

Name	Type	Default	Description
`Cx`	Context		The context to finalize
`Chunk`	string	''	The chunk that matched with the `end` condition
`MatchResult`	Array.<string>	null	The maching result of the `end` condition

Source:: Rule.js, line 449

Returns:

Result of fin callback. If fin is not specified, true will be returned

Type:: boolean

init(Cx, Chunk, MatchResult) → boolean

Initializes a context

Parameters:

Name	Type	Default	Description
`Cx`	Context		The context to initialize
`Chunk`	string	''	The chunk that matched with the `start` condition
`MatchResult`	Array.<string>	null	The matching result of the `start` condition

Source:: Rule.js, line 431

Returns:

The result of init callback. If init is not specified, true will be returned

Type:: boolean

on(Ev, Fn)

Sets an event handler

Parameters:

Name Type Description

Ev

string

The event identifier

Available Events:

'start': Occurs when the current chunk matched with Rule#from
'active': While this rule is active, occurs every time the parser reached at Rule#splitter
'end': Occurs when the current chunk matched with Rule#to
'outline': Occurs when Context#outline is called. Debug purpose only

Fn

function

The event handler. Returning false makes the parser read the current chunk again

Parameters:

Properties

Name	Type	Description
`cx`	Context	The current context
`chunk`	string	The current chunk. Only for `start`, `active` and `end`
`matches`	number \| Array.<string>	The matching result of Rule#from/Rule#to. Only for `start` and `end` events

Source:: Rule.js, line 409

parse(Cx, Chunk) → boolean

Parses a chunk

Parameters:

Name	Type	Default	Description
`Cx`	Context		The current context
`Chunk`	string	''	The chunk to parse

Source:: Rule.js, line 466

Returns:

The result of parse callback. If parse is not specified, true will be returned

Type:: boolean

startsWith(Chunk) → mixed

Performs matching the specified chunk with the start pattern

Parameters:

Name	Type	Description
`Chunk`	string	The chunk to match

Source:: Rule.js, line 348

Returns:

The matching result

Type:: mixed

traverse(Fn, Depth, Arg) → boolean

Performs tree traversal

Parameters:

Name	Type	Default	Description
`Fn`	function		The callback that receives every descendant composite as the 1st parameter. If `false` is returned, the traversal will be aborted. The returned value other than `false` will be passed to the next traversal call of `Fn` as the 2nd parameter
`Depth`	number	-1	The limit of traversal depth. Negative number means no-limit
`Arg`	mixed	null	Additinal argument to pass to `Fn` as the 2nd parameter.

Overrides:: Composite#traverse
Source:: Composite.js, line 125

Returns:

true if the traversal is successfully completed. false if the traversal is aborted

Type:: boolean

verifyChild(Cp) → booleanstring

Determines whether the specified composite can be added as a child

Parameters:

Name	Type	Description
`Cp`	Composite	The composite which is about to be added

Overrides:: Composite#verifyChild
Source:: Composite.js, line 80

Returns:

true if Cp is valid. Any type other than true means invalid. If a string is returned, it is shown as an error message in the debug console

Type:: boolean | string