utils library
🧩 Jetleaf Utilities Subsystem
This library provides general-purpose helper utilities, text processors, configuration format parsers, and diagnostic decoding tools for the Jetleaf framework.
Key capabilities:
- Recursive Placeholder Resolution: Dynamic resolution of
${key:default}patterns. - Multi-Format Parsers: Unified AST and object parsing for YAML, JSON, XML, Properties, and ENV.
- Stack Trace Sanitization: Demangling and filtering internal VM frames for clear diagnostics.
- Assertion & String Helpers: Defensive programming guards and casing utilities.
🔄 Placeholder Resolution Flow
┌─────────────────────────────────────────────────────────────┐
│ Input Template String │
│ "https://${server.host:localhost}:${port}" │
├─────────────────────────────────────────────────────────────┤
│ 1. Parse Token Find prefix "${" and suffix "}" │
│ │ │
│ 2. Extract Key/Default key: "server.host", fallback: "..." │
│ │ │
│ 3. Query Resolver Look up key in PropertyPlaceholder │
│ │ │
│ 4. Recursive Replace Substitute nested expressions │
└─────────────────────────────────────────────────────────────┘
📦 Exports Categorization
🏷️ Placeholder Resolution
- PropertyPlaceholderHelper — utility for replacing
${...}placeholders with property values. - PlaceholderResolver — functional contract mapping placeholder keys to replacement values.
- PlaceholderParser — low-level parser extracting placeholder keys, prefixes, and suffixes.
📄 Configuration Parsers
- YamlParser — parses structured YAML documents into Dart Maps and Lists.
- JsonParser — parses JSON streams and strings with strict type safety.
- PropertiesParser — parses Java-style
.propertieskey-value pairs. - EnvParser — parses
.envfiles with quoted strings and variable expansion.
🩺 Stack Trace Utilities
- StackTraceParser — parses raw Dart stack traces into structured TraceFrame instances.
- TraceFrame — encapsulates file, line number, column, member, and package metadata.
🛡️ Guards & Defensiveness
- Assert — defensive programming validation helpers (e.g.
notNull,hasText,state). - StringUtils — high-performance string manipulation, casing, and collection joining.
🎯 Usage Example: Placeholders & Defensive Assertions
import 'package:jetleaf_core/utils.dart';
void main() {
// 1. Validate preconditions with Assert
final username = 'alice';
Assert.hasText(username, 'Username must not be empty');
// 2. Resolve placeholders dynamically
final helper = PropertyPlaceholderHelper('\${', '}');
final properties = {
'api.host': 'api.jetleaf.dev',
'api.version': 'v2',
};
final endpoint = helper.replacePlaceholders(
'https://\${api.host}/\${api.version}/users/\${api.missing:current}',
(key) => properties[key],
);
print('Resolved Endpoint: $endpoint');
// Output: https://api.jetleaf.dev/v2/users/current
}
Classes
- Assert
- A utility class that provides static assertion methods for validating arguments and states in your application.
- DartParser
- A parser for Dart configuration files in Jetleaf.
- EnvParser
-
Parses dotenv (
.env) style files into aMap<String, dynamic>. - JsonParser
- A parser for JSON configuration files.
- NestedPlaceholderPart
- A PlaceholderPart that represents a nested placeholder expression with optional fallback.
- PackageUtils
- Utility class for resolving and caching Dart packages at runtime.
- Parser
- A base interface for all configuration parsers in Jetleaf.
- PlaceholderAbstractPart
- Base class for all PlaceholderPart implementations that represent a segment of a parsed placeholder expression.
- PlaceholderParsedSection
-
Represents a parsed section of a placeholder string,
typically extracted from a raw placeholder like
#{key:default}. - PlaceholderParsedValue
-
A container for a parsed text and its constituent
Partobjects. - PlaceholderParser
- A utility class for parsing and resolving placeholders within a string.
- PlaceholderPart
- Represents a segment or fragment of a placeholder expression.
- PlaceholderPartResolutionContext
- A resolution context for placeholder expressions, providing configuration, resolution logic, and tracking for visited placeholders.
- PlaceholderResolver
- Strategy interface for resolving placeholder values in configuration strings.
- PlaceholderTextPart
- A PlaceholderPart implementation that represents literal, already-resolved text within a placeholder expression.
- PropertiesParser
- A parser for Java-style properties files.
- PropertyPlaceholderHelper
-
A utility class for resolving string values that contain placeholders
in the format
#{name}. - SimplePlaceholderPart
- A PlaceholderPart that represents a basic placeholder expression with an optional fallback.
- StackTraceParser
- A comprehensive stack trace parsing utility for Jetleaf applications.
- StringUtils
-
🚀
StringUtils— A collection of common string manipulation utilities. - SystemPropertyPlaceholderResolver
- A PlaceholderResolver implementation that resolves placeholders using system properties and environment variables.
- SystemPropertyUtils
-
Utility class for resolving
#{...}-style placeholders within strings using system properties or environment variables. - TraceFrame
- Represents a single structured entry in a Jetleaf stack trace.
- TraceMapping
- A structured representation of a complete stack trace with analysis capabilities.
- XmlParser
- A parser for XML configuration files.
- YamlParser
- A parser for YAML configuration files.
Extensions
- PlaceholderResolverExtension on PlaceholderResolverFn
- Extension to provide a method-style interface on PlaceholderResolverFn functions.
Typedefs
- PlaceholderResolverFn = String? Function(String placeholderName)
Exceptions / Errors
- ParserException
- Exception thrown when parsing fails.
- PlaceholderResolutionException
- Exception thrown when placeholder resolution fails.