Interface: module:br/parsing/Parser

module:br/parsing/Parser

Parsers allow you to convert arbitrary user-input into some normalized form, and so provide additional flexibility to the end-user as to how data entry is performed. Parsers can be designed to work in co-operation with each other, allowing complex user input to be normalized using a series of progressive transformations. For example, the input -(3 + (4 * 5) + 2) could be normalized to -25 via the following steps: -(3 + (4 * 5) + 2) -> -(3 + (20) + 2) (operator-parser) -(3 + (20) + 2) -> -(3 + 20 + 2) (bracket-parser) -(3 + 20 + 2) -> -(23 + 2) (operator-parser) -(23 + 2) -> -(25) (operator-parser) -(25) -> -25 (bracket-parser) Notice here how the input is slowly transformed into it's a final value by repeatedly applying a couple of simple parser transformations, and that parsing only stops when none of the parsers are able to further simplify the input text. For this to work, parsers must obey the following two rules: 1. A parser's output must be closer to normal form than it's input. 2. Parsers must be able to disambiguate the meaning of the text they are parsing (e.g. whether '12/01/2000' is the UK date "12th of January, 2000" or the US date "December the 1st, 2000"?).
This is an interface and should not be constructed.
Implementations:
Source:

Methods

isSingleUseParser()

Allows parsers that should only run a single time, and that should not repeatedly re-parse their own output.

This method is optional. Parsers that don't implement it are not considered to be single-use parsers by default.

Implementations:
Source:

parse(sValue, mAttributes)

Parses a value and either returns the parsed value upon success, otherwise returns null.
Parameters:
Name Type Description
sValue String the unparsed value. May be null.
mAttributes Object the attributes appropriate to the Parser implementation.
Implementations:
Source:
Returns:
the parsed value, or null if the value was not recognised.