omnibuild 0.2.2 omnibuild: ^0.2.2 copied to clipboard
Library and binary for processing Omnibus message specifications.
Omnibuild #
You can create an Omnibus messages specification in a YAML file and use the
omnibuild
executable to generate Dart code from this file. This executable
should be executed using the command below, note that the output directory
must have a trailing slash.
omnibuild -o <output directory> <input files>
Writing the YAML files #
An Omnibus messages specification file looks as follows:
# Copyright that should be applied to the output file.
copyright: Example copyright
# Library name these messages are included in.
library: message_library
# Extensive description (main code documentation)
description: |
General description of what the messages in this file do and in which
scenarios they should be used.
# Messages list
messages:
- name: MyMessage # Message name
type: event # _OmnibusMessageType (event, request, response)
note: Documentation # Message documentation
# Message properties
properties:
- name: impactFactor # Property name
note: Documentation # Property documentation
type: enum ImpactFactor # Property type, prefix with 'enum ' if it is an
# enumeration as shown here.
pass: named parameter # Positional or named parameter
dflt: ImpactFactor.high # Default value (abbreviated to four letters so all
# properties can be aligned nicely)
This example would result in the following code.
// Example copyright
// THIS FILE IS AUTO-GENERATED, PLEASE DO NOT MODIFY BY HAND.
part of message_library;
/// General description of what the messages in this file do and in which
/// scenarios they should be used.
/// Documentation
class MyMessage extends OmnibusEvent {
/// omnibusId
static const id = 'message_library.v0.MyMessage';
/// Documentation
final ImpactFactor impactFactor;
/// Constructor
MyMessage({final ImpactFactor impactFactor: ImpactFactor.high})
: impactFactor = impactFactor,
super.unchecked(id, {'impactFactor': impactFactor.index});
/// Internal constructor for fromJson
MyMessage._from(final Map<String, dynamic> data, ImpactFactor impactFactor)
: impactFactor = impactFactor,
super.unchecked(id, data);
/// Data map input constructor
factory MyMessage.fromJson(final Map<String, dynamic> data) {
ImpactFactor impactFactor;
if (data.containsKey('impactFactor') && data['impactFactor'] is int) {
impactFactor = ImpactFactor.values[data['impactFactor'] as int];
} else {
throw new ArgumentError.value(
data, 'data', "No valid field for property 'impactFactor'");
}
return new MyMessage._from(data, impactFactor);
}
}
This output file is written to the specified directory. The file name will be
the same as the specification file except that the file extension is changed to
.dart
. You have to specify the specification version in the file name using
this format: <name>.v<major_version_integer>.yaml
. The version number can not
be higher than the pub version. You are actually expected to increment this
version along with the pub major version. This is part of the compatibility
strategy.
Backward compatibility #
The versioning method in the previous paragraph is part of the compatibility strategy of omnibuild. When you introduce breaking changes in the messages you should continue in a new file with incremented version and you should increment the pub major version to reflect this change. This way modules that rely on old messages can still safely update to the new version, although they should change their messages of course. This also allows modules to implement multiple versions in order to provide backward compatibility for old modules. A next step could be to remove the old version message file and adapt the Dart code of that version to an adapter library (functions that act as old message builders but in reality create messages in the new format while still taking the same parameters as before).
To take advantage of this strategy in the modules, you should import message libraries in the following way:
import 'package:messages/messages.v1.dart' as v1;
bus.bindEventHandler(v1.MyMessage.id, {}, eventHandler);
bus.publishEvent(v1.MyMessage());