exception_templates 0.2.0

Parameterized exception and error templates for Dart. Enables throwing and catching exception/error objects that are defined by their type argument.

Exception Templates

Introduction

When handling a program exception, the two main concerns are in what context did it occur and what type of exception occured.

The library exception_templates provides parameterized classes that allow throwing and catching exceptions characterized by their type argument.

Using parameterized exceptions eliminates the need to define library or class specific exceptions and enables filtering caught exceptions based on their type argument.

To highlight the exception context use:

• ExceptionOf<T> and
• ErrorOf<T>. In this case, the type argument hints at where the exception occured.

To emphasise the exception type use:

• ExceptionOfType<T>, where T extends ExceptionType,
• ErrorOfType<T> where T extends ErrorType.

Usage

To use this library include exception_templates as dependency in your pubspec.yaml file. Colour output can be globally enabled or disabled by setting the static field colorOutput to ColorOutput.ON or ColorOutput.OFF, respectively.

The program below demonstrates how to throw and catch objects of type ErrorOfType<T> and ExceptionOfType<T> where T is a generic type.

import 'package:exception_templates/exception_templates.dart';

// Defining error types:
class LengthMismatch extends ErrorType {}

// Defining exception types:
class EmptyUserInput extends ExceptionType {}

extension Subtraction on List<num> {
  /// Subtracts two numerical lists of same length.
  List<num> operator -(List<num> other) {
    if (length != other.length) {
      throw ErrorOfType<LengthMismatch>(
          message: 'Could not calculate: $this - $other.',
          invalidState: 'Length of $this does not match length of $other.',
          expectedState: 'Two operands with the same length.');
    }
    return List<num>.generate(length, (i) => this[i] - other[i]);
  }
}

void main(List<String> args) {
  final a = [1, 2];
  final b = [3, 4];
  final c = [...b, 5];

  // Catching an ErrorOfType<LenghtMismatch>.
  // Demo only! Errors should not be caught, while exceptions should be caught.
  try {
    print('b - a = ${b - a}');
    print('c - b = ${c - b}');
  } on ErrorOfType<LengthMismatch> catch (e) {
    print(e);
  }

  // Catching an ExceptionOfType<EmptyUserFeedback>.
  var userFeedback = '';
  try {
    throw ExceptionOfType<EmptyUserInput>(
      message: 'Could not process user feedback.',
      expectedState: 'A non-empty String.',
    );
  } on ExceptionOfType<EmptyUserInput> catch (e) {
    userFeedback = '${e.message} User did not leave a message.';
    print('Feedback: $userFeedback\n');
  }
}

A typical output produced when running the program above is shown below:

Examples

A copy of the program shown in the section above can be found in the folder example.

Features and bugs

Please file feature requests and bugs at the issue tracker.