@flex-development/vfile-reader
v3.1.2
Published
vfile utility to read from a file
Downloads
6
Maintainers
Readme
vfile-reader
vfile utility to read from a file
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- 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
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:
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 readstart
(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])
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 nextk
-th reader value and index of current value- default:
1
- default:
Returns
(T
) Peeked reader value or null
.
Reader#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 nextk
-th reader value and index of current value- default:
1
- default:
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).
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.