tom_basics library

Basic utilities for the TOM framework.

This library provides foundational utilities that have minimal dependencies and can be used by other TOM framework packages:

Usage

import 'package:tom_basics/tom_basics.dart';

throw TomBaseException('orders.submit.no_positions', 'The order is empty');
tomLog.info('Application started');

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.
TomConsoleLogOutput
Default console-based log output implementation.
TomDecodedText
A file's decoded text and the encoding it came from.
TomDiagnosticEvent
One structured entry.
TomDiagnosticNotice
A finding that has to be both shown and logged.
TomDiagnostics
Where structured events go.
TomDiagnosticsLogOutput
A TomLogOutput that writes every TomLogger line into a TomDiagnostics sink, so a program that logs both ways — rendered lines through tomLog, structured events through the port — keeps one log.
TomEnvironment
Defines a runtime environment configuration.
TomFallbackPlatformUtils
A fallback implementation of TomPlatformUtils.
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.
TomInMemoryDiagnostics
A bounded in-memory sink.
TomLoggable
Interface for objects that can provide a custom log representation.
TomLogger
The main logger class providing structured logging capabilities.
TomLogLevel
Represents a logging level with support for bitwise operations.
TomLogOutput
Abstract base class for log output implementations.
TomNullDiagnostics
The sink a build that logs nowhere gets.
TomOutputLine
One line of output.
TomOutputRecorder
Collects lines up to a bound and counts the rest.
TomOutputTranscript
A program's output, bounded.
TomPlatform
Defines a target platform for bean selection.
TomPlatformUtils
Abstract base class for platform-specific utility operations.
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.
TomRuntime
Central runtime configuration manager.
TomStructuredFailure
A failure that can say what it is without its text.
TomYamlConfigWriter
The single sanctioned path for mutating YAML config text while preserving its on-disk layout.

Enums

TomDiagnosticLevel
How much the reader is meant to care.
TomOutputStream
Which stream a line came from.
TomTextEncoding
How a file's text is stored.

Constants

defaultTomEnvironment → const TomEnvironment
Default environment when none is specified.
noTomEnvironment → const TomEnvironment
Sentinel value indicating no environment constraint.
noTomPlatform → const TomPlatform
Sentinel value indicating no platform constraint.
platformAndroid → const TomPlatform
Android platform constant.
platformFuchsia → const TomPlatform
Fuchsia platform constant.
platformIos → const TomPlatform
iOS platform constant.
platformLinux → const TomPlatform
Linux platform constant.
platformMacos → const TomPlatform
macOS platform constant.
platformWeb → const TomPlatform
Web platform constant.
platformWindows → const TomPlatform
Windows platform constant.

Properties

tomLog ↔ TomLogger
The global logger instance.
getter/setter pair

Functions

limited(Object? o, dynamic maxLength) → String
Limits the string representation of an object to a maximum length.
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.
tomFailureFields(Object error) → Map<String, Object>
The field map a failure is logged under: its type, and whatever it says about itself structurally (TomStructuredFailure). Never its text.
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

TomBaseException
Base exception class with UUID tracking, timestamps, and stack trace support.
TomOperationCancelled
Thrown by work that noticed its token was cancelled, naming what stopped.