vfile utility to read from a file
- What is this?
- When should I use this?
- Install
- Use
- API
- Types
- Related
- Contribute
This package implements an input reader that can be used to read characters and character codes (code points) from a file.
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.
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>
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 } }
This package exports the following identifiers:
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
|null
|undefined
) β file to readstart
(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
.
(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 nextk
-th reader value and index of current value- default:
1
- default:
(T
) Peeked reader value or null
.
(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 nextk
-th reader value and index of current value- default:
1
- default:
(T
) Next k
-th reader value or null
.
Reset the position of the reader.
(this
) The repositioned reader.
Convert the specified sequence of reader values to a string.
...values
(ReaderSlice<T> | T[]
) β reader value sequence
(string
) String created from reader value sequence.
Get the values spanning range
without changing the position of the reader.
range
(Range
) β slice position
(ReaderSlice<T>
) Reader value slice.
Get the text spanning range
without changing the position of the reader.
range
(Range
) β slice position
(string
) Serialized 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 character code reader.
Create a code check from a character code or regular expression.
test
(Code | RegExp
) β test to create check from
(CodeCheck
) Code check.
Convert the specified sequence of character codes to a string.
...codes
(Code[]
) β character code sequence
(string
) String created from character code sequence.
Instance method equivalent of CodeReader.check(test)
.
Character dictionary.
Character code dictionary.
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
Create a code check from a character code or regular expression (TypeScript type).
type CodeCheckFactory = (test: Code | RegExp) => CodeCheck
test
(Code | RegExp
) β test to create check from
(CodeCheck
) Code check.
Check whether a character code, or sequence of codes, matches the bound test (TypeScript type).
type CodeCheck = (code: Code | Code[]) => boolean
code
(Code | Code[]
) β code or code sequence to check
(boolean
) true
if code
matches bound test.
Character code (code point) in a source file, with null
denoting end of file (TypeScript type).
type Code = number | null
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.
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).
type RangeTuple = [
start: Offset | Point,
end?: Offset | Point | null | undefined
]
Union of range types (TypeScript type).
type Range = Position | RangeTuple
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>
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>]
| []
Character or character code in a source file, with null
denoting the end of file (TypeScript type).
type ReaderValue = Character | Code
Reader output values (TypeScript type).
type ReaderValues<T extends ReaderValue = ReaderValue> = readonly [
...values: NonNullable<T>[],
eof: null
]
This package is fully typed with TypeScript.
vfile-location
β vfile utility to convert between point and offset based locations
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.