peberminta

Common errors

• ERR_REQUIRE_ESM: require() of ES Module .../node_modules/peberminta/dist/index.js from ... not supported.

  cause Attempting to import peberminta using `require()` in a CommonJS module, but the package is an ES Module.
  fix Convert your project or the specific file to an ES Module by adding `"type": "module"` to your `package.json` or by changing the file extension to `.mjs`. Then use `import * as p from 'peberminta';`.

• Argument of type '{ tokens: string[]; offset: number; }' is not assignable to parameter of type 'PState<unknown>'

  cause Mismatch in the generic type parameters for `PState` (Parser State) or `Parser` functions, often when the token type is not explicitly handled or inferred correctly.
  fix Ensure that the `tokens` array in your `PState` matches the expected token type of your parser. If your parser expects `char` tokens (strings of length 1), make sure your `tokens` array contains `string[]`. Explicitly typing `PState<YourTokenType>` can help resolve ambiguities.

• Type 'Fail' is not assignable to type 'Ok<TOutput, TToken>'

  cause Directly trying to access `value` or other properties on a `ParseResult` without checking its `type` property, which could be 'Fail' if parsing fails.
  fix Always check the `type` property of the `ParseResult` object. Use a conditional check like `if (result.type === 'Ok') { /* access result.value */ } else { /* handle error */ }`.

• No overload matches this call.

  cause Incorrect number or type of arguments passed to a parser combinator function, or a combinator expects a different parser signature than provided.
  fix Review the documentation and type definitions for the specific combinator function. Ensure all required arguments are present and their types (especially the generic `Parser<TOutput, TToken>`) match the expected signature. For example, `p.seq` expects an array of parsers.

Warnings

• gotcha peberminta does not support streaming input; it expects a complete, fixed array of tokens. Users must tokenize their entire input upfront.
  Fix: Ensure your input is fully tokenized into an array before passing it to any parser. If you need streaming capabilities, consider a different library or implement an external streaming tokenization layer.
• breaking As a pre-1.0 package (current version 0.10.0), API stability is not guaranteed. Breaking changes may occur in minor versions without deprecation cycles.
  Fix: Refer to the `CHANGELOG.md` (linked in README) with each update and thoroughly test your parsing logic after upgrading to new minor versions.
• gotcha The core `peberminta` library is token-agnostic and does not provide an integrated lexer/tokenizer. Users must 'bring their own' lexer to convert raw input (e.g., strings) into a token array.
  Fix: Implement a custom tokenizer or use a separate lexing library (like `leac` mentioned in the README) to preprocess your input into an array of tokens before passing it to `peberminta` parsers.
• gotcha peberminta is written with TypeScript and modern `import` syntax, suggesting a primary focus on ESM. While not explicitly stated as 'ESM-only', using `require()` in CommonJS environments might lead to import errors.
  Fix: Prefer using `import` statements in projects configured for ESM. If strictly in a CommonJS environment, ensure Node.js is configured to handle ESM imports, or consider transpilation.

Install

• npm install peberminta npm
• yarn add peberminta yarn
• pnpm add peberminta pnpm

Imports

• p
  wrong:

  const p = require('peberminta');

  correct:

  import * as p from 'peberminta';

  Primary import for core parser combinators. peberminta is designed for modern JavaScript environments, primarily ESM.
• pc
  wrong:

  const pc = require('peberminta/char');

  correct:

  import * as pc from 'peberminta/char';

  Import for character-specific parser building blocks, separate from the highly generic core.
• Parser

  import type { Parser } from 'peberminta';

  Importing types explicitly is good practice in TypeScript, though often inferred.

Quickstart

Demonstrates defining and using basic parser combinators to parse a hexadecimal color string, including tokenization and result handling.

import * as p from 'peberminta';
import * as pc from 'peberminta/char';

// Define a parser for a single hexadecimal digit (0-9, a-f, A-F)
const hexDigit = p.choice(
  pc.digit, // 0-9
  pc.charIn('abcdef'), // a-f
  pc.charIn('ABCDEF')  // A-F
);

// Define a parser for a hex color code, e.g., #RRGGBB
const hexColorParser = p.seq(
  pc.char('#'),
  p.repeat(hexDigit, { min: 6, max: 6 })
);

// Function to parse and format the result
const parseHexColor = (input: string) => {
  const tokens = input.split(''); // Simple tokenizer for char-based parsing
  const result = hexColorParser({ tokens, offset: 0 });

  if (result.type === 'Fail') {
    return `Failed to parse: ${result.kind} at offset ${result.offset}`;
  } else {
    const hexChars = result.value[1].join(''); // Extract the hex digits
    return `Successfully parsed hex color: #${hexChars}`;
  }
};

console.log(parseHexColor('#AABBCC'));
console.log(parseHexColor('#123xyz'));
console.log(parseHexColor('ABCDEF'));