<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/API/Stack.md. Do not edit. -->

```{index} single: Test2::API::Stack
```

# Test2::API::Stack

Object to manage a stack of [Test2::Hub](../Hub.md)
instances.

## \*\*\*INTERNALS NOTE\*\*\*

**The internals of this package are subject to change at any time!** The public
methods provided will not change in backwards incompatible ways, but the
underlying implementation details might. **Do not break encapsulation here!**

## DESCRIPTION

This module is used to represent and manage a stack of [Test2::Hub](../Hub.md)
objects. Hubs are usually in a stack so that you can push a new hub into place
that can intercept and handle events differently than the primary hub.

## SYNOPSIS

```perl
my $stack = Test2::API::Stack->new;
my $hub = $stack->top;
```

## METHODS

- $stack = Test2::API::Stack->new()

    This will create a new empty stack instance. All arguments are ignored.

- $hub = $stack->new\_hub()
- $hub = $stack->new\_hub(%params)
- $hub = $stack->new\_hub(%params, class => $class)

    This will generate a new hub and push it to the top of the stack. Optionally
    you can provide arguments that will be passed into the constructor for the
    [Test2::Hub](../Hub.md) object.

    If you specify the `'class' => $class` argument, the new hub will be an
    instance of the specified class.

    Unless your parameters specify `'formatter'` or `'ipc'` arguments, the
    formatter and IPC instance will be inherited from the current top hub. You can
    set the parameters to `undef` to avoid having a formatter or IPC instance.

    If there is no top hub, and you do not ask to leave IPC and formatter undef,
    then a new formatter will be created, and the IPC instance from
    [Test2::API](../API.md) will be used.

- $hub = $stack->top()

    This will return the top hub from the stack. If there is no top hub yet this
    will create it.

- $hub = $stack->peek()

    This will return the top hub from the stack. If there is no top hub yet this
    will return undef.

- $stack->cull

    This will call `$hub->cull` on all hubs in the stack.

- @hubs = $stack->all

    This will return all the hubs in the stack as a list.

- $stack->clear

    This will completely remove all hubs from the stack. Normally you do not want
    to do this, but there are a few valid reasons for it.

- $stack->push($hub)

    This will push the new hub onto the stack.

- $stack->pop($hub)

    This will pop a hub from the stack, if the hub at the top of the stack does not
    match the hub you expect (passed in as an argument) it will throw an exception.

## SOURCE

The source code repository for Test2 can be found at
[https://github.com/Test-More/test-more/](https://github.com/Test-More/test-more/).

## MAINTAINERS

- Chad Granum <exodist@cpan.org>

## AUTHORS

- Chad Granum <exodist@cpan.org>

## COPYRIGHT

Copyright Chad Granum <exodist@cpan.org>.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

See [https://dev.perl.org/licenses/](https://dev.perl.org/licenses/)