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

# Poet::Import(3pm)

## 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 to import certain variables (known as "quick vars") and utility sets into any script or module in your environment.

In a script:

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

and in a module:

```
    use Poet qw(...);
```

where `"..."` contains one or more quick var names (e.g. `$conf`, `$poet`) and/or utility tags (e.g. `":file"`, `":web"`).

(Note that `"use Poet::Script"` is also necessary for initializing the environment, even if you don't care to import anything, whereas `"use Poet"` has no effect other than importing.)

## QUICK VARS

Here is the built-in list of quick vars you can import. Some of the variables are singletons, and some of them are specific to each package they are imported into.

- $poet

  The global environment object, provided by Poet::Environment. This provides information such as the root directory and paths to subdirectories.

  For backward compatibility this is also available as `$env`.

- $conf

  The global configuration object, provided by Poet::Conf.

- $cache

  The cache for the current package, provided by Poet::Cache.

- $log

  The logger for the current package, provided by Poet::Log.

## UTILITIES

### Default utilities

The utilities in Poet::Util::Debug are always imported, with no tag necessary.

### :file

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

### :web

This tag imports all the utilities in Poet::Util::Web. It is automatically included in all Mason components.

## MASON COMPONENTS

Every Mason component automatically gets this on top:

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

`"$m->cache"` and `"$m->log"` will get you the cache and log objects for a particular Mason component.

## CUSTOMIZING

### Adding variables

To 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.
    }
```

`"provide_dbh"` can return a single global value, or a dynamic value depending on `$caller`.

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);
```

### 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"} = ...;
    }
```

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