blob: 2dcd96e495988d56758b1e8355aaee9aeaf28d22 [file] [log] [blame]
// Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
library plugin;
import 'package:plugin/src/plugin_impl.dart';
/**
* A function used to register the given [extension] to the extension point with
* the given unique [identifier].
*
* An [ExtensionError] will be thrown if the [extension] is not appropriate
* for the extension point, such as an [extension] that does not implement the
* required interface.
*/
typedef void RegisterExtension(String identifier, Object extension);
/**
* A function used to register the given [extensionPoint].
*
* An [ExtensionError] will be thrown if the extension point cannot be
* registered, such as when a plugin attempts to define two extension points
* with the same identifier.
*/
typedef void RegisterExtensionPoint(ExtensionPoint extensionPoint);
/**
* A function used by a plugin to validate an [extension] to a extension point.
*
* An [ExtensionError] should be thrown if the [extension] is not valid for the
* extension point, such as an [extension] that does not implement the required
* interface.
*/
typedef void ValidateExtension(Object extension);
/**
* An exception indicating that an error occurred while attempting to register
* either an extension or an extension point.
*
* Clients may not extend, implement or mix-in this class.
*/
class ExtensionError implements Exception {
/**
* The message describing the error that occurred.
*/
final String message;
/**
* Initialize a newly created error to have the given message.
*/
ExtensionError(this.message);
}
/**
* A representation of an extension point.
*
* Clients may not extend, implement or mix-in this class.
*/
abstract class ExtensionPoint<E> {
/**
* Initialize a newly created extension point to be defined by the given
* [plugin] with the given [simpleIdentifier]. The [validateExtension]
* function will be used to validate extensions for this extension point.
*/
factory ExtensionPoint(Plugin plugin, String simpleIdentifier,
ValidateExtension validateExtension) = ExtensionPointImpl<E>;
/**
* Return an immutable list containing all of the extensions that were
* registered for this extension point.
*/
List<E> get extensions;
/**
* Return the plugin that defined this extension point.
*/
Plugin get plugin;
/**
* Return the identifier used to uniquely identify this extension point within
* the defining plugin.
*/
String get simpleIdentifier;
/**
* Return the identifier used to uniquely identify this extension point. The
* unique identifier is the identifier for the plugin, followed by a period
* (`.`), followed by the [simpleIdentifier] for the extension point.
*/
String get uniqueIdentifier;
}
/**
* A contribution to the host application that can extend the behavior of the
* application while also allowing other plugins to extend it's behavior.
*
* Clients may implement this class when implementing plugins.
*/
abstract class Plugin {
/**
* Return the identifier used to uniquely identify this plugin.
*/
String get uniqueIdentifier;
/**
* Use the [register] function to register all of the extension points
* contributed by this plugin.
*
* Clients should not invoke the [register] function after this method has
* returned.
*/
void registerExtensionPoints(RegisterExtensionPoint register);
/**
* Use the [register] function to register all of the extensions contributed
* by this plugin.
*
* Clients should not invoke the [register] function after this method has
* returned.
*/
void registerExtensions(RegisterExtension register);
/**
* Return a unique identifier created from the unique identifier from the
* [plugin] and the [simpleIdentifier].
*/
static String buildUniqueIdentifier(Plugin plugin, String simpleIdentifier) =>
join(plugin.uniqueIdentifier, simpleIdentifier);
/**
* Return an identifier created by joining the [pluginIdentifier] and the
* [simpleIdentifier].
*/
static String join(String pluginIdentifier, String simpleIdentifier) =>
'$pluginIdentifier.$simpleIdentifier';
}