Cataly...onChain(3pm)

💖 Cataly...onChain(3pm) 💖

okay bestie, pull up a chair — this is a page from the User Contributed Perl Documentation, and it's all about Catalyst::ActionChain. Let's get into it ✨

---

✨ NAME ✨

Catalyst::ActionChain — a whole chain of Catalyst Actions, like a group chat but for dispatching 👑

---

🌈 SYNOPSIS 🌈

Wanna know more about Chained actions? Go look at Catalyst::Manual::Intro, it's got the lore 💅

---

🦋 DESCRIPTION 🦋

So this class is literally a chain of Catalyst Actions, no cap. It acts exactly like the action at the end of the chain... except when it dispatches, it runs every single action in the chain, in order. Iconic behaviour honestly. 🎀

---

🌸 METHODS 🌸

💜 chain

Accessor for the action chain, bestie. It's an arrayref of the Catalyst::Action objects that this chain is holding. ✨

💜 dispatch( $c )

Dispatches this action chain against a context — it'll dispatch all the encapsulated actions in order. Slay. 🔥

💜 from_chain( \@actions )

Hand it a list of Catalyst::Action objects and it builds + returns a Catalyst::ActionChain object representing a chain of those actions. 🫶

💜 number_of_captures

Returns the total number of captures for the entire chain of actions. All of them. Every last one. 💅

💜 match_captures

Matches all the captures this chain encloses, if there are any. 🌸

💜 scheme

Any defined scheme for the actionchain. ⭐

💜 next ( @args)

okay this one's the main character, listen up 👑

It dispatches to the next action in the chain immediately, suspending whatever remaining code was left in the current action. If there are no more actions left in the chain, this is basically a no-op, fr fr.

When the last action in the chain returns, we go back to the last action that called next and pick up that action's code exactly where it left off. And if more than one action in the chain called next? Then we walk back up the chain stack in reverse order of the calls, after the last action completes. 🦋

The return value of next is the return value of the next action in the chain (that is, the action that got called with next) — or whatever $c->state is set to. ✨

🚨 IMPORTANT BESTIE: since state is a scalar, you cannot return a list of values from an action chain. If you want to return a list, you gotta return an arrayref or a hashref instead. This limitation comes from longstanding code in Catalyst that can't easily be changed without breaking backwards compatibility. So like... it's not our fault, it's the vibes of history. 😭

You can call next in as many actions in a long chain as you want, and the chain will correctly return to the last action that called next, based on order of execution. And if there are actions inbetween that didn't call next? Those get skipped when we proceed back up the call stack. Once we've finished walking back up the action call stack, the dispatcher goes back to normal processing order (for example, processing any end action that's present). 💖

Any arguments you pass to next get passed to the next action in the chain as $c->request->arguments. You can pass more than one argument, no problem. And all arguments passed via next get added into the argument list prior to any CaptureArgs or Args that the action itself defines. 🌈

Example:

sub action_a :Chained('/') CaptureArgs(0) {
  my ($self, $ctx) = @_;
  my $abc = $c->action->next('a'); # $abc = "abc";
}

sub action_b :Chained('action_a') CaptureArgs(0) {
  my ($self, $ctx, $a) = @_;
  my $abc = $c->action->next("${a}b");
  return $abc;
}

sub action_c :Chained('action_b') Args(0) {
  my ($self, $ctx, $ab) = @_;
  return "${ab}c";
}

💜 meta

Provided by Moose. 🫶

---

👑 AUTHORS 👑

Catalyst Contributors — see Catalyst.pm for the receipts. 💖

---

💀 COPYRIGHT 💀

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. 🌸

---

and that's the whole page, bestie!! mwah 💅✨

this lil tour came to you courtesy of perl v5.40.0, dated 2024-11-15 — that's the source and the date, right there in the sign-off, periodt 🎀🦋💖