utilities library

Small utilities with no platform dependency: cooperative cancellation, one SHA-256, slugs, text decoding that keeps the encoding and BOM, globs and .gitignore matching, protected-value copying with auto-clear, a bounded output transcript, and YAML writing — canonical emission, single-key emission in hand-edited files' style, and surgical edits of existing text.

Reaches no dart:io and no HTTP client, so a web-linkable package can take it without the rest of tom_basics (whose barrel reaches http).

Classes

TomCancellationSource

The write side of a cancellation.

TomCancellationToken

The read side of a cancellation.

TomClipboardPort

The platform clipboard as the protected-copy service needs it.

TomClipboardReceipt

What a binding placed: enough to recognise it later.

TomDecodedText

A file's decoded text and the encoding it came from.

TomGitignore

The rules of one .gitignore file, in the folder base (relative to the root, '' for the root itself).

TomGitignoreSet

Several .gitignore files, as git reads them together: each speaks for the paths under its own folder, and a later file's verdict overrides an earlier one's. Add the files root first, so a deeper file wins.

TomGlob

A compiled glob.

TomOutputLine

One line of output.

TomOutputRecorder

Collects lines up to a bound and counts the rest.

TomOutputTranscript

A program's output, bounded.

TomProtectedClipboard

Copies protected values and clears them again.

TomProtectedClipboardState

What the clipboard service holds right now — what a countdown chip shows.

TomProtectedCopy

What TomProtectedClipboard.copy did.

TomYamlConfigWriter

The single sanctioned path for mutating YAML config text while preserving its on-disk layout.

Enums

TomOutputStream

Which stream a line came from.

TomTextEncoding

How a file's text is stored.

Functions

tomDecodeTextBytes(List<int> bytes) → TomDecodedText

Decodes bytes as the file's own encoding: UTF-16 behind its mark, else UTF-8 (a UTF-8 mark noted and dropped from the text), else Latin-1.

tomDeepSortKeys(Object? value) → Object?

Recursively re-orders every mapping in value by key.

tomEmitCanonicalFragment(Object? value) → String

Emits value as a canonical fragment: rule 1 with every key sorted.

tomEmitLiteralBlock(String value, int keyIndent) → String?

The canonical literal-block emission of value under a key written at keyIndent spaces: the text that follows key: — header and content lines — or null when value has no canonical block form and is emitted by rule 4 instead.

tomEmitYamlDocument(Object? value, {List<String>? blockScalarPath}) → String

Emits value (a map or list) as a YAML document string.

tomEncodeText(String text, TomTextEncoding encoding) → Uint8List

text as encoding's bytes, mark included.

tomNewlineOf(String text) → String

The newline a file uses: CRLF when most of its line breaks are CRLF.

tomOrderedMapping(Map<Object?, Object?> mapping, List<String> known, {Map<String, Object? Function(Object?)> nested = const {}}) → Map<String, Object?>

known keys first in their listed order, then the rest sorted by code point; nested rewrites a named key's value. Keys that are not strings are dropped — a fragment's keys are strings, and a mapping that is not string-keyed has no canonical form to give.

tomSha256Hex(List<int> bytes) → String

The lowercase hex SHA-256 of bytes — 64 characters.

tomSha256OfText(String text) → String

tomSha256Hex over the UTF-8 encoding of text.

tomShortId(String uuid) → String

The first 8 hex characters of a canonical UUID (7f3c9e21-… → 7f3c9e21).

tomSlugify(String text, {String fallback = 'section'}) → String

Lowercase ASCII slug of text: runs of anything but a-z0-9 become one -, with none leading or trailing. An empty result becomes fallback.

tomSortedById(List<Object?> items, {String key = 'id'}) → List<Object?>

items ordered by the string under key, code point order; an item without one keeps its relative position after every item that has one.

tomSortedRemainder(Iterable<String> all, List<String> known) → List<String>

The keys of all that known does not name, sorted by code point — the rule for an open key set.

tomYamlEntry(String key, Object? value, int indent, String nl) → String

The text of key: value, at column indent, ending in nl.

tomYamlListItem(Object? item, int indent, String nl) → String

One - item of a block sequence whose dashes sit at column indent.

tomYamlScalar(String value) → String

value as a one-line YAML scalar: plain when that reads back as the same string in YAML 1.1 and 1.2, double-quoted otherwise.

tomYamlSchemaRefOf(String text) → String?

The schema text names in a # yaml-language-server: $schema= comment, or null when it names none. The reference is returned as written, to be resolved against the file's own folder.

tomYamlToPlain(Object? node) → Object?

Converts a value package:yaml produced into plain Dart: every YamlMap becomes a Map<String, Object?> (keys by their toString), every YamlList a List<Object?>, recursively; scalars pass through.

Typedefs

TomTimerFactory = Timer Function(Duration delay, void callback())

Arms a timer. A parameter so a test can run the clock itself.

Exceptions / Errors

TomOperationCancelled

Thrown by work that noticed its token was cancelled, naming what stopped.