@flex-development/vfile-reader

vfile-reader

vfile utility to read from a file

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • Reader(file[, start])
    • Reader#eof
    • Reader#includes(value)
    • Reader#index
    • Reader#next
    • Reader#now()
    • Reader#offset([point])
    • Reader#output
    • Reader#peek([k])
    • Reader#point([offset])
    • Reader#previous
    • Reader#read([k])
    • Reader#reset()
    • Reader#serialize(...values)
    • Reader#slice(range)
    • Reader#sliceSerialize(range)
    • Reader#start
  • CharacterReader(file[, start])
    • CharacterReader#peekMatch(test)
  • CodeReader(file[, start])
    • CodeReader.check(test)
    • CodeReader.serialize(...codes)
    • CodeReader#check(test)
  • chars
  • codes
  • CharacterMatch
  • Character
  • CodeCheckFactory
  • CodeCheck
  • Code
  • Position
  • RangeTuple
  • Range
  • ReaderIterator<T>
  • ReaderIteratorResult
  • ReaderSlice<T>
  • ReaderValue
  • ReaderValues<T>
• Types
• Related
• Contribute

What is this?

This package implements an input reader that can be used to read characters and character codes (code points) from a file.

When should I use this?

This package is useful when characters or codes need to be read individually or as a group, such as when building a parser or tokenizer.

Install

This package is ESM only.

In Node.js (version 18+) with yarn:

yarn add @flex-development/vfile-reader

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

import {
  CharacterReader,
  CodeReader,
  chars,
  codes
} from 'https://esm.sh/@flex-development/vfile-reader'

In browsers with esm.sh:

<script type="module">
  import {
    CharacterReader,
    CodeReader,
    chars,
    codes
  } from 'https://esm.sh/@flex-development/vfile-reader'
</script>

Use

import { CharacterReader, CodeReader } from '@flex-development/vfile-reader'
import { read } from 'to-vfile'
import type { VFile } from 'vfile'

const file: VFile = await read('__fixtures__/emojis.txt') // 😍👍🚀❇️

const chars: CharacterReader = new CharacterReader(file)
const codes: CodeReader = new CodeReader(file)

// for (const char of chars) console.dir({ char, now: chars.now() })
// for (const code of codes) console.dir({ code, now: codes.now() })

while (!chars.eof) {
  console.dir({
    char: chars.read(),
    code: codes.read(),
    now: codes.now()
  })
}

...yields

{ char: '😍', code: 128525, now: { column: 1, line: 1, offset: 0 } }
{ char: '👍', code: 128077, now: { column: 2, line: 1, offset: 1 } }
{ char: '🚀', code: 128640, now: { column: 3, line: 1, offset: 2 } }
{ char: '❇', code: 10055, now: { column: 4, line: 1, offset: 3 } }
{ char: '️', code: 65039, now: { column: 5, line: 1, offset: 4 } }
{ char: '\n', code: 10, now: { column: 6, line: 1, offset: 5 } }
{ char: null, code: null, now: { column: 1, line: 2, offset: 6 } }

API

This package exports the following identifiers:

• CharacterReader
• CodeReader
• Reader
• chars
• codes

There is no default export.

Reader(file[, start])

extends: Location
implements: ReaderIterator<T>

Create a new input reader.

Pass a start point to make reader locations relative to a specific place. Any point or offset accessed will be relative to the given point.

Note: This is an abstract class and must be extended.

• file (Value | VFile | null | undefined) — file to read
• start (Point | null | undefined) — point before first reader value

Type Parameters

• T (ReaderValue) — reader output value

Reader#eof

(boolean) Boolean indicating if reader has reached the end of file, with true denoting end of file.

Reader#includes(value)

Check if the file contains the given search value, relative to the current reader position.

Parameters

• value (string) — value to search for in file

Returns

(boolean) true if file contains search value.

Reader#index

(Offset) Index of current reader value.

Reader#next()

Get the next reader result.

Unlike peek, this method changes the position of the reader.

Returns

(ReaderIteratorResult<T>) Next reader result.

Reader#now()

Get the current point in the file.

Returns

(Point) Current point in file, relative to reader#start.

Reader#offset([point])

See Location#offset([point]).

Reader#output

(T) Current reader value or null, with null denoting end of file. Equivalent to reader.peek(0).

Reader#peek([k])

Get the next k-th reader value from the file without changing the position of the reader, with null denoting end of file.

Parameters

• k (number | undefined) — difference between index of next k-th reader value and index of current value
  • default: 1

Returns

(T) Peeked reader value or null.

Reader#point([offset])

See Location#point([offset]).

Reader#previous

(T) Previous reader value or null, with null denoting beginning or end of file. Equivalent to reader.peek(-1).

Reader#read([k])

Get the next k-th reader value from the file, with null denoting end of file.

Unlike peek, this method changes the position of the reader.

Parameters

• k (number | undefined) — difference between index of next k-th reader value and index of current value
  • default: 1

Returns

(T) Next k-th reader value or null.

Reader#reset()

Reset the position of the reader.

Returns

(this) The repositioned reader.

Reader#serialize(...values)

Convert the specified sequence of reader values to a string.

Parameters

• ...values (ReaderSlice<T> | T[]) — reader value sequence

Returns

(string) String created from reader value sequence.

Reader#slice(range)

Get the values spanning range without changing the position of the reader.

Parameters

• range (Range) — slice position

Returns

(ReaderSlice<T>) Reader value slice.

Reader#sliceSerialize(range)

Get the text spanning range without changing the position of the reader.

Parameters

• range (Range) — slice position

Returns

(string) Serialized slice.

Reader#start

(Point) Point before first reader value in file.

CharacterReader(file[, start])

extends: Reader<Character>

Create a new character reader.

CharacterReader#peekMatch(test)

Get the next match from the file without changing the position of the reader, with null denoting no match.

Parameters

• test (RegExp) — character test

Returns

(CharacterMatch) Peeked character match or null.

CodeReader(file[, start])

extends: Reader<Code>

Create a new character code reader.

CodeReader.check(test)

Create a code check from a character code or regular expression.

Parameters

• test (Code | RegExp) — test to create check from

Returns

(CodeCheck) Code check.

CodeReader.serialize(...codes)

Convert the specified sequence of character codes to a string.

Parameters

• ...codes (Code[]) — character code sequence

Returns

(string) String created from character code sequence.

CodeReader#check(test)

Instance method equivalent of CodeReader.check(test).

chars

Character dictionary.

codes

Character code dictionary.

CharacterMatch

Match in a source file, with null denoting no match (TypeScript type).

type CharacterMatch = RegExpExecArray | null

Character

Character in a source file, with null denoting end of file (TypeScript type).

type Character = string | null

CodeCheckFactory

Create a code check from a character code or regular expression (TypeScript type).

type CodeCheckFactory = (test: Code | RegExp) => CodeCheck

Parameters

• test (Code | RegExp) — test to create check from

Returns

(CodeCheck) Code check.

CodeCheck

Check whether a character code, or sequence of codes, matches the bound test (TypeScript type).

type CodeCheck = (code: Code | Code[]) => boolean

Parameters

• code (Code | Code[]) — code or code sequence to check

Returns

(boolean) true if code matches bound test.

Code

Character code (code point) in a source file, with null denoting end of file (TypeScript type).

type Code = number | null

Position

Range between two points in a source file (TypeScript interface).

See also: Point

interface Position {
  end: Point
  start: Point
}

The start field represents the place of the first reader value in the range. The end field represents the place of the last reader value in the range.

RangeTuple

List, where the first value is the location of the first reader value in a slice, and the last is the location of the last reader value, with null or undefined denoting all values after the first (inclusive) are included in the slice (TypeScript type).

See also: Offset, Point

type RangeTuple = [
  start: Offset | Point,
  end?: Offset | Point | null | undefined
]

Range

Union of range types (TypeScript type).

type Range = Position | RangeTuple

ReaderIterator<T>

Input reader iterator API (TypeScript interface).

interface ReaderIterator<T extends ReaderValue = ReaderValue> {
  [Symbol.iterator](): ReaderIterator<T>
  next(): ReaderIteratorResult<T>
}

ReaderIteratorResult

Union of iterator results (TypeScript type).

type ReaderIteratorResult<
  T extends ReaderValue = ReaderValue
> = IteratorReturnResult<T> | IteratorYieldResult<T>

ReaderSlice<T>

Array representing a slice of reader output values (TypeScript type).

type ReaderSlice<T extends ReaderValue = ReaderValue> =
  | [...values: NonNullable<T>[], value: NonNullable<T>]
  | [...values: ReaderValues<T>]
  | []

ReaderValue

Character or character code in a source file, with null denoting the end of file (TypeScript type).

type ReaderValue = Character | Code

ReaderValues<T>

Reader output values (TypeScript type).

type ReaderValues<T extends ReaderValue = ReaderValue> = readonly [
  ...values: NonNullable<T>[],
  eof: null
]

Types

This package is fully typed with TypeScript.

Related

• vfile-location — vfile utility to convert between point and offset based locations

Contribute

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.