pdata 1.0.0

A reader/writer for JSON, YAML, and TOML config files, in pure Dart.

pdata

A reader/writer for JSON, YAML, and TOML config files, written in pure Dart. No package:yaml, no package:toml — the parsers and encoders are hand-written, so pdata adds zero transitive dependencies to your project.

Features

• Read and write JSON, YAML, and TOML through one small API.
• Format is guessed from the file extension (.json, .yaml/.yml, .toml), or you can pass it explicitly.
• Sync and async file I/O, plus pdataDecode/pdataEncode for working with strings directly.
• Typed getInt / getDouble / getBool / getString / getList / getMap accessors on the resulting map, with clear errors instead of crashes.
• Zero dependencies — JSON is a thin wrapper over dart:convert (part of the Dart SDK, not a package); YAML and TOML are parsed and written by pdata itself.

Installation

Add pdata to your pubspec.yaml:

dependencies:
  pdata: ^1.0.0

Then run:

dart pub get

Usage

import 'package:pdata/pdata.dart';

void main() {
  final config = pdataReadFile('config.yaml') as Map<String, dynamic>;

  print(config.getString('name'));
  print(config.getInt('port', defaultValue: 8080));

  pdataWriteFile('config.json', config);
}

Format is picked up from the extension, so the same code works for .json, .yaml/.yml, and .toml files. Pass format: explicitly if you need to override that (e.g. a .conf file that's actually TOML):

final config = pdataReadFile('app.conf', format: PdataFormat.toml);

Working with strings directly

final data = decodeYaml('name: my-app\nport: 8080\n');
final yaml = encodeYaml(data);
final toml = encodeToml(data as Map<String, dynamic>);
final json = encodeJson(data);

Typed accessors

final config = pdataReadFile('config.toml') as Map<String, dynamic>;

final port = config.getInt('port', defaultValue: 8080);
final debug = config.getBool('debug', defaultValue: false);
final name = config.getString('name'); // throws FormatException if missing
final tags = config.getList('tags');
final author = config.getMap('author');

Async

final config = await pdataReadFileAsync('config.yaml') as Map<String, dynamic>;
await pdataWriteFileAsync('config.json', config);

Supported syntax

pdata's YAML and TOML support is a well-tested subset covering what the vast majority of hand-written config files use — not the full spec. If you hit a document pdata can't parse, please open an issue with a minimal example.

YAML

Supported: block and flow mappings/sequences (nested and mixed), single/double-quoted and plain scalars, # comments, null/true/false/int/float scalars, and literal (|) / folded (>) block scalars (with -/+ chomping).

Not supported: multiple documents in one string, anchors/aliases, tags, and explicit block-scalar indentation indicators (e.g. |2). encodeYaml always writes block style, even though decodeYaml can read flow style.

TOML

Supported: tables ([table]), arrays of tables ([[table]]), dotted and quoted keys, inline tables, arrays (including multi-line), basic and literal strings (including their triple-quoted multi-line forms), integers (decimal/hex/octal/binary), floats (including inf/nan), booleans, and RFC 3339 date-times (parsed into DateTime where possible).

Not supported: space-separated date-times (use T, not a space, between the date and time) and bare local-time values (07:32:00 with no date). TOML has no null; encoding a map containing a null value throws PdataFormatException — omit the key instead.

Exceptions

• PdataFileNotFoundException — the requested file doesn't exist.
• PdataFormatException — the format couldn't be guessed from a file extension, or a value can't be represented in the requested format (e.g. null in TOML).
• PdataParseException — YAML or TOML input is malformed. (JSON parse errors surface as Dart's own FormatException, from dart:convert.)

try {
  final config = pdataReadFile('config.yaml');
} on PdataFileNotFoundException catch (e) {
  print(e);
} on PdataParseException catch (e) {
  print(e);
}