vfile utility to read from a file

• 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#slice(m)
    • Reader#start
  • CharacterReader(file[, start])
    • CharacterReader#peekMatch(test)
  • CodeReader(file[, start])
    • CodeReader#stringify(...codes)
  • CharacterMatch
  • Character
  • Code
  • ReaderIterator<T>
  • ReaderIteratorResult
  • ReaderValue
• Types
• Contribute

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

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

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 } from 'https://esm.sh/@flex-development/vfile-reader'

In browsers with esm.sh:

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

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 } }

This package exports the following identifiers:

• CharacterReader
• Reader

There is no default export.

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) — file to read
• start (Point | null | undefined) — point before first reader value

• T (ReaderValue) — reader output value

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

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

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

(boolean) true if file contains search value.

(Offset) Index of current reader value.

Get the next reader result.

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

(ReaderIteratorResult<T>) Next reader result.

Get the current point in the file.

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

See Location#offset([point]).

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

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

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

(T) Peeked reader value or null.

See Location#point([offset]).

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

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.

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

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

Reset the position of the reader.

(this) The repositioned reader.

Get a slice of the most recent reader values, with the last value being the current reader value, without changing the position of the reader.

• m (number) — maximum number of reader values to include in slice

(NonNullable<T>[]) Reader values slice.

(Point) Point before first reader value in file.

extends: Reader<Character>

Create a new character reader.

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

• test (RegExp) — character test

(CharacterMatch) Peeked character match or null.

extends: Reader<Code>

Create a new code point reader.

Convert the specified sequence of code points to a string.

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

(string) String created from code point sequence.

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

type CharacterMatch = RegExpExecArray | null

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

type Character = string | null

An integer between 0 and 0x10FFFF (inclusive) representing a Unicode code point in a source file, with null denoting end of file (TypeScript type).

type Code = number | null

Input reader iterator API (TypeScript interface).

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

Union of iterator results (TypeScript type).

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

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

type ReaderValue = Character | Code

This package is fully typed with TypeScript.

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.