https://github.com/wiselibs/toml-v1
A TOML v1.0.0 spec-compliant parser
https://github.com/wiselibs/toml-v1
Last synced: 3 months ago
JSON representation
A TOML v1.0.0 spec-compliant parser
- Host: GitHub
- URL: https://github.com/wiselibs/toml-v1
- Owner: WiseLibs
- License: mit
- Created: 2024-02-01T12:06:12.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-02-01T12:44:13.000Z (almost 2 years ago)
- Last Synced: 2025-04-09T19:16:09.363Z (9 months ago)
- Language: JavaScript
- Size: 47.9 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# toml-v1 [](https://github.com/WiseLibs/toml-v1/actions/workflows/test.yml)
A TOML parser compatible with TOML version [v1.0.0](https://toml.io/en/v1.0.0).
This package passes [the TOML test suite](https://github.com/toml-lang/toml-test), except for a few tests that fall into these categories:
- Tests for 64-bit integers (JavaScript numbers only have 53 bits of precision)
- Tests for detecting invalid UTF-8 (not applicable to JavaScript strings)
It has the additional ability to track the source locations of keys and values after parsing ([see below](#source-tracking)).
## Installation
```
npm install toml-v1
```
> Requires Node.js v14.x.x or later.
## Usage
```js
import { parse } from 'toml-v1';
const data = parse('[foo]\nbar = 123');
assert(data.foo.bar === 123);
```
### Parsing dates
TOML defines four types of dates:
- [`OffsetDateTime`](https://toml.io/en/v1.0.0#offset-date-time)
- [`LocalDateTime`](https://toml.io/en/v1.0.0#local-date-time)
- [`LocalDate`](https://toml.io/en/v1.0.0#local-date)
- [`LocalTime`](https://toml.io/en/v1.0.0#local-time)
This package defines these types as subclasses of `Date`. The `OffsetDateTime` subclass is functionally equivalent to `Date`, but its timezone information is not forgotten. The other classes contain incomplete date/time information, so some of their methods are disabled. For example, calling `.getFullYear()` on `LocalTime` will throw an error.
```js
import { LocalTime } from 'toml-v1';
const localTime = new LocalTime('12:42:42');
assert(localTime.getHours() === 12);
assert(localTime.toString() === '12:42:42');
```
### Source tracking
By using the `SourceTracker`, you can retrieve [`Source`](https://github.com/WiseLibs/super-sources?tab=readme-ov-file#new-sourcefile-start-end) objects corresponding to each key and value in the TOML file.
```js
import { parser, SourceTracker } from 'toml-v1';
const tracker = new SourceTracker();
const data = parse('[foo]\nbar = 123', 'example.toml', tracker);
const keySource = tracker.getKeySource(data.foo, 'bar');
const valueSource = tracker.getValueSource(data.foo, 'bar');
assert(keySource.start === 6);
assert(keySource.end === 9);
assert(valueSource.start === 12);
assert(valueSource.end === 15);
```
## License
[MIT](https://github.com/WiseLibs/toml-v1/blob/master/LICENSE)