Decoder | ParTSing

The Decoder class is the base type to implement custom decoders. It has three type parameters:

In for input. The input to a decoder can be any raw value that your decoder can extract information from. In a simple case it could be a string value or an array of bytes. If decoders are chained, the input needs to be transferred from one decoder to the following one. That is why DecodeResult has an Input as well. It is important to notice that what is passed to the next decoder needs to be the relative input and not the original one. For efficiency reasons, most decoders will wrap their own input into some more sophisticated type to allow tracking the current position in the stream.
Out for output. It's the type of the value return by the decoder if it succeeds. Through operations like Decoder.map and Decoder.flatMap, this type can be changed.
Err for error. It's the type of the error message. In some implementations it might be as simple as string. For the embedded decoders (text and value), the error is fixed to the DecodeError unione type. The constructors for DecodeError have more semantic value than strings and can be properly used for localization.

Type parameters

Hierarchy

Decoder

Index

Properties

Methods

Properties

_E

_E: Err

These placeholder (_I, _O, _E) types are not expected to bring any value. They exist to allow inspecting the main types of a Decoder at compile time.

_I

_I: In

See _E.

_O

_O: Out

See _E.

Methods

atLeast

atLeast(times: number): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:225
Expect the current decoder to be repeated at least n times.

The result is an array of Out values.

Parameters
- times: number
Returns Decoder<In, Out[], Err>

atLeastWithSeparator

atLeastWithSeparator<Separator>(times: number, separator: Decoder<In, Separator, Err>): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:296
Given a separator decoder, it returns an array of values from the current decoder. It is expected that at least times values are returned from this decoder.

Type parameters
- Separator
Parameters
- times: number
- separator: Decoder<In, Separator, Err>
Returns Decoder<In, Out[], Err>

atMost

atMost(times: number): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:287
Repeat the current decoder at most n times.

Notice that this allows for zero successes. Which makes this decoder optional.

Parameters
- times: number
Returns Decoder<In, Out[], Err>

atMostWithSeparator

atMostWithSeparator<Separator>(times: number, separator: Decoder<In, Separator, Err>): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:305
Given a separator decoder, it returns an array of values from the current decoder. It is expected that at most times values are returned from this decoder.

Type parameters
- Separator
Parameters
- times: number
- separator: Decoder<In, Separator, Err>
Returns Decoder<In, Out[], Err>

between

between(min: number, max: number): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:252
Repeat the current decoder between min and max times.

Parameters
- min: number
- max: number
Returns Decoder<In, Out[], Err>

betweenWithSeparator

betweenWithSeparator<Separator>(min: number, max: number, separator: Decoder<In, Separator, Err>): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:330
Given a separator decoder, it returns an array of values from the current decoder. It is expected that between min and max values are returned.

Type parameters
- Separator
Parameters
- min: number
- max: number
- separator: Decoder<In, Separator, Err>
Returns Decoder<In, Out[], Err>

flatMap

flatMap<Out2>(fun: function): Decoder<In, Out2, Err>

- Defined in core/decoder.ts:86
flatMap allows to combine the result of a decoder with a new one.

It can be used to conditionally pick the next decoder in a chain based on the result of a previous step.

Type parameters
- Out2
Parameters
- fun: function
  - - (res: Out): Decoder<In, Out2, Err>
    - Parameters
      - res: Out
      Returns Decoder<In, Out2, Err>
Returns Decoder<In, Out2, Err>

flatMapError

flatMapError<Err2>(fun: function): Decoder<In, Out, Err2>

- Defined in core/decoder.ts:153
Like flatMap but for the failure case. It is also useful to recover from an error.

Type parameters
- Err2
Parameters
- fun: function
  - - (res: Err[]): Decoder<In, Out, Err2>
    - Parameters
      - res: Err[]
      Returns Decoder<In, Out, Err2>
Returns Decoder<In, Out, Err2>

join

join<Out2>(next: Decoder<In, Out2, Err>): Decoder<In, [Out, Out2], Err>

- Defined in core/decoder.ts:194
Combines the result of the current decoder with the one in next and returns them as tuple of two if they are both successful.

Type parameters
- Out2
Parameters
- next: Decoder<In, Out2, Err>
Returns Decoder<In, [Out, Out2], Err>

many

many(): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:245
Repeat the current decoder zero or more times.

Returns Decoder<In, Out[], Err>

manyWithSeparator

manyWithSeparator<Separator>(separator: Decoder<In, Separator, Err>): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:313
Given a separator decoder, it returns an array of values from the current decoder. It is expected any number of values returned, even zero.

Type parameters
- Separator
Parameters
- separator: Decoder<In, Separator, Err>
Returns Decoder<In, Out[], Err>

map

map<Out2>(fun: function): Decoder<In, Out2, Err>

- Defined in core/decoder.ts:108
Convert and/or transform the result of a decoding into a different value.

The applied function argument is executed exclusively on a succesful result of decoding.

example
```
regexp(/\d{4}-\d{2}-\d{2}/y).map(Date.parse)
```
Type parameters
- Out2
Parameters
- fun: function
  - - (res: Out): Out2
    - Parameters
      - res: Out
      Returns Out2
Returns Decoder<In, Out2, Err>

mapError

mapError<Err2>(fun: function): Decoder<In, Out, Err2>

- Defined in core/decoder.ts:165
Like map but for the failure case.

Type parameters
- Err2
Parameters
- fun: function
  - - (e: Err): Err2
    - Parameters
      - e: Err
      Returns Err2
Returns Decoder<In, Out, Err2>

mapWithInput

mapWithInput<Out2>(fun: function): Decoder<In, Out2, Err>

- Defined in core/decoder.ts:116
Similar to map but passes a tuple of res: Out and input: In. This is mostly useful when decoding tokens to preserve the original position in the input.

Type parameters
- Out2
Parameters
- fun: function
  - - (res: Out, input: In): Out2
    - Parameters
      - res: Out
      - input: In
      Returns Out2
Returns Decoder<In, Out2, Err>

or

or<U>(...decoders: object): Decoder<In, Out | TupleToUnion<U>, Err>

- Defined in core/decoder.ts:202
If the current decoder fails, it tries the ones passed as arguments until one of them succeeds or they all fail.

Type parameters
- U: any[]
Parameters
- Rest ...decoders: object
Returns Decoder<In, Out | TupleToUnion<U>, Err>

pickNext

pickNext<Out2>(next: Decoder<In, Out2, Err>): Decoder<In, Out2, Err>

- Defined in core/decoder.ts:178
On a successful decoding of the current decoder, it moves to the next one returning only its result.

Type parameters
- Out2
Parameters
- next: Decoder<In, Out2, Err>
Returns Decoder<In, Out2, Err>

probe

probe(f: function): Decoder<In, Out, Err>

- Defined in core/decoder.ts:416
The probe method is used to perform a side-effecty function somewhere in the decoder chain. It is mostly used as a debugging mechanism.

example
```
decoder.probe(console.log).map(v => ...)
```
Parameters
- f: function
  - - (v: DecodeResult<In, Out, Err>): void
    - Parameters
      - v: DecodeResult<In, Out, Err>
      Returns void
Returns Decoder<In, Out, Err>

repeat

repeat(times: number): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:277
Repeat the current decoder exactly n times.

Parameters
- times: number
Returns Decoder<In, Out[], Err>

repeatWithSeparator

repeatWithSeparator<Separator>(times: number, separator: Decoder<In, Separator, Err>): Decoder<In, Out[], Err>

- Defined in core/decoder.ts:322
Given a separator decoder, it returns an array of values from the current decoder. It is expected that exactly times values are returned from this decoder.

Type parameters
- Separator
Parameters
- times: number
- separator: Decoder<In, Separator, Err>
Returns Decoder<In, Out[], Err>

skipNext

skipNext<Out2>(next: Decoder<In, Out2, Err>): Decoder<In, Out, Err>

- Defined in core/decoder.ts:186
Make sure that the current decoder is followed by the one defined in next but it ignores its result.

Type parameters
- Out2
Parameters
- next: Decoder<In, Out2, Err>
Returns Decoder<In, Out, Err>

sub

sub<In2, Out2, Err2>(decoder: Decoder<In2, Out2, Err2>, mapInput: function, mapError: function): Decoder<In, Out2, Err>

- Defined in core/decoder.ts:131
Allow to convert the result of decoder into the input for another one. It can be used to use different kind of decoders together.

Type parameters
- In2
- Out2
- Err2
Parameters
- decoder: Decoder<In2, Out2, Err2>
- mapInput: function
  - - (o: Out): In2
    - Parameters
      - o: Out
      Returns In2
- mapError: function
  - - (e: Err2): Err
    - Parameters
      - e: Err2
      Returns Err
Returns Decoder<In, Out2, Err>

surroundedBy

surroundedBy(before: Decoder<In, any, Err>, after?: Decoder<In, any, Err>): Decoder<In, Out, Err>

- Defined in core/decoder.ts:384
Put the current decoder between before and after. The values captured by before and after are discarded.

Parameters
- before: Decoder<In, any, Err>
  
  opening decoder.
- Optional after: Decoder<In, any, Err>
  
  optional closing decoder. If omitted before will be used.
Returns Decoder<In, Out, Err>

test

test(predicate: function, err: Err): Decoder<In, Out, Err>

- Defined in core/decoder.ts:395
If the current decoder is successful it passes its value to predicate and succeed the decoding if the function returns true.

failure is provided to have an explicit error if predicate fails.

Parameters
- predicate: function
  - - (r: Out): boolean
    - Parameters
      - r: Out
      Returns boolean
- err: Err
Returns Decoder<In, Out, Err>

withFailure

withFailure<Err2>(e: Err2): Decoder<In, Out, Err2>

- Defined in core/decoder.ts:435
If the current decoder fails, replace its error with the value of e.

Type parameters
- Err2
Parameters
- e: Err2
Returns Decoder<In, Out, Err2>

withResult

withResult<Out2>(value: Out2): Decoder<In, Out2, Err>

- Defined in core/decoder.ts:428
If the current decoder executes succesfully, ignore its result and replace it with value.

Type parameters
- Out2
Parameters
- value: Out2
Returns Decoder<In, Out2, Err>

Static of

of<In, Out, Err>(run: Decoding<In, Out, Err>): Decoder<In, Out, Err>

- Defined in core/decoder.ts:55
Creates a decoder from a [Decoding] function.

Type parameters
- In
- Out
- Err
Parameters
- run: Decoding<In, Out, Err>
Returns Decoder<In, Out, Err>

Type parameters

In

Out

Err

Hierarchy

Index

Properties

Methods

Properties

_E

_I

_O

Methods

atLeast

Parameters

times: number

Returns Decoder<In, Out[], Err>

atLeastWithSeparator

Type parameters

Separator

Parameters

times: number

separator: Decoder<In, Separator, Err>

Returns Decoder<In, Out[], Err>

atMost

Parameters

times: number

Returns Decoder<In, Out[], Err>

atMostWithSeparator

Type parameters

Separator

Parameters

times: number

separator: Decoder<In, Separator, Err>

Returns Decoder<In, Out[], Err>

between

Parameters

min: number

max: number

Returns Decoder<In, Out[], Err>

betweenWithSeparator

Type parameters

Separator

Parameters

min: number

max: number

separator: Decoder<In, Separator, Err>

Returns Decoder<In, Out[], Err>

flatMap

Type parameters

Out2

Parameters

fun: function

Parameters

res: Out

Returns Decoder<In, Out2, Err>

Returns Decoder<In, Out2, Err>

flatMapError

Type parameters

Err2

Parameters

fun: function

Parameters

res: Err[]

Returns Decoder<In, Out, Err2>

Returns Decoder<In, Out, Err2>

join

Type parameters

Out2

Parameters

next: Decoder<In, Out2, Err>

Returns Decoder<In, [Out, Out2], Err>

many

Returns Decoder<In, Out[], Err>

manyWithSeparator

Type parameters

Separator

Parameters

separator: Decoder<In, Separator, Err>

Returns Decoder<In, Out[], Err>