https://github.com/flex-development/vfile-reader
vfile utility to read from a file
https://github.com/flex-development/vfile-reader
character code-point reader unicode vfile vfile-util
Last synced: 4 months ago
JSON representation
vfile utility to read from a file
- Host: GitHub
- URL: https://github.com/flex-development/vfile-reader
- Owner: flex-development
- License: bsd-3-clause
- Created: 2024-05-06T22:07:52.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-07T11:32:36.000Z (over 1 year ago)
- Last Synced: 2024-11-07T12:25:35.150Z (over 1 year ago)
- Topics: character, code-point, reader, unicode, vfile, vfile-util
- Language: TypeScript
- Homepage: https://github.com/flex-development/vfile-reader
- Size: 3.08 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# vfile-reader
[](https://github.com/flex-development/vfile-reader/releases/latest)
[](https://npmjs.com/package/@flex-development/vfile-reader)
[](https://codecov.io/gh/flex-development/vfile-reader)
[](https://github.com/voxpelli/badges-cjs-esm)
[](LICENSE.md)
[](https://conventionalcommits.org/)
[](https://typescriptlang.org/)
[](https://vitest.dev/)
[](https://yarnpkg.com/)
[vfile][vfile] utility to read from a file
## Contents
- [What is this?](#what-is-this)
- [When should I use this?](#when-should-i-use-this)
- [Install](#install)
- [Use](#use)
- [API](#api)
- [`Reader(file[, start])`](#readerfile-start)
- [`Reader#eof`](#readereof)
- [`Reader#includes(value)`](#readerincludesvalue)
- [`Reader#index`](#readerindex)
- [`Reader#next`](#readernext)
- [`Reader#now()`](#readernow)
- [`Reader#offset([point])`](#readeroffsetpoint)
- [`Reader#output`](#readeroutput)
- [`Reader#peek([k])`](#readerpeekk)
- [`Reader#point([offset])`](#readerpointoffset)
- [`Reader#previous`](#readerprevious)
- [`Reader#read([k])`](#readerreadk)
- [`Reader#reset()`](#readerreset)
- [`Reader#serialize(...values)`](#readerserializevalues)
- [`Reader#slice(range)`](#readerslicerange)
- [`Reader#sliceSerialize(range)`](#readersliceserializerange)
- [`Reader#start`](#readerstart)
- [`CharacterReader(file[, start])`](#characterreaderfile-start)
- [`CharacterReader#peekMatch(test)`](#characterreaderpeekmatchtest)
- [`CodeReader(file[, start])`](#codereaderfile-start)
- [`CodeReader.check(test)`](#codereaderchecktest)
- [`CodeReader.serialize(...codes)`](#codereaderserializecodes)
- [`CodeReader#check(test)`](#codereaderchecktest-1)
- [`chars`](#chars)
- [`codes`](#codes)
- [`CharacterMatch`](#charactermatch)
- [`Character`](#character)
- [`CodeCheckFactory`](#codecheckfactory)
- [`CodeCheck`](#codecheck)
- [`Code`](#code)
- [`Position`](#position)
- [`RangeTuple`](#rangetuple)
- [`Range`](#range)
- [`ReaderIterator`](#readeriteratort)
- [`ReaderIteratorResult`](#readeriteratorresult)
- [`ReaderSlice`](#readerslicet)
- [`ReaderValue`](#readervalue)
- [`ReaderValues`](#readervaluest)
- [Types](#types)
- [Related](#related)
- [Contribute](#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][esm].
In Node.js (version 18+) with [yarn][yarn]:
```sh
yarn add @flex-development/vfile-reader
```
See Git - Protocols | Yarn
for details regarding installing from Git.
In Deno with [`esm.sh`][esmsh]:
```ts
import {
CharacterReader,
CodeReader,
chars,
codes
} from 'https://esm.sh/@flex-development/vfile-reader'
```
In browsers with [`esm.sh`][esmsh]:
```html
import {
CharacterReader,
CodeReader,
chars,
codes
} from 'https://esm.sh/@flex-development/vfile-reader'
```
## Use
```ts
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
```sh
{ 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`](#characterreaderfile-start)
- [`CodeReader`](#codereaderfile-start)
- [`Reader`](#readerfile-start)
- [`chars`](#chars)
- [`codes`](#codes)
There is no default export.
### `Reader(file[, start])`
> **extends**: [`Location`][location]\
> **implements**: [`ReaderIterator`](#readeriteratort)
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-value] | [`VFile`][vfile-api] | `null` | `undefined`) — file to read
- `start` ([`Point`][point] | `null` | `undefined`) — point before first reader value
#### Type Parameters
- `T` ([`ReaderValue`](#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`][offset]) Index of current reader value.
#### `Reader#next()`
Get the next reader result.
Unlike [`peek`](#readerpeekk), this method changes the position of the reader.
##### `Returns`
([`ReaderIteratorResult`](#readeriteratorresult)) Next reader result.
#### `Reader#now()`
Get the current point in the file.
##### `Returns`
([`Point`][point]) Current point in file, relative to [`reader#start`](#readerstart).
#### `Reader#offset([point])`
See [`Location#offset([point])`][locationoffset-point].
#### `Reader#output`
(`T`) Current reader value or `null`, with `null` denoting end of file. Equivalent to
[`reader.peek(0)`](#readerpeekk).
#### `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])`][locationpoint-offset].
#### `Reader#previous`
(`T`) Previous reader value or `null`, with `null` denoting beginning or end of file. Equivalent to
[`reader.peek(-1)`](#readerpeekk).
#### `Reader#read([k])`
Get the next `k`-th reader value from the file, with `null` denoting end of file.
Unlike [`peek`](#readerpeekk), 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[]`) — 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`](#range)) — slice position
##### `Returns`
([`ReaderSlice`](#readerslicet)) Reader value slice.
#### `Reader#sliceSerialize(range)`
Get the text spanning `range` without changing the position of the reader.
##### `Parameters`
- `range` ([`Range`](#range)) — slice position
##### `Returns`
(`string`) Serialized slice.
#### `Reader#start`
([`Point`][point]) Point before first reader value in file.
### `CharacterReader(file[, start])`
> **extends**: `Reader`
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`](#charactermatch)) Peeked character match or `null`.
### `CodeReader(file[, start])`
> **extends**: `Reader`
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`](#codecheck)) Code check.
#### `CodeReader.serialize(...codes)`
Convert the specified sequence of character codes to a string.
##### `Parameters`
- `...codes` ([`Code[]`](#code)) — character code sequence
##### `Returns`
(`string`) String created from character code sequence.
#### `CodeReader#check(test)`
Instance method equivalent of [`CodeReader.check(test)`](#codereaderchecktest).
### `chars`
Character dictionary.
### `codes`
Character code dictionary.
### `CharacterMatch`
Match in a source file, with `null` denoting no match (TypeScript type).
```ts
type CharacterMatch = RegExpExecArray | null
```
### `Character`
Character in a source file, with `null` denoting end of file (TypeScript type).
```ts
type Character = string | null
```
### `CodeCheckFactory`
Create a code check from a character code or regular expression (TypeScript type).
```ts
type CodeCheckFactory = (test: Code | RegExp) => CodeCheck
```
#### `Parameters`
- `test` (`Code | RegExp`) — test to create check from
#### `Returns`
([`CodeCheck`](#codecheck)) Code check.
### `CodeCheck`
Check whether a character code, or sequence of codes, matches the bound test (TypeScript type).
```ts
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][codepointat]) in a source file, with `null` denoting end of file (TypeScript type).
```ts
type Code = number | null
```
### `Position`
Range between two points in a source file (TypeScript interface).
> See also: [`Point`][point]
```ts
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`][offset], [`Point`][point]
```ts
type RangeTuple = [
start: Offset | Point,
end?: Offset | Point | null | undefined
]
```
### `Range`
Union of range types (TypeScript type).
```ts
type Range = Position | RangeTuple
```
### `ReaderIterator`
Input reader iterator API (TypeScript interface).
```ts
interface ReaderIterator {
[Symbol.iterator](): ReaderIterator
next(): ReaderIteratorResult
}
```
### `ReaderIteratorResult`
Union of iterator results (TypeScript type).
```ts
type ReaderIteratorResult<
T extends ReaderValue = ReaderValue
> = IteratorReturnResult | IteratorYieldResult
```
### `ReaderSlice`
Array representing a slice of reader output values (TypeScript type).
```ts
type ReaderSlice =
| [...values: NonNullable[], value: NonNullable]
| [...values: ReaderValues]
| []
```
### `ReaderValue`
Character or character code in a source file, with `null` denoting the end of file (TypeScript type).
```ts
type ReaderValue = Character | Code
```
### `ReaderValues`
Reader output values (TypeScript type).
```ts
type ReaderValues = readonly [
...values: NonNullable[],
eof: null
]
```
## Types
This package is fully typed with [TypeScript][typescript].
## Related
- [`vfile-location`][vfile-location] — [vfile][vfile] utility to convert between point and offset based locations
## Contribute
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
This project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
community you agree to abide by its terms.
[codepointat]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh/
[location]: https://github.com/flex-development/vfile-location#locationfile-start
[locationoffset-point]: https://github.com/flex-development/vfile-location#locationoffsetpoint
[locationpoint-offset]: https://github.com/flex-development/vfile-location#locationpointoffset
[offset]: https://github.com/flex-development/unist-util-types#offset
[point]: https://github.com/flex-development/vfile-location#point
[typescript]: https://www.typescriptlang.org
[vfile-api]: https://github.com/vfile/vfile#vfileoptions
[vfile-location]: https://github.com/flex-development/vfile-location
[vfile-value]: https://github.com/vfile/vfile#value
[vfile]: https://github.com/vfile/vfile
[yarn]: https://yarnpkg.com