---
name: "Poet::Environment"
section: "3pm"
platform: "linux"
package: "libpoet-perl"
version: "0.16-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Poet::Environment"
---

# Poet::Environment(3pm)

## NAME

Poet::Environment -- Poet environment

## SYNOPSIS

```
    # In a script...
    use Poet::Script qw($poet);
    # In a module...
    use Poet qw($poet);
    # $poet is automatically available in Mason components
    # 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 contains information about the current environment and its directory paths.

## PATH METHODS

- root\_dir

  Returns the root directory of the environment, i.e. where *.poet\_root* is located.

- path (subpath)

  Returns the root directory with a relative *subpath* added. e.g. 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 will be just below the root dirctory. e.g. 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. e.g. 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 to use for the specified class, depending on whether there is a subclass in the environment. e.g.

  ```
      $poet->app_class('Cache')
  ```

  will return `"MyApp::Cache"` if that module exists, and otherwise `"Poet::Cache"`.  This is used internally by Poet to implement auto subclassing.

- app\_name

  Returns the app name, e.g. 'MyApp', found in .poet\_root.

- conf

  Returns the Poet::Conf object associated with the environment. Usually you'd access this by importing `$conf`.

- current\_env

  A class method that returns the current (singleton) environment for the process. Usually you'd access this by importing `$poet`.

## OBTAINING $poet SINGLETON

In a script:

```
    use Poet::Script qw($poet);
```

In a module:

```
    use Poet qw($poet);
```

`$poet` is automatically available in components.

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. e.g.

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

With this 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
```

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