{
    "content": [
        {
            "type": "text",
            "text": "# Test2::Hub (perldoc)\n\n## NAME\n\nTest2::Hub - The conduit through which all events flow.\n\n## SYNOPSIS\n\nuse Test2::Hub;\nmy $hub = Test2::Hub->new();\n$hub->send(...);\n\n## DESCRIPTION\n\nThe hub is the place where all events get processed and handed off to the formatter. The hub\nalso tracks test state, and provides several hooks into the event pipeline.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **COMMON TASKS**\n- **METHODS**\n- **THIRD PARTY META-DATA**\n- **SOURCE**\n- **MAINTAINERS**\n- **AUTHORS**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Test2::Hub",
        "section": "",
        "mode": "perldoc",
        "summary": "Test2::Hub - The conduit through which all events flow.",
        "synopsis": "use Test2::Hub;\nmy $hub = Test2::Hub->new();\n$hub->send(...);",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "COMMON TASKS",
                "lines": 70,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 180,
                "subsections": []
            },
            {
                "name": "THIRD PARTY META-DATA",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "SOURCE",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "MAINTAINERS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Test2::Hub - The conduit through which all events flow.\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use Test2::Hub;\n\nmy $hub = Test2::Hub->new();\n$hub->send(...);\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "The hub is the place where all events get processed and handed off to the formatter. The hub\nalso tracks test state, and provides several hooks into the event pipeline.\n",
                "subsections": []
            },
            "COMMON TASKS": {
                "content": "SENDING EVENTS\n$hub->send($event)\n\nThe \"send()\" method is used to issue an event to the hub. This method will handle thread/fork\nsync, filters, listeners, TAP output, etc.\n\nALTERING OR REMOVING EVENTS\nYou can use either \"filter()\" or \"prefilter()\", depending on your needs. Both have identical\nsyntax, so only \"filter()\" is shown here.\n\n$hub->filter(sub {\nmy ($hub, $event) = @;\n\nmy $action = getaction($event);\n\n# No action should be taken\nreturn $event if $action eq 'none';\n\n# You want your filter to remove the event\nreturn undef if $action eq 'delete';\n\nif ($action eq 'doit') {\nmy $newevent = copyevent($event);\n... Change your copy of the event ...\nreturn $newevent;\n}\n\ndie \"Should not happen\";\n});\n\nBy default, filters are not inherited by child hubs. That means if you start a subtest, the\nsubtest will not inherit the filter. You can change this behavior with the \"inherit\" parameter:\n\n$hub->filter(sub { ... }, inherit => 1);\n\nLISTENING FOR EVENTS\n$hub->listen(sub {\nmy ($hub, $event, $number) = @;\n\n... do whatever you want with the event ...\n\n# return is ignored\n});\n\nBy default listeners are not inherited by child hubs. That means if you start a subtest, the\nsubtest will not inherit the listener. You can change this behavior with the \"inherit\"\nparameter:\n\n$hub->listen(sub { ... }, inherit => 1);\n\nPOST-TEST BEHAVIORS\n$hub->followup(sub {\nmy ($trace, $hub) = @;\n\n... do whatever you need to ...\n\n# Return is ignored\n});\n\nfollowup subs are called only once, either when donetesting is called, or in an END block.\n\nSETTING THE FORMATTER\nBy default an instance of Test2::Formatter::TAP is created and used.\n\nmy $old = $hub->format(My::Formatter->new);\n\nSetting the formatter will REPLACE any existing formatter. You may set the formatter to undef to\nprevent output. The old formatter will be returned if one was already set. Only one formatter is\nallowed at a time.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "$hub->send($event)\nThis is where all events enter the hub for processing.\n\n$hub->process($event)\nThis is called by send after it does any IPC handling. You can use this to bypass the IPC\nprocess, but in general you should avoid using this.\n\n$old = $hub->format($formatter)\nReplace the existing formatter instance with a new one. Formatters must be objects that\nimplement a \"$formatter->write($event)\" method.\n\n$sub = $hub->listen(sub { ... }, %optionalparams)\nYou can use this to record all events AFTER they have been sent to the formatter. No changes\nmade here will be meaningful, except possibly to other listeners.\n\n$hub->listen(sub {\nmy ($hub, $event, $number) = @;\n\n... do whatever you want with the event ...\n\n# return is ignored\n});\n\nNormally listeners are not inherited by child hubs such as subtests. You can add the\n\"inherit => 1\" parameter to allow a listener to be inherited.\n\n$hub->unlisten($sub)\nYou can use this to remove a listen callback. You must pass in the coderef returned by the\n\"listen()\" method.\n\n$sub = $hub->filter(sub { ... }, %optionalparams)\n$sub = $hub->prefilter(sub { ... }, %optionalparams)\nThese can be used to add filters. Filters can modify, replace, or remove events before\nanything else can see them.\n\n$hub->filter(\nsub {\nmy ($hub, $event) = @;\n\nreturn $event;    # No Changes\nreturn;           # Remove the event\n\n# Or you can modify an event before returning it.\n$event->modify;\nreturn $event;\n}\n);\n\nIf you are not using threads, forking, or IPC then the only difference between a \"filter\"\nand a \"prefilter\" is that \"prefilter\" subs run first. When you are using threads, forking,\nor IPC, prefilters happen to events before they are sent to their destination proc/thread,\nordinary filters happen only in the destination hub/thread.\n\nYou cannot add a regular filter to a hub if the hub was created in another process or\nthread. You can always add a prefilter.\n\n$hub->unfilter($sub)\n$hub->preunfilter($sub)\nThese can be used to remove filters and prefilters. The $sub argument is the reference\nreturned by \"filter()\" or \"prefilter()\".\n\n$hub->followop(sub { ... })\nUse this to add behaviors that are called just before the hub is finalized. The only\nargument to your codeblock will be a Test2::EventFacet::Trace instance.\n\n$hub->followup(sub {\nmy ($trace, $hub) = @;\n\n... do whatever you need to ...\n\n# Return is ignored\n});\n\nfollowup subs are called only once, ether when donetesting is called, or in an END block.\n\n$sub = $hub->addcontextacquire(sub { ... });\nAdd a callback that will be called every time someone tries to acquire a context. It gets a\nsingle argument, a reference of the hash of parameters being used the construct the context.\nThis is your chance to change the parameters by directly altering the hash.\n\ntest2addcallbackcontextacquire(sub {\nmy $params = shift;\n$params->{level}++;\n});\n\nThis is a very scary API function. Please do not use this unless you need to. This is here\nfor Test::Builder and backwards compatibility. This has you directly manipulate the hash\ninstead of returning a new one for performance reasons.\n\nNote Using this hook could have a huge performance impact.\n\nThe coderef you provide is returned and can be used to remove the hook later.\n\n$hub->removecontextacquire($sub);\nThis can be used to remove a context acquire hook.\n\n$sub = $hub->addcontextinit(sub { ... });\nThis allows you to add callbacks that will trigger every time a new context is created for\nthe hub. The only argument to the sub will be the Test2::API::Context instance that was\ncreated.\n\nNote Using this hook could have a huge performance impact.\n\nThe coderef you provide is returned and can be used to remove the hook later.\n\n$hub->removecontextinit($sub);\nThis can be used to remove a context init hook.\n\n$sub = $hub->addcontextrelease(sub { ... });\nThis allows you to add callbacks that will trigger every time a context for this hub is\nreleased. The only argument to the sub will be the Test2::API::Context instance that was\nreleased. These will run in reverse order.\n\nNote Using this hook could have a huge performance impact.\n\nThe coderef you provide is returned and can be used to remove the hook later.\n\n$hub->removecontextrelease($sub);\nThis can be used to remove a context release hook.\n\n$hub->cull()\nCull any IPC events (and process them).\n\n$pid = $hub->pid()\nGet the process id under which the hub was created.\n\n$tid = $hub->tid()\nGet the thread id under which the hub was created.\n\n$hud = $hub->hid()\nGet the identifier string of the hub.\n\n$uuid = $hub->uuid()\nIf UUID tagging is enabled (see Test2::API) then the hub will have a UUID.\n\n$ipc = $hub->ipc()\nGet the IPC object used by the hub.\n\n$hub->setnoending($bool)\n$bool = $hub->noending\nThis can be used to disable auto-ending behavior for a hub. The auto-ending behavior is\ntriggered by an end block and is used to cull IPC events, and output the final plan if the\nplan was 'NO PLAN'.\n\n$bool = $hub->active\n$hub->setactive($bool)\nThese are used to get/set the 'active' attribute. When true this attribute will force\n\"hub->finalize()\" to take action even if there is no plan, and no tests have been run. This\nflag is useful for plugins that add follow-up behaviors that need to run even if no events\nare seen.\n\nSTATE METHODS\n$hub->resetstate()\nReset all state to the start. This sets the test count to 0, clears the plan, removes the\nfailures, etc.\n\n$num = $hub->count\nGet the number of tests that have been run.\n\n$num = $hub->failed\nGet the number of failures (Not all failures come from a test fail, so this number can be\nlarger than the count).\n\n$bool = $hub->ended\nTrue if the testing has ended. This MAY return the stack frame of the tool that ended the\ntest, but that is not guaranteed.\n\n$bool = $hub->ispassing\n$hub->ispassing($bool)\nCheck if the overall test run is a failure. Can also be used to set the pass/fail status.\n\n$hub->plan($plan)\n$plan = $hub->plan\nGet or set the plan. The plan must be an integer larger than 0, the string 'NO PLAN', or the\nstring 'SKIP'.\n\n$bool = $hub->checkplan\nCheck if the plan and counts match, but only if the tests have ended. If tests have not\nended this will return undef, otherwise it will be a true/false.\n",
                "subsections": []
            },
            "THIRD PARTY META-DATA": {
                "content": "This object consumes Test2::Util::ExternalMeta which provides a consistent way for you to attach\nmeta-data to instances of this class. This is useful for tools, plugins, and other extensions.\n",
                "subsections": []
            },
            "SOURCE": {
                "content": "The source code repository for Test2 can be found at http://github.com/Test-More/test-more/.\n",
                "subsections": []
            },
            "MAINTAINERS": {
                "content": "Chad Granum <exodist@cpan.org>\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "Chad Granum <exodist@cpan.org>\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright 2020 Chad Granum <exodist@cpan.org>.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nSee http://dev.perl.org/licenses/\n",
                "subsections": []
            }
        }
    }
}