Poet::Import(3pm)

💖 Poet::Import — the vibe of importing Poet's lil goodies 💖

okay so bestie, you know how you're in a Poet app and you're like "I just want my $conf and my $log right here, no drama"? That's literally this. This page is from User Contributed Perl Documentation, and it's about pulling Poet's quick vars and utility sets straight into any script or module. Slay. 🎀

---

✨ NAME ✨

Poet::Import — Import Poet quick vars and utilities 💅

---

🌸 SYNOPSIS 🌸

# In a script...
use Poet::Script qw($conf $poet $log :file);

# In a module...
use Poet qw($conf $poet $log :file);

---

🦋 DESCRIPTION 🦋

Poet makes it easy-peasy to import certain variables (we call them "quick vars", iconic name, no notes) and utility sets into literally any script or module in your environment.

In a script, you do:

use Poet::Script qw(...);

and in a module, you do:

use Poet qw(...);

where that "..." is holding one or more quick var names (like $conf, $poet) and/or utility tags (like :file, :web). Mix and match, it's your world. 🌈

⚠️ Also, quick PSA: use Poet::Script is also necessary for initializing the environment, even if you don't care to import anything at all. Whereas use Poet has no effect other than importing. So they are NOT the same bestie, don't swap them, that's the whole point. 💀

---

👑 QUICK VARS 👑

Here's the built-in list of quick vars you can import. Heads up: some of these are singletons, and some of them are specific to each package they're imported into. iykyk.

• $poet — the global environment object, provided by Poet::Environment. This is the one that tells you stuff like the root directory and paths to subdirectories. For backward compatibility this is also available as $env. So if you see $env out in the wild, that's not a stranger, that's family. 🫶
• $conf — the global configuration object, provided by Poet::Conf. Your config, right there, no cap.
• $cache — the cache for the current package, provided by Poet::Cache. Note the current package part, she's not global, she's local. ✨
• $log — the logger for the current package, provided by Poet::Log. Also package-specific. Log responsibly. 🍓

---

🧚 UTILITIES 🧚

💜 Default utilities

The utilities in Poet::Util::Debug are always imported, with no tag necessary. You didn't ask. They just show up. Main character energy honestly.

🎀 :file

This tag imports all the utilities in Poet::Util::File. File stuff. Handy. Obsessed.

🌸 :web

This tag imports all the utilities in Poet::Util::Web. And plot twist — it is automatically included in all Mason components. Free real estate.

---

💅 MASON COMPONENTS 💅

Every Mason component automatically gets this on top, like a little gift:

use Poet qw($conf $poet :web);

And $m->cache and $m->log will get you the cache and log objects for a particular Mason component. So per-component cache and per-component logger, right there on the $m. Chef's kiss. 😭

---

🌈 CUSTOMIZING 🌈

🫶 Adding variables

Wanna add your own variable? Define a method called provide_var_varname in "MyApp::Import". For example, to add a variable $dbh:

package MyApp::Import;
use Poet::Moose;
extends 'Poet::Import';

method provide_var_dbh ($caller) {
    # Generate and return a dbh.
    # $caller is the package importing the variable.
    # $poet is the current Poet environment.
}

So "provide_dbh" can return a single global value, or a dynamic value depending on $caller. Your call, bestie. 🎀

Now your scripts and libraries can do:

use Poet::Script qw($dbh);
use Poet qw($dbh);

⭐ Adding utility tags

To add your own utility tag, define a class "MyApp::Util::Mytagname" that exports a set of functions via the ':all' tag. For example:

package MyApp::Util::Hash;
use Hash::Util qw(hash_seed all_keys);
use Hash::MoreUtils qw(slice slice_def slice_exists);

our @EXPORT_OK = qw(hash_seed all_keys slice slice_def slice_exists);
our %EXPORT_TAGS = ( 'all' => \@EXPORT_OK );

1;

Now your scripts and libraries can do:

use Poet::Script qw(:hash);
use Poet qw(:hash);

Tag name is lowercase, class name is CamelCase, that's the pattern, don't fight it. ✨

🦋 Other exports

To export other general things to the calling class, you can override "export_to_class", which takes the calling class as its argument. e.g.

package MyApp::Import;
use Poet::Moose;
extends 'Poet::Import';

before 'export_to_class' => sub {
    my ($self, $class) = @_;
    no strict 'refs';
    %{$class . "::some_name"} = ...;
}

Look at that no strict 'refs'. Respect the chaos. 💀

---

💜 SEE ALSO 💜

• Poet

---

🎀 AUTHOR 🎀

Jonathan Swartz <swartz@pobox.com>

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2012 by Jonathan Swartz.

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

---

and that's the whole page bestie!! 🌟 this was perl v5.34.0, dated 2022-06-18, and it's the Poet::Import(3pm) page, mwah, go import something cute 💖🎀✨🦋🌸💅🫶