Represents a fully normalized and transport-safe view of arguments passed to an executable entity (constructor, method, function, or tear-off).
The ExecutableArgument interface abstracts away how arguments were originally supplied and exposes a stable representation consisting of:
- Ordered positional arguments
- Named arguments, keyed using both string names and symbol names
This abstraction is used throughout the JetLeaf runtime reflection and hint-processing pipeline to unify how arguments are captured, inspected, transformed, or re-invoked.
Purpose
Reflection APIs, hint systems, and runtime resolvers often need to:
- Reconstruct invocation contexts
- Forward argument sets to new execution paths (AOT, JIT, hints, or mirrors)
- Normalize arguments so that they can be serialized or compared
ExecutableArgument provides a single contract that allows all components in the system to work with argument collections safely and consistently.
Positional vs. Named Arguments
Positional arguments preserve the exact order in which the caller supplied them. Named arguments preserve:
- Their string name (preferred for userland reflection)
- Their symbol key (required for low-level
dart:mirrorsinvocation)
Implementations ensure that these two representations remain aligned.
Immutability & Consistency
While implementations may store arguments in any internal representation, callers should treat the returned collections as read-only snapshots. Runtime resolvers and hint processors rely on argument immutability to ensure deterministic behavior.
Creation
The static factory ExecutableArgument.unmodified constructs a normalized argument container used by most parts of the runtime system.
Example:
final args = ExecutableArgument.inEqualized(
{'count': 3},
[42, true],
);
print(args.getPositionalArguments()); // [42, true]
print(args.getNamedArguments()); // { 'count': 3 }
print(args.getSymbolizedNamedArguments());
// { #count: 3 }
Implementations (such as _UnmodifableExecutableArgument) must guarantee
that both the string-keyed and symbol-keyed named argument maps represent
the same underlying values.
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
getArgument(
Object object, [bool? fromNamed]) → Object? - Retrieves a single argument—either positional or named—based on the lookup value provided.
-
getNamedArguments(
) → Map< String, Object?> - Returns a map of named arguments keyed by their string names.
-
getPositionalArguments(
) → List< Object?> - Returns the list of positional arguments in the order they were provided to the original call site.
-
getSymbolizedNamedArguments(
) → Map< Symbol, Object?> - Returns a map of named arguments keyed using Symbol objects.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Methods
-
named(
Map< String, Object?> named) → ExecutableArgument - Creates an ExecutableArgument containing only named arguments.
-
none(
) → ExecutableArgument - Returns a singleton or empty representation of ExecutableArgument that contains no positional or named arguments.
-
optional(
{Map< String, Object?> ? named, List<Object?> ? positional}) → ExecutableArgument - Creates an ExecutableArgument with optional positional and named arguments, defaulting to empty collections when omitted.
-
positional(
List< Object?> positional) → ExecutableArgument - Creates an ExecutableArgument containing only positional arguments.
-
unmodified(
Map< String, Object?> named, List<Object?> positional) → ExecutableArgument - Creates an ExecutableArgument from explicitly supplied named and positional arguments, ensuring both representations are internally aligned and normalized.