vfile-reader

vfile utility to read characters from a file

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • Reader(file[, start])
    • Reader#char
    • Reader#eof
    • Reader#index
    • Reader#now()
    • Reader#offset([point])
    • Reader#peek([k])
    • Reader#peekMatch(test)
    • Reader#point([offset])
    • Reader#previous
    • Reader#read([k])
    • Reader#start
  • CharacterMatch
  • Character
• Types
• Contribute

What is this?

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

When should I use this?

This package is useful when characters need to be read individually or by regex match, 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 { Reader } from 'https://esm.sh/@flex-development/vfile-reader'

In browsers with esm.sh:

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

Use

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

const file: VFile = await read('hrt.ts')
const reader: Reader = new Reader(file)

while (!reader.eof) console.log(reader.read())

API

This package exports the identifier Reader. There is no default export.

Reader(file[, start])

Create a new character 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.

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

Reader#char

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

Reader#eof

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

Reader#index

(Offset) Index of current character.

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#peek([k])

Get the next k-th character 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 character and index of current character
  • default: 1

Returns

(Character) Peeked character or null.

Reader#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.

Reader#point([offset])

See Location#point([offset]).

Reader#previous

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

Reader#read([k])

Get the next k-th character 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 character and index of current character
  • default: 1

Returns

(Character) Next k-th character or null.

Reader#start

(Point) Point before first character in file.

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 the end of file (TypeScript type).

type Character = string | null

Types

This package is fully typed with TypeScript.

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.