--- name: "Catalyst::Utils" section: "3pm" platform: "linux" package: "libcatalyst-perl" version: "5.90132-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Catalyst::Utils" --- # Catalyst::Utils(3pm) The Catalyst Utils ## NAME Catalyst::Utils - The Catalyst Utils ## SYNOPSIS See Catalyst. ## DESCRIPTION Catalyst Utilities. ## METHODS ### appprefix($class) ``` MyApp::Foo becomes myapp_foo ``` ### class2appclass($class); ``` MyApp::Controller::Foo::Bar becomes MyApp My::App::Controller::Foo::Bar becomes My::App ``` ### class2classprefix($class); ``` MyApp::Controller::Foo::Bar becomes MyApp::Controller My::App::Controller::Foo::Bar becomes My::App::Controller ``` ### class2classsuffix($class); ``` MyApp::Controller::Foo::Bar becomes Controller::Foo::Bar ``` ### class2env($class); Returns the environment name for class. ``` MyApp becomes MYAPP My::App becomes MY_APP ``` ### 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 ``` ### 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 ``` ### home($class) Returns home directory for given 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 ### prefix($class, $name); Returns a prefixed action. ``` MyApp::Controller::Foo::Bar, yada becomes foo/bar/yada ``` ### request($uri) Returns an HTTP::Request object for a uri. ### 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. ### merge\_hashes($hashref, $hashref) Base code to recursively merge two hashes together with right-hand precedence. ### 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}. ### 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) }; ``` ### resolve\_namespace Method which adds the namespace for plugins and actions. ``` __PACKAGE__->setup(qw(MyPlugin)); # will load Catalyst::Plugin::MyPlugin ``` ### build\_middleware (@args) Internal application that converts a single middleware definition (see "psgi\_middleware" in Catalyst) into an actual instance of middleware. ### 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. ### 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 Ls 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 ### 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'. ### 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. ### 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'. ## AUTHORS Catalyst Contributors, see Catalyst.pm ## COPYRIGHT This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.