FormatSpec class final

What one format is: its id, its suffixes, the version this build writes, the chain that lifts older documents, and where the fixtures that prove each version still reads are kept.

Declared once, as a constant, beside the format's reader:

static const FormatSpec spec = FormatSpec(
  id: 'f3d.level',
  version: formatVersion,
  suffixes: <String>['.level.json'],
  fixture: 'test/fixtures/v<N>/first.level.json',
  migrations: <FormatMigration>[_identity, _toIds],
);

The repository's structure check reads these declarations and fails when a version has no fixture, so a bump without a file minted at it does not get in.

Constructors

FormatSpec({required String id, required int version, List<String> suffixes = const <String>[], String? fixture, int since = 1, List<FormatMigration> migrations = const <FormatMigration>[], List<String> aliases = const <String>[], String? legacyVersionKey, Set<String> understands = const <String>{}, bool enveloped = true, List<int>? magic})

The declaration of the format id, written at version and read from since up; asserts that version is at least since. Without suffixes no file is recognised as the format by its name.

const

Properties

aliases → List<String>

Ids the format was written under before the envelope, read as this one.

final

enveloped → bool

Whether a document of this format starts with the JSON envelope (read and envelope are for it). False for a format whose file is bytes, or text that is not JSON (the material language): its envelope is its own magic and version, and it is in the registry for its id, suffixes, version and fixtures, with magic what FormatRegistry.sniff looks for.

final

fixture → String?

Where the fixture minted at each version lives, from the package root, with <N> for the version: test/fixtures/v<N>/first.level.json.

final

hashCode → int

The hash code for this object.

no setter, inherited

id → String

The format's name in the envelope: f3d.<kind> for the engine's, <pluginId>.<kind> for a plugin's.

final

legacyVersionKey → String?

The key an old document kept its version under instead of version: f3dfx for an effect, f3dplugin for a data plugin.

final

magic → List<int>?

The bytes a file of this format starts with, for a format that is not enveloped.

final

migrations → List<FormatMigration>

Entry i lifts a document from version since + i to since + i + 1. Shorter than version - since only while the missing steps are the identity, which lift treats them as.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

since → int

The oldest version this build reads.

final

suffixes → List<String>

The file suffixes the format is saved under, with the dot, longest first when one ends another (.level.json before .json).

final

understands → Set<String>

The requires entries this build understands. A document requiring anything else is refused, naming it.

final

version → int

The version this build writes, and the newest it reads.

final

Methods

claims(Map<String, Object?> document) → bool

Whether document says it is this format, under its id or an alias, or carries this format's legacyVersionKey.

envelope({int? version, List<String> requires = const <String>[], String generator = defaultGenerator}) → Map<String, Object?>

The envelope this build writes for a document of this format, in the order it goes at the top of the file.

lift(Map<String, Object?> document, {required int from}) → Map<String, Object?>

document, written at version from, lifted through migrations to version. A step past the end of the list is the identity.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

read(Map<String, Object?> document, {required FormatRefusal refuse}) → Map<String, Object?>

document checked against this format and lifted to version.

toString() → String

A string representation of this object.

override

versionOf(Map<String, Object?> document) → int

The version document was written at: version, else the legacy key, else 1 — a document from before the key existed is the first version. A 0 or a negative is what it says, for read to refuse, and so is anything that is not a finite whole number, read as 0.

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

wholeNumber(Object? value) → int?

value as an int when it is a finite whole number, else null.

Constants

defaultGenerator → const String

What envelope names as the writer when nobody says otherwise.

envelopeKeys → const Set<String>

The envelope's keys, which no format may use for anything else.