From c78d57a04bb373b2964a3ec0cfb20ad50818a3db Mon Sep 17 00:00:00 2001 From: Vladislav Mamon Date: Tue, 12 Jul 2022 11:17:46 +0500 Subject: [PATCH] feat(tsdoc): add tsdocs for parsers --- .releaserc.json | 6 +--- docs/content/parsers/oneOf.md | 4 +-- src/parsers/any.ts | 5 ++++ src/parsers/defer.ts | 52 +++++++++++++++++++++++++++++++++++ src/parsers/eof.ts | 5 ++++ src/parsers/eol.ts | 5 ++++ src/parsers/float.ts | 5 ++++ src/parsers/letter.ts | 10 +++++++ src/parsers/noneOf.ts | 7 +++++ src/parsers/nothing.ts | 5 ++++ src/parsers/oneOf.ts | 7 +++++ src/parsers/regexp.ts | 15 ++++++++++ src/parsers/rest.ts | 5 ++++ src/parsers/run.ts | 11 ++++++++ src/parsers/string.ts | 14 ++++++++++ src/parsers/whitespace.ts | 5 ++++ 16 files changed, 154 insertions(+), 7 deletions(-) diff --git a/.releaserc.json b/.releaserc.json index 246ff39..8d84953 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -4,11 +4,7 @@ "@semantic-release/commit-analyzer", { "preset": "angular", - "releaseRules": [ - { "type": "docs", "scope": "readme", "release": "patch" }, - { "type": "docs", "scope": "tsdoc", "release": "patch" }, - { "scope": "no-release", "release": false } - ] + "releaseRules": [{ "scope": "no-release", "release": false }] } ], "@semantic-release/release-notes-generator", diff --git a/docs/content/parsers/oneOf.md b/docs/content/parsers/oneOf.md index 6414d3d..e9304c6 100644 --- a/docs/content/parsers/oneOf.md +++ b/docs/content/parsers/oneOf.md @@ -1,7 +1,7 @@ --- title: 'oneOf' kind: 'primitive' -description: 'oneOf tries to match one of the characters in the given string.' +description: 'oneOf ensures that one of the characters in the given string matches the current character.' --- ```typescript {{ withLineNumbers: false }} @@ -10,7 +10,7 @@ function oneOf(): Parser ## Description -`oneOf` tries to match one of the characters in the given string. +`oneOf` ensures that one of the characters in the given string matches the current character. ## Usage diff --git a/src/parsers/any.ts b/src/parsers/any.ts index d2f2163..26cf8b8 100644 --- a/src/parsers/any.ts +++ b/src/parsers/any.ts @@ -1,5 +1,10 @@ import { type Parser } from '../state' +/** + * Parses any single character from the input and returns it. Fails at the end of input. + * + * @returns A single parsed character. + */ export function any(): Parser { return { parse(input, pos) { diff --git a/src/parsers/defer.ts b/src/parsers/defer.ts index 4c62543..2d2cacd 100644 --- a/src/parsers/defer.ts +++ b/src/parsers/defer.ts @@ -1,9 +1,61 @@ import { type Parser } from '../state' +/** + * Intersection type to add a method for deferred parser definition. + * + * @internal + */ type Deferred = Parser & { with(parser: Parser): void } +/** + * This is a special parser that has an additional `with` method, which should be used to define the + * parser. This parser is tailored for creating mutually recursive parsers. + * + * @example + * + * ```typescript + * interface NumberNode { + * type: 'number' + * value: number + * } + * + * interface ListNode { + * type: 'list' + * value: Array + * } + * + * // Here we create 'dummies' + * + * const TupleList = defer() + * const TupleNumber = defer() + * + * // And below we actually define parsers + * + * TupleNumber.with( + * map( + * int(), + * (value) => ({ type: 'number', value }) + * ) + * ) + * + * TupleList.with( + * map( + * takeMid( + * string('('), + * sepBy(choice(TupleList, TupleNumber), string(',')), + * string(')') + * ), + * (value) => ({ type: 'list', value }) + * ) + * ) + * + * console.log( + * run(TupleList).with('(1,2,(3,(4,5)))') + * ) + * ``` + */ export function defer(): Deferred { let deferred: Parser | null = null diff --git a/src/parsers/eof.ts b/src/parsers/eof.ts index 0c64112..e04a289 100644 --- a/src/parsers/eof.ts +++ b/src/parsers/eof.ts @@ -1,5 +1,10 @@ import { type Parser } from '../state' +/** + * Only succeeds at the end of the input. + * + * @returns `null` + */ export function eof(): Parser { return { parse(input, pos) { diff --git a/src/parsers/eol.ts b/src/parsers/eol.ts index b9d6887..3ceb409 100644 --- a/src/parsers/eol.ts +++ b/src/parsers/eol.ts @@ -7,6 +7,11 @@ import { string } from './string' const EOL_UNIX = '\n' const EOL_NON_UNIX = '\r\n' +/** + * Only succeeds at the end of the line, either `\n` or `\r\n`. + * + * @returns Matched line break character + */ export function eol(): Parser { return error(choice(string(EOL_UNIX), string(EOL_NON_UNIX)), 'end of line') } diff --git a/src/parsers/float.ts b/src/parsers/float.ts index ca106c1..82074e4 100644 --- a/src/parsers/float.ts +++ b/src/parsers/float.ts @@ -4,6 +4,11 @@ import { regexp } from './regexp' const FLOAT_RE = /-?\d+\.\d+/g +/** + * Parses a floating point number. + * + * @returns Parsed float as a number + */ export function float(): Parser { return { parse(input, pos) { diff --git a/src/parsers/letter.ts b/src/parsers/letter.ts index 718ed05..3a51b1e 100644 --- a/src/parsers/letter.ts +++ b/src/parsers/letter.ts @@ -5,10 +5,20 @@ import { regexp } from './regexp' const LETTER_RE = /\p{Letter}/gu const LETTERS_RE = /\p{Letter}+/gu +/** + * Parses a single alphabetical character. Unicode friendly. + * + * @returns Matched character. + */ export function letter(): Parser { return regexp(LETTER_RE, 'letter') } +/** + * Parses a sequence of alphabetical characters. Unicode friendly. + * + * @returns Matched characters as a string. + */ export function letters(): Parser { return regexp(LETTERS_RE, 'letters') } diff --git a/src/parsers/noneOf.ts b/src/parsers/noneOf.ts index 1bd5c75..233f87a 100644 --- a/src/parsers/noneOf.ts +++ b/src/parsers/noneOf.ts @@ -1,5 +1,12 @@ import { type Parser } from '../state' +/** + * Ensures that none of the characters in the given string matches the current character. + * + * @param chars - A string of characters that current character should not match + * + * @returns Current character + */ export function noneOf(chars: string): Parser { const charset = [...chars] diff --git a/src/parsers/nothing.ts b/src/parsers/nothing.ts index 6645ebd..ba63669 100644 --- a/src/parsers/nothing.ts +++ b/src/parsers/nothing.ts @@ -1,5 +1,10 @@ import { type Parser } from '../state' +/** + * Simply resolves to `null`. + * + * @returns `null`. + */ export function nothing(): Parser { return { parse(_, pos) { diff --git a/src/parsers/oneOf.ts b/src/parsers/oneOf.ts index 906a01c..6ede151 100644 --- a/src/parsers/oneOf.ts +++ b/src/parsers/oneOf.ts @@ -1,5 +1,12 @@ import { type Parser } from '../state' +/** + * Ensures that one of the characters in the given string matches the current character. + * + * @param chars - A string of characters that current character should match + * + * @returns Current character + */ export function oneOf(chars: string): Parser { const charset = [...chars] diff --git a/src/parsers/regexp.ts b/src/parsers/regexp.ts index f671e5c..c0eca86 100644 --- a/src/parsers/regexp.ts +++ b/src/parsers/regexp.ts @@ -1,5 +1,20 @@ import { type Parser } from '../state' +/** + * Parses a string that matches a provided `re` regular expression. Returns the matched string, or + * fails with an `expected` message. + * + * The regular expression must obey three simple rules: + * + * - It *does* use `g` flag. Flags like `u` and `i` are allowed and can be added if needed. + * - It *doesn't* use `^` and `$` to match at the beginning or at the end of the text. + * - It *doesn't* use capturing groups. + * + * @param re - Regular expression + * @param expected - Error message if the regular expression does not match input + * + * @returns Matched string + */ export function regexp(re: RegExp, expected: string): Parser { return { parse(input, pos) { diff --git a/src/parsers/rest.ts b/src/parsers/rest.ts index 8260b9f..0ec7a98 100644 --- a/src/parsers/rest.ts +++ b/src/parsers/rest.ts @@ -1,5 +1,10 @@ import { type Parser } from '../state' +/** + * Simply returns the unparsed input as a string. Never fails. + * + * @returns Rest of the input as a string + */ export function rest(): Parser { return { parse(input, pos) { diff --git a/src/parsers/run.ts b/src/parsers/run.ts index 48ceded..dd07c8f 100644 --- a/src/parsers/run.ts +++ b/src/parsers/run.ts @@ -1,9 +1,20 @@ import type { Parser, Result } from '../state' +/** + * @internal + */ interface Runnable { with(input: string): Result } +/** + * Runs a parser with provided input. + * + * @typeParam T - Type of parser's result + * @param parser - Parser to run + * + * @returns Parser result + */ export function run(parser: Parser): Runnable { return { with(input) { diff --git a/src/parsers/string.ts b/src/parsers/string.ts index dfec6f6..f6dc22b 100644 --- a/src/parsers/string.ts +++ b/src/parsers/string.ts @@ -1,6 +1,13 @@ import { type Parser } from '../state' import { size } from '../utils/unicode' +/** + * Parses an *ASCII* string. For parsing Unicode strings, consider using `ustring`. + * + * @param match - String to parse + * + * @returns Parsed string + */ export function string(match: string): Parser { return { parse(input, pos) { @@ -28,6 +35,13 @@ export function string(match: string): Parser { } } +/** + * Parses a Unicode string. For parsing ASCII-only strings, consider using `string`. + * + * @param match - String to parse + * + * @returns Parsed string + */ export function ustring(match: string): Parser { return { parse(input, pos) { diff --git a/src/parsers/whitespace.ts b/src/parsers/whitespace.ts index 62bb335..bd78892 100644 --- a/src/parsers/whitespace.ts +++ b/src/parsers/whitespace.ts @@ -4,6 +4,11 @@ import { regexp } from './regexp' const WHITESPACE_REQUIRED_RE = /\s+/g +/** + * Parses whitespace, either a single character or consecutive ones. + * + * @returns Matched whitespace character(s) + */ export function whitespace(): Parser { return regexp(WHITESPACE_REQUIRED_RE, 'whitespace') }