### Example import statement

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Example of importing the core.widgets library, which is one of the local widget libraries shipped with the package.

```plaintext
import core.widgets;

```

--------------------------------

### start

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/start.html

The start property returns the SourceLocation that marks the beginning of the range. It is a final field, so it cannot be modified after initialization.

```APIDOC
## start

### Description
The start property returns the SourceLocation that marks the beginning of a contiguous region in a source file. This region corresponds to a particular BlobNode, and the range contains the start.

### Property
- **Type**: SourceLocation
- **Modifier**: final

### Implementation
```dart
final SourceLocation start;
```

### Usage
Access the start location of a SourceRange instance.

### Example
```dart
SourceRange range = ...;
SourceLocation startLocation = range.start;
```
```

--------------------------------

### Encoded bytes for the switch example

Source: https://pub.dev/documentation/rfw/latest/rfw/decodeLibraryBlob.html

Shows the exact byte sequence that encodes the switch example above, including the switch tag and all data. The bytes are grouped in rows of 8 for readability.

```text
content_copy0F 0A 01 00 00 00 00  00 00 61 03 00 00 00 00
00 00 00 02 00 00 00 00  00 00 00 00 04 01 00 00
00 00 00 00 00 7A 02 01  00 00 00 00 00 00 00 04
01 00 00 00 00 00 00 00  6F 10 04 01 00 00 00 00
00 00 00 64

```

--------------------------------

### Button widget with state and animation

Source: https://pub.dev/documentation/rfw/latest/index.html

Example of a Button widget in the remote_widget_libraries example that tracks a local 'down' state, reacts to onTapDown/onTapUp/onTapCancel events, and changes its shadow and margins based on the state. Uses AnimatedContainer (via Container) with a duration of 50ms for smooth animation.

```rfwtxt
widget Button { down: false } = GestureDetector(
  onTap: args.onPressed,
  onTapDown: set state.down = true,
  onTapUp: set state.down = false,
  onTapCancel: set state.down = false,
  child: Container(
    duration: 50,
    margin: switch state.down {
      false: [ 0.0, 0.0, 2.0, 2.0 ],
      true: [ 2.0, 2.0, 0.0, 0.0 ],
    },
    padding: [ 12.0, 8.0 ],
    decoration: {
      type: "shape",
      shape: {
        type: "stadium",
        side: { width: 1.0 },
      },
      gradient: {
        type: "linear",
        begin: { x: -0.5, y: -0.25 },
        end: { x: 0.0, y: 0.5 },
        colors: [ 0xFFFFFF99, 0xFFEEDD00 ],
        stops: [ 0.0, 1.0 ],
        tileMode: "mirror",
      },
      shadows: switch state.down {
        false: [ { blurRadius: 4.0, spreadRadius: 0.5, offset: { x: 1.0, y: 1.0, } } ],
        default: [],
      },
    },
    child: DefaultTextStyle(
      style: {
        color: 0xFF000000,
        fontSize: 32.0,
      },
      child: args.child,
    ),
  ),
);

```

--------------------------------

### Implementation with assertions: assert source consistency and ordering

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/SourceRange.html

Initializes this.start and this.end, with assertions that the source objects match and that start is before end.

```dart
SourceRange(this.start, this.end)
 : assert(start.source == end.source, 'The start and end locations have inconsistent source information.'),
   assert(start < end, 'The start location must be before the end location.');
```

--------------------------------

### start property implementation

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/start.html

Declares the final SourceLocation start property. It is part of the SourceRange class and marks the beginning of a contiguous source region.

```dart
content_copyfinal SourceLocation start;
```

--------------------------------

### start → SourceLocation

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange-class.html

The start of a contiguous region of a source file that corresponds to a particular BlobNode.

```APIDOC
## start → SourceLocation

### Description
The start of a contiguous region of a source file that corresponds to a particular BlobNode.

### Type
SourceLocation

### Remarks
This property is final and immutable.
```

--------------------------------

### Elaborate Widget Argument Example

Source: https://pub.dev/documentation/rfw/latest/index.html

Shows a widget argument with a nested map and list structure, demonstrating how to pass complex data to a widget.

```dart
widget fruit = Foo(
  bar: { quux: [ 'apple', 'banana', 'cherry' ] },
);
```

--------------------------------

### SourceRange constructor

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/SourceRange.html

Creates a SourceRange object with the given start and end SourceLocation objects. The start and end must have identical source objects and the start must be before the end.

```APIDOC
## SourceRange constructor

### Description
Creates a SourceRange object with the given start and end SourceLocation objects. The start and end locations are initialized from the given arguments and must have identical SourceLocation.source objects. The start location must be before the end location.

### Method
Constructor

### Signature
```dart
SourceRange(
  SourceLocation start,
  SourceLocation end
)
```

### Parameters
- **start** (SourceLocation) - Required - The starting location of the range.
- **end** (SourceLocation) - Required - The ending location of the range.

### Implementation
```dart
SourceRange(this.start, this.end)
 : assert(start.source == end.source, 'The start and end locations have inconsistent source information.'),
   assert(start < end, 'The start location must be before the end location.');
```

```

--------------------------------

### Data Structure for Reference Example

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

A sample data structure used to illustrate how references index into maps and lists. The comment shows that foo.2.fruit resolves to the string "Kiwi".

```dart
content_copy{
  foo: [
    { fruit: "Apple" },
    { fruit: "Banana" },
    { fruit: "Kiwi" }, // foo.2.fruit is the string "Kiwi" here
  ],
  bar: [ ],
}

```

--------------------------------

### Constructor signature: SourceRange(SourceLocation start, SourceLocation end)

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/SourceRange.html

Declares the SourceRange constructor parameters. The start and end locations must have identical SourceLocation.source objects.

```dart
SourceRange(
  1. SourceLocation start, 
  2. SourceLocation end

)
```

--------------------------------

### Switch example in RFW DSL

Source: https://pub.dev/documentation/rfw/latest/rfw/decodeLibraryBlob.html

Shows a switch statement in the RFW DSL that maps input values to outputs, with a default case. The switch is encoded as described in the surrounding text.

```text
content_copyswitch (args.a) {
 0: 'z',
 1: 'o',
 default: 'd',
}

```

--------------------------------

### imports property

Source: https://pub.dev/documentation/rfw/latest/rfw/RemoteWidgetLibrary-class.html

Gets the list of libraries that this library depends on.

```APIDOC
## imports → List<Import>

### Description
The list of libraries that this library depends on.

### Type
List<Import>

### Remarks
This property is final and has no setter.
```

--------------------------------

### Examples of using isMap with map or scalar values

Source: https://pub.dev/documentation/rfw/latest/index.html

Two equivalent widget definitions using the 'Foo' widget with 'bar' as a String or a map with a 'name' key. Both produce the same result.

```dart
widget example1 = GreenBox(
  child: Foo(
    bar: 'Jean',
  ),
);

```

```dart
widget example2 = GreenBox(
  child: Foo(
    bar: { name: 'Jean' },
  ),
);

```

--------------------------------

### Render remote widgets with RemoteWidget in Flutter

Source: https://pub.dev/documentation/rfw/latest/index.html

A complete Flutter StatefulWidget example that renders a remote widget library. It hardcodes the remote widgets and data for demonstration, but in production these would come from a server. The example shows how to set up the Runtime and DynamicContent, parse a remote widget library, and handle events via the onEvent callback.

```dart
class Example extends StatefulWidget {
  const Example({super.key});

  @override
  State<Example> createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  final Runtime _runtime = Runtime();
  final DynamicContent _data = DynamicContent();

  // Normally this would be obtained dynamically, but for this example
  // we hard-code the "remote" widgets into the app.
  //
  // Also, normally we would decode this with [decodeLibraryBlob] rather than
  // parsing the text version using [parseLibraryFile]. However, to make it
  // easier to demo, this uses the slower text format.
  static final RemoteWidgetLibrary _remoteWidgets = parseLibraryFile('''
    // The "import" keyword is used to specify dependencies, in this case,
    // the built-in widgets that are added by initState below.
    import core.widgets;
    // The "widget" keyword is used to define a new widget constructor.
    // The "root" widget is specified as the one to render in the build
    // method below.
    widget root = Container(
      color: 0xFF002211,
      child: Center(
        child: Text(text: ["Hello, ", data.greet.name, "!"], textDirection: "ltr"),
      ),
    );
  ''');

  static const LibraryName coreName = LibraryName(<String>['core', 'widgets']);
  static const LibraryName mainName = LibraryName(<String>['main']);

  @override
  void initState() {
    super.initState();
    // Local widget library:
    _runtime.update(coreName, createCoreWidgets());
    // Remote widget library:
    _runtime.update(mainName, _remoteWidgets);
    // Configuration data:
    _data.update('greet', <String, Object>{'name': 'World'});
  }

  @override
  Widget build(BuildContext context) {
    return RemoteWidget(
      runtime: _runtime,
      data: _data,
      widget: const FullyQualifiedWidgetName(mainName, 'root'),
      onEvent: (String name, DynamicMap arguments) {
        // The example above does not have any way to trigger events, but if it
        // did, they would result in this callback being invoked.
        debugPrint('user triggered event "$name" with data: $arguments');
      },
    );
  }
}

```

--------------------------------

### Example of using length with a list of strings

Source: https://pub.dev/documentation/rfw/latest/index.html

Creates a GreenBox with a Foo widget that has a 'text' list containing two strings. This demonstrates how the length method is used with a list.

```dart
widget example3 = GreenBox(
  child: Foo(
    text: ['apple', 'banana']
  ),
);

```

--------------------------------

### isList implementation

Source: https://pub.dev/documentation/rfw/latest/rfw/DataSource/isList.html

Implementation example of the isList method returning a bool based on the given key.

```dart
content_copybool isList(List<Object> argsKey);
```

--------------------------------

### Example StatefulWidget with LocalWidgetLibrary and Runtime Update

Source: https://pub.dev/documentation/rfw/latest/index.html

Defines a StatefulWidget that creates a local widget library with 'GreenBox' and 'Hello' widgets. It uses the reassemble method to update the runtime on hot reload, and parses a remote library string to demonstrate usage.

```dart
class Example extends StatefulWidget {
  const Example({super.key});

  @override
  State<Example> createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  final Runtime _runtime = Runtime();
  final DynamicContent _data = DynamicContent();

  @override
  void initState() {
    super.initState();
    _update();
  }

  @override
  void reassemble() {
    // This function causes the Runtime to be updated any time the app is
    // hot reloaded, so that changes to _createLocalWidgets can be seen
    // during development. This function has no effect in production.
    super.reassemble();
    _update();
  }

  static WidgetLibrary _createLocalWidgets() {
    return LocalWidgetLibrary(<String, LocalWidgetBuilder>{
      'GreenBox': (BuildContext context, DataSource source) {
        return ColoredBox(color: const Color(0xFF002211), child: source.child(<Object>['child']));
      },
      'Hello': (BuildContext context, DataSource source) {
        return Center(
          child: Text(
            'Hello, ${source.v<String>(<Object>["name"])}!',
            textDirection: TextDirection.ltr,
          ),
        );
      },
    });
  }

  static const LibraryName localName = LibraryName(<String>['local']);
  static const LibraryName remoteName = LibraryName(<String>['remote']);

  void _update() {
    _runtime.update(localName, _createLocalWidgets());
    // Normally we would obtain the remote widget library in binary form from a
    // server, and decode it with [decodeLibraryBlob] rather than parsing the
    // text version using [parseLibraryFile]. However, to make it easier to
    // play with this sample, this uses the slower text format.
    _runtime.update(
      remoteName,
      parseLibraryFile('''
      import local;
      widget root = GreenBox(
        child: Hello(name: "World"),
      );
    '''),
    );
  }

  @override
  Widget build(BuildContext context) {
    return RemoteWidget(
      runtime: _runtime,
      data: _data,
      widget: const FullyQualifiedWidgetName(remoteName, 'root'),
      onEvent: (String name, DynamicMap arguments) {
        debugPrint('user triggered event "$name" with data: $arguments');
      },
    );
  }
}
```

--------------------------------

### Structured Argument Reference Example

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Shows how to reference a leaf node in a structured argument. The argument 'show' contains a map with 'name' and 'phrase'; the reference args.show.phrase accesses the string "Bobbins".

```dart
content_copyFoo(show: { name: "Cracking the Cryptic", phrase: "Bobbins" })

```

```dart
content_copywidget Foo = Text(text: args.show.phrase);

```

--------------------------------

### Argument Reference Example

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Shows how to pass a reference to an argument of the remote widget being defined. The widget Foo passes the value of its 'name' argument to a Text widget.

```dart
content_copyFoo(name: "Bobbins")

```

```dart
content_copywidget Foo = Text(text: args.name);

```

--------------------------------

### Nested Widget Builders Example

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Shows how to nest Builder widgets to access arguments, state, data, and outer builder arguments. The innermost Text widget references all available scopes: args, state, data, and the builder arguments foo, bar, baz.

```dart
content_copywidget Foo {text: 'this is cool'} = Builder(
  builder: (foo) => Builder(
    builder: (bar) => Builder(
      builder: (baz) => Text(
        text: [
          args.text,
          state.text,
          data.text,
          foo.text,
          bar.text,
          baz.text,
        ],
      ),
    ),
  ),
);

```

--------------------------------

### Sample JSON data for remote widget library

Source: https://pub.dev/documentation/rfw/latest/index.html

Example data structure for a remote widget library, showing a list of games with attributes like rating, name, and rank. This data is valid JSON and RFW data file, parsed by parseDataFile into a DynamicMap.

```json
content_copy{ "games": [
{"rating": 8.219, "users-rated": 16860, "name": "Twilight Struggle", "rank": 1, "link": "/boardgame/12333/twilight-struggle", "id": 12333},
{"rating": 8.093, "users-rated": 11750, "name": "Through the Ages: A Story of Civilization", "rank": 2, "link": "/boardgame/25613/through-ages-story-civilization", "id": 25613},
{"rating": 8.088, "users-rated": 34745, "name": "Agricola", "rank": 3, "link": "/boardgame/31260/agricola", "id": 31260},
{"rating": 8.082, "users-rated": 8913, "name": "Terra Mystica", "rank": 4, "link": "/boardgame/120677/terra-mystica", "id": 120677},
// ···

```

--------------------------------

### Data Model Reference Example

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Shows how to reference a leaf node in the data model tree. The data model is a map with a 'server' key containing a list of maps; the reference data.server.cart.1.name accesses the string "Banana".

```dart
content_copy{ server: { cart: [ { name: "Apple"}, { name: "Banana"} ] }

```

```dart
content_copyText(text: data.server.cart.1.name)

```

--------------------------------

### int get hashCode

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/hashCode.html

Returns the hash code for this SourceRange object. The hash code is computed from the start and end properties, and must be consistent with the equality operator.

```APIDOC
## int get hashCode

### Description
Returns the hash code for this SourceRange object. The hash code is computed from the start and end properties, and must be consistent with the equality operator.

### Method
get

### Property
hashCode

### Return Value
- **int** - The hash code for this object.

### Implementation
```dart
@override
int get hashCode => Object.hash(start, end);
```

### Remarks
- The hash code must be the same for objects that are equal according to operator ==.
- The hash code should only change if the object changes in a way that affects equality.
- If a subclass overrides hashCode, it should also override operator == to maintain consistency.
```

--------------------------------

### childList(List<Object> argsKey) → List<Widget>

Source: https://pub.dev/documentation/rfw/latest/rfw/DataSource-class.html

Builds the children at the given key.

```APIDOC
## childList(List<Object> argsKey) → List<Widget>

### Description
Builds the children at the given key.

### Method
childList

### Parameters
- **argsKey** (List<Object>) - Required - The list of keys forming a path to the node in the arguments.

### Returns
- **List<Widget>** - The list of built child widgets.
```

--------------------------------

### Import constructor

Source: https://pub.dev/documentation/rfw/latest/rfw/Import/Import.html

Creates an Import object that wraps the given library name.

```APIDOC
## Import constructor

### Description
Wraps the given library `name` in an Import object.

### Constructor
`const Import(LibraryName name)`

### Parameters
- **name** (LibraryName) - Required - The library name to wrap.

### Implementation
```dart
const Import(this.name);
```
```

--------------------------------

### Signalling event handler example: Button with onPressed

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Example of a signalling event handler in a Button widget. The onPressed handler sends the event "hello" with a map containing one key "id" set to 1.

```dart
Button(
  onPressed: event "hello" { id: 1 },
  child: Text(text: "Greetings"),
);
```

--------------------------------

### SourceLocation(Object source, int offset)

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceLocation/SourceLocation.html

Creates a SourceLocation object with the given source and offset. The source and offset properties are initialized from the arguments.

```APIDOC
## SourceLocation(Object source, int offset)

### Description
Creates a SourceLocation object with the given source and offset. The source and offset properties are initialized from the arguments.

### Constructor
`const SourceLocation(Object source, int offset)`

### Parameters
- **source** (Object) - Required - The source object for the location.
- **offset** (int) - Required - The offset within the source.

### Implementation
```dart
const SourceLocation(this.source, this.offset);
```
```

--------------------------------

### RemoteWidgetLibrary.new

Source: https://pub.dev/documentation/rfw/latest/rfw/RemoteWidgetLibrary/RemoteWidgetLibrary.html

Creates a RemoteWidgetLibrary instance with the given imports and widgets lists. The lists must not be mutated after the library is created.

```APIDOC
## RemoteWidgetLibrary.new

### Description
Wraps a set of `imports` and `widgets` (widget declarations) in a RemoteWidgetLibrary object. The provided lists must not be mutated once the library is created.

### Constructor
```dart
const RemoteWidgetLibrary(
  List<Import> imports,
  List<WidgetDeclaration> widgets
)
```

### Parameters
- **imports** (List<Import>) - Required - The list of imports to include in the library.
- **widgets** (List<WidgetDeclaration>) - Required - The list of widget declarations to include in the library.

### Implementation
```dart
const RemoteWidgetLibrary(this.imports, this.widgets);
```
```

--------------------------------

### Switch.new

Source: https://pub.dev/documentation/rfw/latest/rfw/Switch/Switch.html

Creates a Switch with the given input and outputs. The provided objects must not be mutated after being given to the constructor.

```APIDOC
## Switch.new

### Description
Creates a Switch with the given `input` and `outputs`. The provided objects must not be mutated after being given to the constructor. In particular, changing the `outputs` map after creating the Switch is an error.

### Constructor
`const Switch(Object input, Map<Object?, Object> outputs)`

### Parameters
- **input** (Object) - Required - The input object for the Switch.
- **outputs** (Map<Object?, Object>) - Required - A map of outputs for the Switch.

### Implementation
```dart
const Switch(this.input, this.outputs);
```
```

--------------------------------

### BNF: identifier production

Source: https://pub.dev/documentation/rfw/latest/formats/parseDataFile.html

Identifiers are alphanumeric sequences (with underscore considered a letter) that do not start with a digit.

```bnf
identifier ::= letter ( letter | digit )*
letter ::= <a character in the ranges A-Z, a-z, or the underscore>
digit ::= <a character in the range 0-9>
```

--------------------------------

### Runtime()

Source: https://pub.dev/documentation/rfw/latest/rfw/Runtime-class.html

Creates a new Runtime object.

```APIDOC
## Runtime()

### Description
Creates a new Runtime object.

### Constructor
Runtime()

### Parameters
None.

### Returns
A new Runtime instance.
```

--------------------------------

### LibraryName constructor

Source: https://pub.dev/documentation/rfw/latest/rfw/LibraryName-class.html

Creates a LibraryName instance by wrapping the given list of string parts.

```APIDOC
## LibraryName(List<String> parts)

### Description
Wrap the given list as a LibraryName. The list represents the components of the library name, e.g., ['core', 'widgets'] for 'core.widgets'.

### Constructor
LibraryName(List<String> parts)

### Parameters
- **parts** (List<String>) - Required - The components of the structured library name.

### Example
```dart
LibraryName name = LibraryName(['core', 'widgets']);
```
```

--------------------------------

### message → String

Source: https://pub.dev/documentation/rfw/latest/rfw/ParserException-class.html

Gets the human-readable error message that was detected by the parser. This property is final.

```APIDOC
## message → String

### Description
Returns the error that was detected by the parser as a human-readable string.

### Property
`final String message`

### Returns
- **String** - The error message.
```

--------------------------------

### child(List<Object> argsKey)

Source: https://pub.dev/documentation/rfw/latest/rfw/DataSource/child.html

Builds the child widget at the given key. If the node is not a widget, returns an ErrorWidget.

```APIDOC
## child(List<Object> argsKey)

### Description
Builds the child at the given key. If the node specified is not a widget, returns an ErrorWidget.

### Method
Abstract method

### Signature
```dart
Widget child(List<Object> argsKey);
```

### Parameters
- **argsKey** (List<Object>) - Required - The key of the child to build.

### Returns
- **Widget** - The built child widget, or an ErrorWidget if the node is not a widget.

### See Also
- **optionalChild** - Returns null if the widget is missing.
```

--------------------------------

### int get hashCode

Source: https://pub.dev/documentation/rfw/latest/rfw/LibraryName/hashCode.html

Returns the hash code for this object. The implementation uses Object.hashAll on the parts of the object.

```APIDOC
## int get hashCode

### Description
Returns the hash code for this object. The hash code is a single integer representing the state of the object that affects operator == comparisons. It must be consistent with equality: equal objects must have the same hash code.

### Method
GET

### Endpoint
`hashCode` (property getter)

### Parameters
None

### Implementation
```dart
@override
int get hashCode => Object.hashAll(parts);
```

### Returns
- **int** - The hash code for this object.

### Notes
- The hash code should only change if the object changes in a way that affects equality.
- If a subclass overrides hashCode, it should also override operator == to maintain consistency.
```

--------------------------------

### source

Source: https://pub.dev/documentation/rfw/latest/rfw/BlobNode/source.html

Gets the source location that corresponds to this BlobNode, if known. Returns null if no source location is associated.

```APIDOC
## source

### Description
Gets the source location that corresponds to this BlobNode, if known. Returns null if no source location is associated.

### Method
get

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **source** (SourceRange?) - The source location of this BlobNode, or null if unknown.

#### Response Example
```dart
SourceRange? source = blobNode.source;
```

### Implementation
```dart
SourceRange? get source {
  return _sources[this];
}
```
```

--------------------------------

### compareTo(FullyQualifiedWidgetName other)

Source: https://pub.dev/documentation/rfw/latest/rfw/FullyQualifiedWidgetName/compareTo.html

Compares this FullyQualifiedWidgetName to another. Returns a negative integer if this is ordered before other, a positive integer if after, and zero if equal. The comparison is performed by first comparing the library fields, and if they are equal, comparing the widget fields.

```APIDOC
## compareTo(FullyQualifiedWidgetName other)

### Description
Compares this object to another object. Returns a value like a Comparator when comparing `this` to `other`. That is, it returns a negative integer if `this` is ordered before `other`, a positive integer if `this` is ordered after `other`, and zero if `this` and `other` are ordered together. The `other` argument must be a value that is comparable to this object.

### Method
compareTo

### Signature
`int compareTo(FullyQualifiedWidgetName other)`

### Parameters
#### Parameters
- **other** (FullyQualifiedWidgetName) - Required - The object to compare with this object.

### Return Value
- **int** - A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

### Implementation
```dart
@override
int compareTo(FullyQualifiedWidgetName other) {
  final int result = library.compareTo(other.library);
  if (result != 0) {
    return result;
  }
  return widget.compareTo(other.widget);
}
```
```

--------------------------------

### line → int

Source: https://pub.dev/documentation/rfw/latest/rfw/ParserException-class.html

Gets the line number (1-based) that the parser had reached when the error was detected. This property is final.

```APIDOC
## line → int

### Description
Returns the line number (using 1-based indexing) that the parser had reached when the error was detected.

### Property
`final int line`

### Returns
- **int** - The line number.
```

--------------------------------

### column → int

Source: https://pub.dev/documentation/rfw/latest/rfw/ParserException-class.html

Gets the column number (1-based) that the parser had reached when the error was detected. This property is final.

```APIDOC
## column → int

### Description
Returns the column number (using 1-based indexing) that the parser had reached when the error was detected.

### Property
`final int column`

### Returns
- **int** - The column number.
```

--------------------------------

### handler<T extends Function>(List<Object> argsKey, HandlerGenerator<T> generator) → T?

Source: https://pub.dev/documentation/rfw/latest/rfw/DataSource-class.html

Gets an event handler at the given key.

```APIDOC
## handler<T extends Function>(List<Object> argsKey, HandlerGenerator<T> generator) → T?

### Description
Gets an event handler at the given key.

### Method
handler

### Type Parameters
- **T** (Function) - The type of the handler function.

### Parameters
- **argsKey** (List<Object>) - Required - The list of keys forming a path to the node in the arguments.
- **generator** (HandlerGenerator<T>) - Required - The generator for the handler.

### Returns
- **T?** - The event handler, or null if not found.
```

--------------------------------

### LocalWidgetLibrary class

Source: https://pub.dev/documentation/rfw/latest/rfw/LocalWidgetLibrary-class.html

Documentation for the LocalWidgetLibrary class constructor and its findConstructor method.

```APIDOC
## LocalWidgetLibrary(Map<String, LocalWidgetBuilder> _widgets)

### Description
Creates a LocalWidgetLibrary instance with the given map of widget builders.

### Constructor
`LocalWidgetLibrary(Map<String, LocalWidgetBuilder> _widgets)`

### Parameters
- `_widgets` (Map<String, LocalWidgetBuilder>) - Required - The map of widget names to their builders.

```

```APIDOC
## findConstructor(String name) → LocalWidgetBuilder?

### Description
Returns the builder for the widget of the given name, if any.

### Method
`LocalWidgetBuilder? findConstructor(String name)`

### Parameters
- `name` (String) - Required - The name of the widget to look up.

### Returns
- `LocalWidgetBuilder?` - The builder for the widget, or null if not found.

```

--------------------------------

### duration method implementation

Source: https://pub.dev/documentation/rfw/latest/rfw/ArgumentDecoders/duration.html

Implementation of duration static method. It retrieves an integer from the DataSource; if null, uses AnimationDefaults.durationOf to get the default Duration.

```dart
static Duration duration(DataSource source, List<Object> key, BuildContext context) {
  final int? value = source.v<int>(key);
  if (value == null) {
    return AnimationDefaults.durationOf(context);
  }
  return Duration(milliseconds: value);
}
```

--------------------------------

### createCoreWidgets implementation

Source: https://pub.dev/documentation/rfw/latest/rfw/createCoreWidgets.html

Returns a LocalWidgetLibrary constructed from _coreWidgetsDefinitions.

```dart
LocalWidgetLibrary createCoreWidgets() => LocalWidgetLibrary(_coreWidgetsDefinitions);
```

--------------------------------

### Loop with subreferences in template

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Shows a more elaborate loop example where the template uses subreferences like `product.name.displayName`. The widget is used with a list of product maps.

```dart
widget Items = ListView(
  children: [
    Text(text: 'Products:'),
    ...for item in args.products:
      Text(text: product.name.displayName),
    Text(text: 'End of list.'),
  ],
);

```

```dart
Items(products: [
  { name: { abbreviation: "TI4", displayName: "Twilight Imperium IV" }, price: 120.0 },
  { name: { abbreviation: "POK", displayName: "Prophecy of Kings" }, price: 100.0 },
])

```

--------------------------------

### Dart toString override example

Source: https://pub.dev/documentation/rfw/latest/rfw/ConstructorCall/toString.html

Overrides toString to return a string in the format '$name($arguments)'. This is useful for debugging or logging when the default representation is not meaningful.

```dart
@override
String toString() => '$name($arguments)';
```

--------------------------------

### FullyQualifiedWidgetName(LibraryName library, String widget)

Source: https://pub.dev/documentation/rfw/latest/rfw/FullyQualifiedWidgetName-class.html

Constructs a FullyQualifiedWidgetName by wrapping the given library name and widget name. This is a const constructor.

```APIDOC
## FullyQualifiedWidgetName(LibraryName library, String widget)

### Description
Constructs a FullyQualifiedWidgetName by wrapping the given library name and widget name. This is a const constructor.

### Constructor
FullyQualifiedWidgetName(LibraryName library, String widget)

### Parameters
- **library** (LibraryName) - Required - The name of the library in which the widget can be found.
- **widget** (String) - Required - The name of the widget, which should be in the specified library.

```

--------------------------------

### widgets

Source: https://pub.dev/documentation/rfw/latest/rfw/LocalWidgetLibrary/widgets.html

Gets the widgets defined by this LocalWidgetLibrary as an immutable map view. The map is unmodifiable and contains unqualified widget names mapped to LocalWidgetBuilder instances.

```APIDOC
## GETTER widgets

### Description
Returns an immutable view of the map of local widgets defined by this LocalWidgetLibrary. The map keys are unqualified widget names and the values are the corresponding LocalWidgetBuilder instances. The map never changes during the lifetime of the library, but a new UnmodifiableMapView instance is returned each time this getter is used.

### Return Type
UnmodifiableMapView<String, LocalWidgetBuilder>

### Parameters
None

### Example
```dart
UnmodifiableMapView<String, LocalWidgetBuilder> widgets = library.widgets;
```

### See Also
- createCoreWidgets, a function that creates a Map of local widgets.

### Implementation
```dart
UnmodifiableMapView<String, LocalWidgetBuilder> get widgets {
  return UnmodifiableMapView<String, LocalWidgetBuilder>(_widgets);
}
```
```

--------------------------------

### builder(List<Object> argsKey, DynamicMap builderArg) → Widget

Source: https://pub.dev/documentation/rfw/latest/rfw/DataSource-class.html

Builds the widget builder at the given key.

```APIDOC
## builder(List<Object> argsKey, DynamicMap builderArg) → Widget

### Description
Builds the widget builder at the given key.

### Method
builder

### Parameters
- **argsKey** (List<Object>) - Required - The list of keys forming a path to the node in the arguments.
- **builderArg** (DynamicMap) - Required - The builder arguments.

### Returns
- **Widget** - The built widget.
```

--------------------------------

### int get hashCode

Source: https://pub.dev/documentation/rfw/latest/rfw/FullyQualifiedWidgetName/hashCode.html

Returns the hash code for this FullyQualifiedWidgetName object, computed from the library and widget fields. This override ensures consistency with the equality operator.

```APIDOC
## int get hashCode

### Description
Returns the hash code for this object, based on the `library` and `widget` fields. This override ensures that equal objects have the same hash code, maintaining consistency with the `operator ==` implementation.

### Method
Getter

### Property
`int get hashCode`

### Override
This getter overrides the default `Object.hashCode` implementation.

### Implementation
```dart
@override
int get hashCode => Object.hash(library, widget);
```

### Notes
- The hash code is derived from the `library` and `widget` properties.
- It must be consistent with the `operator ==` implementation.
- The hash code may change if the object's state changes, but should remain consistent within a single execution.
```

--------------------------------

### LocalWidgetLibrary constructor

Source: https://pub.dev/documentation/rfw/latest/rfw/LocalWidgetLibrary/LocalWidgetLibrary.html

Creates a LocalWidgetLibrary instance with the given map of widget builders. The map must not change after construction.

```APIDOC
## LocalWidgetLibrary constructor

### Description
Creates a LocalWidgetLibrary instance with the given map of widget builders. The map must not change after construction.

### Method
Constructor

### Signature
LocalWidgetLibrary(Map<String, LocalWidgetBuilder> _widgets)

### Parameters
- **_widgets** (Map<String, LocalWidgetBuilder>) - Required - The map of widget builders. Must not change after creation.

### Implementation
```dart
LocalWidgetLibrary(this._widgets);
```
```

--------------------------------

### Loop.new

Source: https://pub.dev/documentation/rfw/latest/rfw/Loop/Loop.html

Creates a Loop with the given input and output objects. The provided objects must not be mutated after being passed to the constructor.

```APIDOC
## Loop.new

### Description
Creates a Loop with the given `input` and `output` objects. The provided objects must not be mutated after being given to the constructor (e.g. the ownership of any lists and maps passes to this object).

### Constructor
`const Loop(Object input, Object output)`

### Parameters
- **input** (Object) - Required - The input object for the Loop.
- **output** (Object) - Required - The output object for the Loop.

### Implementation
```dart
const Loop(this.input, this.output);
```
```

--------------------------------

### Widget with initial state declaration

Source: https://pub.dev/documentation/rfw/latest/formats/parseLibraryFile.html

Shows a widget declaration with an initial state `down: false`. The state is used in the widget's child, but the example is noted as nonsensical.

```dart
widget Button { down: false } = Container(
  // ...
);

```

```dart
widget Button { down: false } = Container(
  child: Text(text: 'Hello World', softWrap: state.down),
);

```

--------------------------------

### string(DataSource source, List<Object> key) → String

Source: https://pub.dev/documentation/rfw/latest/rfw/ArgumentDecoders-class.html

Returns a string from the specified string.

```APIDOC
## string(DataSource source, List<Object> key) → String

### Description
Returns a string from the specified string.

### Method
Static method

### Parameters
- **source** (DataSource) - Required - The data source to read from.
- **key** (List<Object>) - Required - The key path to the value.

### Returns
String - The decoded string.
```

--------------------------------

### Override createState for SomeWidget

Source: https://pub.dev/documentation/rfw/latest/rfw/RemoteWidget/createState.html

Example of overriding createState to return a new instance of the associated State subclass. The framework calls this method each time the widget is inserted into the tree.

```dart
@override
State<SomeWidget> createState() => _SomeWidgetState();

```

--------------------------------

### decorationImage(DataSource source, List<Object> key)

Source: https://pub.dev/documentation/rfw/latest/rfw/ArgumentDecoders/decorationImage.html

Returns a DecorationImage from the specified map. The image is determined by interpreting the same key as per imageProvider. If that method returns null, then this returns null also. Otherwise, the return value is used as the provider and additional keys map to the identically-named properties of DecorationImage.

```APIDOC
## decorationImage(DataSource source, List<Object> key)

### Description
Returns a DecorationImage from the specified map. The DecorationImage.image is determined by interpreting the same key as per imageProvider. If that method returns null, then this returns null also. Otherwise, the return value is used as the provider and additional keys map to the identically-named properties of DecorationImage.

### Method
Static method

### Signature
```dart
static DecorationImage? decorationImage(DataSource source, List<Object> key)
```

### Parameters
- **source** (DataSource) - Required - The data source map from which to read the image configuration.
- **key** (List<Object>) - Required - The key path used to locate the image data in the source.

### Return Value
- **DecorationImage?** - A DecorationImage instance, or null if the image provider is null.

### Behavior
- The image provider is obtained by calling `imageProvider(source, key)`. If it returns null, the method returns null.
- Additional keys are interpreted as follows:
  - `onError` (event handler) - The payload map is augmented by an `exception` key containing the text serialization of the exception and a `stackTrace` key containing the stack trace as a string.
  - `colorFilter` (colorFilter) - The color filter for the image.
  - `fit` (enumValue of BoxFit) - The fit of the image.
  - `alignment` (alignment, defaults to Alignment.center) - The alignment of the image.
  - `centerSlice` (rect) - The center slice of the image.
  - `repeat` (enumValue of ImageRepeat, defaults to ImageRepeat.noRepeat) - The repeat behavior.
  - `matchTextDirection` (boolean, defaults to false) - Whether to match text direction.
  - `filterQuality` (enumValue of FilterQuality, defaults to FilterQuality.medium) - The filter quality.

### Implementation
```dart
static DecorationImage? decorationImage(DataSource source, List<Object> key) {
  final ImageProvider? provider = imageProvider(source, key);
  if (provider == null) {
    return null;
  }
  return DecorationImage(
    image: provider,
    onError: (Object exception, StackTrace? stackTrace) {
      final VoidCallback? handler = source.voidHandler([...key, 'onError'], { 'exception': exception.toString(), 'stackTrack': stackTrace.toString() });
      if (handler != null) {
        handler();
      }
    },
    colorFilter: colorFilter(source, [...key, 'colorFilter']),
    fit: enumValue<BoxFit>(BoxFit.values, source, [...key, 'fit']),
    alignment: alignment(source, [...key, 'alignment']) ?? Alignment.center,
    centerSlice: rect(source, [...key, 'centerSlice']),
    repeat: enumValue<ImageRepeat>(ImageRepeat.values, source, [...key, 'repeat']) ?? ImageRepeat.noRepeat,
    matchTextDirection: source.v<bool>([...key, 'matchTextDirection']) ?? false,
    filterQuality: enumValue<FilterQuality>(FilterQuality.values, source, [...key, 'filterQuality']) ?? FilterQuality.medium,
  );
}
```
```

--------------------------------

### Using optionalChild to allow null child

Source: https://pub.dev/documentation/rfw/latest/index.html

Defines a GreenBox widget that uses the optionalChild method to get the child widget, which returns null if the key does not point to a widget.

```dart
'GreenBox': (BuildContext context, DataSource source) {
  return ColoredBox(color: const Color(0xFF002211), child: source.optionalChild(<Object>['child']));
},

```

--------------------------------

### StateReference(List<Object> parts)

Source: https://pub.dev/documentation/rfw/latest/rfw/StateReference-class.html

Constructs a StateReference wrapping the given parts. Each part must be a String or an integer.

```APIDOC
## StateReference(List<Object> parts)

### Description
Wraps the given `parts` as a StateReference. Each part must be either a String (to index into a DynamicMap) or an integer (to index into a DynamicList).

### Constructor
`StateReference(List<Object> parts)`

### Parameters
- **parts** (List<Object>) - Required - The components of the reference. Each entry must be either a String or an integer.

### Returns
A new StateReference instance.
```

--------------------------------

### SourceRange operator == implementation

Source: https://pub.dev/documentation/rfw/latest/rfw/SourceRange/operator_equals.html

Overrides the equality operator to compare SourceRange instances by their start and end fields. Returns false if the runtime type of `other` is not SourceRange. Must be consistent with hashCode.

```dart
@override
bool operator ==(Object other) {
  if (other.runtimeType != SourceRange) {
    return false;
  }
  return other is SourceRange
      && start == other.start
      && end == other.end;
}
```

--------------------------------

### Override hashCode with Object.hashAll

Source: https://pub.dev/documentation/rfw/latest/rfw/LibraryName/hashCode.html

Example implementation of the hashCode getter that uses Object.hashAll to compute a hash code from the object's parts. This should be overridden when operator == is overridden to maintain consistency.

```dart
@override
int get hashCode => Object.hashAll(parts);
```

--------------------------------

### Implementation of Locale.locale static method

Source: https://pub.dev/documentation/rfw/latest/rfw/ArgumentDecoders/locale.html

This is the exact implementation of the static `locale` method. It retrieves a string from the given `DataSource` using the provided key, returns null if the value is null, and then splits the string on hyphens. Depending on the number of subtags, it returns a `Locale` using the one-argument, two-argument, or `Locale.fromSubtags` constructor. The method includes a TODO comment about verifying the correctness of the subtag handling.

```dart
static Locale? locale(DataSource source, List<Object> key) {
  final String? value = source.v<String>(key);
  if (value == null) {
    return null;
  }
  final List<String> subtags = value.split('-');
  if (subtags.isEmpty) {
    return null;
  }
  if (subtags.length == 1) {
    return Locale(value);
  }
  if (subtags.length == 2) {
    return Locale(subtags[0], subtags[1]);
  }
  // TODO(ianh): verify this is correct (I tried looking up the Unicode spec but it was... confusing)
  return Locale.fromSubtags(languageCode: subtags[0], scriptCode: subtags[1], countryCode: subtags[2]);
}
```

--------------------------------

### doubleOrZero(DataSource source, List<Object> key)

Source: https://pub.dev/documentation/rfw/latest/rfw/ArgumentDecoders/doubleOrZero.html

Returns a double from the specified DataSource. Returns 0.0 if the value is not a double. Useful when null is not acceptable, for example, when providing a decoder to a list.

```APIDOC
## doubleOrZero(DataSource source, List<Object> key)

### Description
Returns a double from the specified DataSource. Returns 0.0 if the value is not a double. Useful when null is not acceptable, for example, when providing a decoder to a list.

### Method
static method

### Signature
```dart
static double doubleOrZero(DataSource source, List<Object> key)
```

### Parameters
- **source** (DataSource) - The data source from which to read the value.
- **key** (List<Object>) - The key used to locate the value in the data source.

### Return Value
- **double** - The double value from the data source, or 0.0 if the value is not a double.

### Implementation
```dart
static double doubleOrZero(DataSource source, List<Object> key) {
  return source.v<double>(key) ?? 0.0;
}
```

```

--------------------------------

### build method implementation

Source: https://pub.dev/documentation/rfw/latest/rfw/Runtime/build.html

Implementation of the build method. It looks up a cached bound widget, creates one if not found, and returns the built widget. The method uses _checkForImportLoops and _applyConstructorAndBindArguments.

```dart
Widget build(
  BuildContext context,
  FullyQualifiedWidgetName widget,
  DynamicContent data,
  RemoteEventHandler remoteEventTarget,
) {
  _CurriedWidget? boundWidget = _widgets[widget];
  if (boundWidget == null) {
    _checkForImportLoops(widget.library);
    boundWidget = _applyConstructorAndBindArguments(
      widget,
      const <String, Object?>{},
      const <String, Object?>{},
      -1,
      <FullyQualifiedWidgetName>{},
      null,
    );
    _widgets[widget] = boundWidget;
  }
  return boundWidget.build(context, data, remoteEventTarget, const <_WidgetState>[]);
}
```