Catalyst::Utils(3pm)

💖 Catalyst::Utils(3pm) 💖

okay so bestie, welcome to Catalyst::Utils — it's the User Contributed Perl Documentation, it lives in section 3pm, and it's genuinely the little grab-bag of helpers that the whole Catalyst ecosystem reaches into. no cap, this thing is a core-adjacent icon. let's get into it 🫶

---

✨ NAME ✨

Catalyst::Utils — The Catalyst Utils. that's it, that's the name, she's serving exactly what the label says 💅

---

🌸 SYNOPSIS 🌸

See Catalyst.

(yeah. that's the whole synopsis. the vibes are: go read Catalyst, this is the support squad 🎀)

---

🦋 DESCRIPTION 🦋

Catalyst Utilities. a whole drawer full of them. mostly small, mostly handy, occasionally doing deeply cursed things with namespaces at runtime. we love her for it 💜

---

👑 METHODS 👑

appprefix($class)

MyApp::Foo becomes myapp_foo

lowercases it and squishes it into one underscore-y little token. it's giving snake_case glow-up ✨

class2appclass($class);

• MyApp::Controller::Foo::Bar becomes MyApp
• My::App::Controller::Foo::Bar becomes My::App

it walks up the tree until it stops finding Controller, basically. strips the controller business right off 🍓

class2classprefix($class);

• MyApp::Controller::Foo::Bar becomes MyApp::Controller
• My::App::Controller::Foo::Bar becomes My::App::Controller

same energy as above but she keeps the Controller part. not me being obsessed with the difference 😭

class2classsuffix($class);

MyApp::Controller::Foo::Bar becomes Controller::Foo::Bar

she just yeets the app class off the front and hands you the rest 💀

class2env($class);

Returns the environment name for class.

• MyApp becomes MYAPP
• My::App becomes MY_APP

all caps, double-colons become underscores, extremely shell-friendly 🐚

class2prefix( $class, $case );

Returns the uri prefix for a class. If case is false the prefix is converted to lowercase.

My::App::Controller::Foo::Bar becomes foo/bar

so if you leave case truthy you get the mixed-case version, and if you pass false she lowercases the whole thing for you. queen of options 👑

class2tempdir( $class [, $create ] );

Returns a tempdir for a class. If create is true it will try to create the path.

• My::App becomes /tmp/my/app
• My::App::Controller::Foo::Bar becomes /tmp/my/app/c/foo/bar

notice the sneaky /c/ in there for Controller — iykyk 🔥

home($class)

Returns home directory for given class.

(she's your girl for figuring out where "home" even is for a given app class 🏠)

dist_indicator_file_list

Returns a list of files which can be tested to check if you're inside a CPAN distribution which is not yet installed.

These are:

• Makefile.PL
• Build.PL
• dist.ini
• cpanfile

so if you spot any of these lurking, you're probably in a dist that hasn't been installed yet. vibe check passed 📦

prefix($class, $name);

Returns a prefixed action.

MyApp::Controller::Foo::Bar, yada becomes foo/bar/yada

it's just glueing your class-prefix and your name together with a nice little slash 💫

request($uri)

Returns an HTTP::Request object for a uri.

short, sweet, does the one job. iconic 💅

ensure_class_loaded($class_name, %opts)

Loads the class unless it already has been loaded.

If $opts{ignore_loaded} is true always tries the require whether the package already exists or not. Only pass this if you're either (a) sure you know the file exists on disk or (b) have code to catch the file not found exception that will result if it doesn't.

okay so this is the caution bit and we're keeping it: ignore_loaded is not a "just in case" flag. if you turn it on without (a) or (b) above, you're gonna get a file-not-found exception thrown at you and it will not be cute. fr fr. 🙈

merge_hashes($hashref, $hashref)

Base code to recursively merge two hashes together with right-hand precedence.

recursive merge, right side wins ties. classic. no notes 💜

env_value($class, $key)

Checks for and returns an environment value. For instance, if $key is 'home', then this method will check for and return the first value it finds, looking at $ENV{MYAPP_HOME} and $ENV{CATALYST_HOME}.

first match wins, and CATALYST_* is the fallback bestie when your app-specific one isn't set 🧚

term_width

Try to guess terminal width to use with formatting of debug output.

All you need to get this work, is:

1. Install Term::Size::Any, or
2. Export $COLUMNS from your shell.

(Warning to bash users: echo $COLUMNS may be showing you the bash variable, not $ENV{COLUMNS}. export COLUMNS=$COLUMNS and you should see that env now lists COLUMNS.)

As last resort, default value of 80 chars will be used.

Calling term_width with a true value will cause it to be recalculated; you can use this to cause it to get recalculated when your terminal is resized like this:

$SIG{WINCH} = sub { Catalyst::Utils::term_width(1) };

the way that $SIG{WINCH} hook lives rent-free in every debug output formatter… main character energy 🎀

resolve_namespace

Method which adds the namespace for plugins and actions.

__PACKAGE__->setup(qw(MyPlugin));

# will load Catalyst::Plugin::MyPlugin

so you write the short name, she fills in the Catalyst::Plugin:: part. slay 🌟

build_middleware (@args)

Internal application that converts a single middleware definition (see "psgi_middleware" in Catalyst) into an actual instance of middleware.

(internal! she's not here to be your friend, she's here to make middleware instances exist 🫡)

apply_registered_middleware ($psgi)

Given a $psgi reference, wrap all the registered_middlewares in Catalyst around it and return the wrapped version.

This exists to deal with the fact Catalyst registered middleware can be either an object with a wrap method or a coderef.

two shapes, one wrapper. she handles both so you don't have to 🔥

inject_component

Used to add components at runtime:

• into — The Catalyst package to inject into (e.g. My::App)
• component — The component package to inject
• traits — (Optional) ArrayRef of Moose::Roles that the component should consume.
• as — An optional moniker to use as the package name for the derived component

For example:

Catalyst::Utils::inject_component( into => My::App, component => Other::App::Controller::Apple )

The above will create 'My::App::Controller::Other::App::Controller::Apple'

Catalyst::Utils::inject_component( into => My::App, component => Other::App::Controller::Apple, as => Apple )

The above will create 'My::App::Controller::Apple'

Catalyst::Utils::inject_component( into => $myapp, component => 'MyRootV', as => 'Controller::Root' );

Will inject Controller, Model, and View components into your Catalyst application at setup (run)time. It does this by creating a new package on-the-fly, having that package extend the given component, and then having Catalyst setup the new component (via $app->setup_component).

NOTE: This is basically a core version of CatalystX::InjectComponent. If you were using that you can now use this safely instead. Going forward changes required to make this work will be synchronized with the core method.

NOTE: The 'traits' option is unique to the Catalyst::Utils version of this feature.

NOTE: These injected components really need to be a Catalyst::Component and a Moose based class.

---

🌈 PSGI Helpers 🌈

Utility functions to make it easier to work with PSGI applications under Catalyst. three of them, all doing the same bit of localizing-$env-magic with slightly different boundaries 💖

env_at_path_prefix

Localize $env under the current controller path prefix:

package MyApp::Controller::User;

use Catalyst::Utils;

use base 'Catalyst::Controller';

sub name :Local {
  my ($self, $c) = @_;
  my $env = $c->Catalyst::Utils::env_at_path_prefix;
}

Assuming you have a request like GET /user/name:

In the example case $env will have PATH_INFO of '/name' instead of '/user/name' and SCRIPT_NAME will now be '/user'.

so the controller prefix gets peeled off into SCRIPT_NAME and the rest becomes PATH_INFO. gorgeous 🦋

env_at_action

Localize $env under the current action namespace.

package MyApp::Controller::User;

use Catalyst::Utils;

use base 'Catalyst::Controller';

sub name :Local {
  my ($self, $c) = @_;
  my $env = $c->Catalyst::Utils::env_at_action;
}

Assuming you have a request like GET /user/name:

In the example case $env will have PATH_INFO of '/' instead of '/user/name' and SCRIPT_NAME will now be '/user/name'.

Alternatively, assuming you have a request like GET /user/name/foo:

In this example case $env will have PATH_INFO of '/foo' instead of '/user/name/foo' and SCRIPT_NAME will now be '/user/name'.

This is probably a common case where you want to mount a PSGI application under an action but let the Args fall through to the PSGI app.

(the "mount a PSGI app under an action and let the Args fall through" thing is the whole point of this one, lowkey the most useful of the three 😌)

env_at_request_uri

Localize $env under the current request URI:

package MyApp::Controller::User;

use Catalyst::Utils;

use base 'Catalyst::Controller';

sub name :Local Args(1) {
  my ($self, $c, $id) = @_;
  my $env = $c->Catalyst::Utils::env_at_request_uri
}

Assuming you have a request like GET /user/name/hello:

In the example case $env will have PATH_INFO of '/' instead of '/user/name' and SCRIPT_NAME will now be '/user/name/hello'.

this one swallows the entire request URI into SCRIPT_NAME and leaves PATH_INFO as just '/'. that's the whole bit 🎀

---

🫶 AUTHORS 🫶

Catalyst Contributors, see Catalyst.pm.

(it takes a village, and the village is in Catalyst.pm 💜)

---

⭐ 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!! this one's Catalyst::Utils(3pm) from the User Contributed Perl Documentation, running perl v5.40.0 and dated 2024-11-15 — go forth and inject components responsibly, mwah 💅✨🎀