feat: optional spaces and whitespaces

[ladihzey]

What problem does this feature solve?

Currently the whitespace parser is strict and requires at least one character to be matched. There are many cases where I need to wrap it into optional parser e.g. the spaces before and after argument braces are optional.

function main() {...}
function main (){...}

Describe the solution

I think aligning this parser with other API would be a little bit more convenient by matching the current pairs such as many and many1, sepBy and sepBy1:

• whitespaces1 - requires a single or multiple characters, works as the current whitespace
• whitespaces - requires zero or more whitespaces to match, works as optional(whitespace)
• (optional) wrapWhitespaces and wrapWhitespaces1 - that should prevent writing the common pattern of surrounding whitespaces over and over again:

sequence(
    functionKeyword,
    takeMid(
        optional(whitespace),
        functionName,
        optional(whitespace)
   )
)

/* could be turned into */

sequence(
    functionKeyword,
    wrapWhitespaces(functionName)
)

[ladihzey]

I also find it useful to have a parser dedicated to match only space character e.g. spaces and spaces1, wrapSpaces and wrapSpaces1.

import * as s from '@nrsk/sigma';

/**
 * Matches one or more space characters.
 * Fails if there are no spaces.
 */
export const spaces1 = s.regexp(/ +/g, 'spaces');

/**
 * Optionally matches many space characters.
 * Does not fail if there are no spaces.
 */
export const spaces = s.optional(spaces1);

/**
 * Wraps the provided parser with optional spaces.
 *
 * Spaces are not included in the final result
 *
 * @param parser - a parser to be wrapped
 *
 * @returns a new parser with optional paces at the start and end.
 */
export const wrapSpaces = <T>(parser: s.Parser<T>): s.Parser<T> => {
    return s.takeMid(
        spaces,
        parser,
        spaces,
    );
};

/**
 * Wraps the provided parser with spaces.
 *
 * Spaces are not included in the final result
 *
 * @param parser - a parser to be wrapped
 *
 * @returns a new parser with spaces at the start and end.
 */
export const wrapSpaces1 = <T>(parser: s.Parser<T>): s.Parser<T> => {
    return s.takeMid(
        spaces1,
        parser,
        spaces1,
    );
};

[norskeld]

Yeah, I've been thinking about reworking whitespace parsers, and the ones you suggested totally make sense. Thanks!