NAME

TB2::EventCoordinator - Coordinate events amongst the builders

SYNOPSIS

    use TB2::EventCoordinator;
    my $ec = TB2::EventCoordinator->new;

    # The builder sends it events like assert results and the beginning
    # and end of tests.
    $ec->post_event($event);

    # The EventCoordinator comes with History and the default Formatter,
    # but they can be replaced or added to.  You can also add handlers of
    # your own devising.
    $events->add_formatters($formatter);
    $events->add_late_handlers($handler);

DESCRIPTION

Test::Builder2 is a federated system of test formatters and assert generators. This lets people make new and interesting ways to write tests and format the results while keeping them coordianted. The EventCoordiantor is responsible for that coordination.

Each thing that generates events, usually something that causes asserts, will report them to the EventCoordinator. This in turn reports them to things like History and result Formatters and whatever else you want to handle events.

METHODS

Attributes

These are attributes which can be set and gotten through a method of the same name. They can also be passed into new.

history

The History object which is listening to events.

This is a special case of handlers provided so you can distinguish between formatters and other handlers.

Defaults to [ TB2::History->new ].

Unlike other handlers, there is only one history.

formatters

An array ref of Formatter objects which are listening to events.

This is a special case of handlers provided so you can distinguish between formatters and other handlers.

Defaults to [ $class->default_formatters ].

The default can be altered by overriding default_formatter_class and/or default_formatters.

early_handlers

An array ref of any additional objects which are listening to events. They all must do the TB2::EventHandler role (or have equivalent methods).

early_handlers are called first before any other handlers. This lets them manipulate the result before a formatter can act on it.

By default there are no early_handlers.

late_handlers

An array ref of any additional objects which are listening to events. They all must do the TB2::EventHandler role (or have equivalent methods).

late_handlers are called last after all other handlers. This lets them see the result after any manipulations.

By default there are no late_handlers.

Constructors

These are methods which create or retrieve EventCoordinator objects.

Constructor

new

    my $ec = TB2::EventCoordinator->new( %args );

Creates a new event coordinator.

%args are the Attributes defined above.

For example, to create an EventCoordinator without a formatter...

    my $ec = TB2::EventCoordinator->new(
        formatters => []
    );

Methods

default_formatter_class

    my $formatter_class = $class->default_formatter_class;

Returns the TB2::Formatter subclass to be used for formatting by default.

Defaults to the TB2_FORMATTER_CLASS environment variable, if set, or TB2::Formatter::TAP if not.

default_formatters

    my $formatters = $class->default_formatters;

Returns the list of formatters to be used by default.

Defaults to a single instance of the default_formatter_class.

post_event

  $ec->post_event($event);

The $ec will hand the $event around to all its handlers, along with itself. See all_handlers for ordering information.

all_handlers

  my @handlers = $ec->all_handlers;

Returns a list of all handlers in the order they will be passed events.

The order is early_handlers, history, formatters, late_handlers.

add_early_handlers

add_formatters

add_late_handlers

  $ec->add_early_handlers($handler1, $handler2, ...);

Adds new handlers to their respective types.

Use this instead of manipulating the list of handlers directly.

clear_early_handlers

clear_formatters

clear_late_handlers

  $ec->clear_early_handlers;

Removes all handlers of their respective types.