Poet::...ronment(3pm)

💖 NAME 💖

Poet::Environment — the whole vibe of your Poet environment, like, in one object ✨

(oh and hi, this is the manpage for Poet::Environment, shipped in the 3pm section, iykyk 🫶)

---

🌸 SYNOPSIS 🌸

okay so first you gotta get your hands on $poet, bestie:

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

# In a module...
use Poet qw($poet);

# $poet is automatically available in Mason components

and then you can just… ask it things. it's giving personal assistant 💅

# then...
my $root_dir       = $poet->root_dir;
my $file           = $poet->path("some/file.txt");
my $path_to_script = $poet->bin_path("foo/bar.pl");
my $path_to_lib    = $poet->lib_path("Foo/Bar.pm");

---

🦋 DESCRIPTION 🦋

The Poet::Environment object is literally the keeper of all the lore about your current environment and where all its directories live. paths, paths, and more paths. it knows things. no cap. 👑

---

🎀 PATH METHODS 🎀

root_dir

Returns the root directory of the environment — aka, the place where .poet_root is chillin'. that file is the moment. 📍

path (subpath)

Returns the root directory with a relative subpath added on. like, if the Poet environment root is /my/env/root, then:

$poet->path("somefile.txt");
   ==> returns /my/env/root/somefile.txt

bin_dir

comps_dir

conf_dir

data_dir

db_dir

lib_dir

logs_dir

static_dir

Returns the specified subdirectory — which, by default, sits just below the root directory. so if the Poet environment root is /my/env/root, then:

$poet->conf_dir
   ==> returns /my/env/root/conf

$poet->lib_dir
   ==> returns /my/env/root/lib

bin_path (subpath)

comps_path (subpath)

conf_path (subpath)

data_path (subpath)

db_path (subpath)

lib_path (subpath)

logs_path (subpath)

static_path (subpath)

Returns the specified subdirectory with a relative subpath added on. same energy as before, if the Poet environment root is /my/env/root, then:

$poet->conf_path("log4perl.conf");
   ==> returns /my/env/root/conf/log4perl.conf

$poet->lib_path("Data/Type.pm");
   ==> returns /my/env/root/lib/Data/Type.pm

---

✨ OTHER METHODS ✨

• app_class — Returns the full class name you should use for the class you passed in, and it depends on whether a subclass exists in the environment. like:

$poet->app_class('Cache')

will hand you back "MyApp::Cache" if that module exists, and if it doesn't, you get "Poet::Cache" instead. Poet uses this internally to do its auto subclassing thing. main character behavior fr 🫶

• app_name — Returns the app name, e.g. 'MyApp', the one it found in .poet_root.
• conf — Returns the Poet::Conf object that goes with the environment. usually you'd just import $conf instead of doing all this, ngl.
• current_env — A class method that returns the current (singleton) environment for the process. again, usually you'd just import $poet. lowkey the easy way is the way. 💜

---

👑 OBTAINING $poet SINGLETON 👑

In a script:

use Poet::Script qw($poet);

In a module:

use Poet qw($poet);

$poet is automatically available in components. iconic.

You can also get it via:

my $poet = Poet::Environment->current_env;

---

🌈 CONFIGURING ENVIRONMENT SUBDIRECTORIES 🌈

Any subdirectories other than conf_dir can be overridden in configuration. like, for example:

# Override bin_dir
env.bin_dir: /some/other/bin/dir

and with that configuration in place:

$poet->bin_dir
   ==> returns /some/other/bin/dir

$poet->bin_path("foo/bar.pl")
   ==> returns /some/other/bin/dir/foo/bar.pl

lowkey obsessed with how clean that is. conf_dir is the one exception tho, so don't come for it. 🙈

---

💫 SEE ALSO 💫

• Poet

---

🌟 AUTHOR 🌟

Jonathan Swartz <swartz@pobox.com> — the legend who made all this happen 💖

---

📜 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.

---

okay that's the whole page bestie, you ate it all up 🍓✨ and for the record, this was documented as perl v5.34.0, dated 2022-06-18, in the Poet::...ronment(3pm) page itself — slay, go build something cute 💅🦋