onia

About

onia is a lightweight library of monadic parser combinators for JavaScript and TypeScript.
It offers a versatile set of functions to create and combine parsers in a modular and composable manner.
These parsers are designed to process and interpret structured text, making them ideal for parsing programming languages, data formats, and other text-based protocols.

Installation

``bash
$ npm i onia
`

Usage

$3

`ts
import onia, {
regex,
alpha,
map,
many,
int,
sequence,
optional
} from 'onia';

const digit = map(
regex(/\d/g, 'digit'),
int(),
'digit'
);
const digits = map(
many(digit),
(digit) => parseInt(digit.join('')),
'digits'
);
const whitespace = alpha(' ', 'whitespace');
const optionalWhitespace = optional(whitespace, false);
const operator = regex(/[+-]/g, 'operator');
const expression = map(
sequence([
digits,
optionalWhitespace,
operator,
optionalWhitespace,
digits
] as const),
filter([
optionalWhitespace
]),
'expression'
);

const result = onia('123 + 321', expression);
// result === [123, '+', 321]
`

API: Parsers

$3

Creates a parser that matches a specific character.

Parameters:

- char (string): The character to match.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that matches the specified character.

Example:

`ts
const parser = alpha('a');
const result = parser({index: 0, text: 'abc'});
// result === 'a'
`

$3

Creates a parser that matches a regular expression pattern.

Parameters:

- pattern (RegExp): The regular expression pattern to match.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that matches the specified pattern.

Example:

`ts
const parser = regex(/\d+/);
const result = parser({index: 0, text: '123abc'});
// result === '123'
`

$3

Creates a parser that matches a sequence of parsers.

Parameters:

- parsers (readonly Parser[]): The parsers to match in sequence.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that matches the sequence of input parsers.

Example:

`ts
const parser = sequence([alpha('a'), alpha('b'), alpha('c')]);
const result = parser({index: 0, text: 'abc'});
// result === ['a', 'b', 'c']
`

$3

Creates a parser that matches any one of the provided parsers.

Parameters:

- parsers (readonly Parser[]): The parsers to match.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that matches any one of the input parsers.

Example:

`ts
const parser = any([alpha('a'), alpha('b')]);
const result = parser({index: 0, text: 'bcd'});
// result === 'b'
`

$3

Creates a parser that optionally matches another parser.

Parameters:

- parser (Parser): The parser to optionally match.
- defaultValue (T, optional): The default value if the parser does not match.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that optionally matches the input parser.

Example:

`ts
const parser = optional(alpha('a'));
const result = parser({index: 0, text: 'bcd'});
// result === undefined
`

$3

Creates a parser that matches zero or more occurrences of another parser.

Parameters:

- parser (Parser): The parser to match multiple times.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that matches zero or more occurrences of the input parser.

Example:

`ts
const parser = many(alpha('a'));
const result = parser({index: 0, text: 'aaabc'});
// result === ['a', 'a', 'a']
`

$3

Creates a parser that transforms the result of another parser.

Parameters:

- parser (Parser): The parser to transform.
- transform (function): The transformation function.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A parser that transforms the result of the input parser.

Example:

`ts
const parser = map(alpha('a'), (char) => char.toUpperCase());
const result = parser({index: 0, text: 'abc'});
// result === 'A'
`

$3

Creates a parser that is lazily evaluated.

Parameters:

- parserFactory (function): A function that returns the parser to be evaluated.
- expected (string, optional): The name of the expected parser.

Returns:

- Parser: A lazily evaluated parser.

Example:

`ts
const parser = lazy(() => alpha('a'));
const result = parser({index: 0, text: 'abc'});
// result === 'a'
`

API: Helpers

$3

Flattens a nested array by one level.

Example:

`ts
const flattenArray = flatten();
const result = flattenArray([['a', 'b'], ['c', 'd']]);
// result === ['a', 'b', 'c', 'd']
`

$3

Returns the last element of an array.

Example:

`ts
const popElement = pop();
const result = popElement(['a', 'b', 'c']);
// result === 'c'
`

$3

Returns the first element of an array.

Example:

`ts
const shiftElement = shift();
const result = shiftElement(['a', 'b', 'c']);
// result === 'a'
`

$3

Joins all elements of an array into a string.

Example:

`ts
const joinElements = join();
const result = joinElements(['a', 'b', 'c']);
// result === 'abc'
`

$3

Expands the elements of an array.

Example:

`ts
const expandElements = expand();
const result = expandElements(1, 2, 3);
// result === [1, 2, 3]
`

$3

Maps each element of an array using a provided function.

Example:

`ts
const stringParser = alpha('foo');
const numberParser = map(regex(/\d/g), int());

const zipParser = map(
sequence([numberParser, stringParser, numberParser] as const),
zip((parser, value) => {
if (parser === stringParser) {
value = '2';
}
return value;
})
);

const result = zipParser({index: 0, text: '1foo3'});
// result === [1, '2', 3]
`

$3

Parses a string as an integer.

Example:

`ts
const parseInt = int();
const result = parseInt('123');
// result === 123
`

$3

Parses a string as a float.

Example:

`ts
const parseFloat = float();
const result = parseFloat('123.45');
// result === 123.45
`

$3

Filters out specified values from an array.

Parameters:

- values (T): Values to filter out.
- strict (boolean, optional): Filter falsy values out.

Example:

`ts
const filterValues = filter([alpha('a'), 'b']);
const result = filterValues(['a', 'b', null, 'c', 'd'] as const, true);
// result === ['c', 'd']
`

$3

Composes multiple functions into a single function.

Example:

`ts
const pipeline = pipe(
(number: number) => number + 1,
(number: number) => number * 2,
(number: number) => number.toString(),
join()
);
const result = pipeline([1, 2, 3]);
// result === '468'
``

Disclaimer

This project is still in early development and is subject to change.

Licence

MIT License, see LICENSE