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

# Poet::Mason(3pm)

## NAME

Poet::Mason -- Mason settings and enhancements for Poet

## SYNOPSIS

```
    # In a conf file...
    mason:
      plugins:
        - Cache
        - TidyObjectFiles
        - +My::Mason::Plugin
      static_source: 1
      static_source_touch_file: ${root}/data/purge.dat
    # Get the main Mason instance
    my $mason = Poet::Mason->instance();
    # Create a new Mason object
    my $mason = Poet::Mason->new(...);
```

## DESCRIPTION

This is a Poet-specific Mason subclass. It sets up sane default settings, maintains a main Mason instance for handling web requests, and adds Poet-specific methods to `$m` (the Mason request object).

## CLASS METHODS

- get\_options

  Returns a hash of Mason options by combining default settings and configuration.

- instance

  Returns the main Mason instance used for web requests, which is created with options from get\_options.

- new

  Returns a new main Mason object, using options from get\_options. Unless you specifically need a new object, you probably want to call instance.

## DEFAULT SETTINGS

- •

  `"comp_root"` is set to `$poet`-\>comps\_dir, by default the `"comps"` subdirectory under the environment root.

- •

  `"data_dir"` is set to `$poet`-\>data\_dir, by default the `"data"` subdirectory under the environment root.

- •

  `"plugins"` is set to include Cache, HTMLFilters and RouterSimple.

- •

  `"cache_root_class"` (a parameter of the `"Cache"` plugin) is set to `"MyApp::Cache"` if it exists (replacing `"MyApp"` with your app name), otherwise `"Poet::Cache"`.

## CONFIGURATION

The Poet configuration entry 'mason', if any, will be treated as a hash of options that supplements and/or overrides the defaults above. If the hash contains 'extra\_plugins', these will be added to the default plugins. e.g.

```
    mason:
      static_source: 1
      static_source_touch_file: ${root}/data/purge.dat
      extra_plugins:
         - AnotherFavoritePlugin
```

## QUICK VARS AND UTILITIES

Poet inserts the following line at the top of of every compiled Mason component:

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

which means that `$conf`, `$poet`, and web utilities are available from every component.

## NEW REQUEST METHODS

Under Poet these additional web-related methods are available in the Mason request object, accessible in components via `$m` or elsewhere via `"Mason::Request->current_request"`.

- req ()

  A reference to the Plack::Request object. e.g.

  ```
      my $user_agent = $m->req->headers->header('User-Agent');
  ```

- res ()

  A reference to the Plack::Response object. e.g.

  ```
      $m->res->content_type('text/plain');
  ```

- abort (status)

  - clear\_and\_abort (status)

  These methods are overridden to set the response status before aborting, if *status* is provided. e.g. to send back a FORBIDDEN result:

  ```
      $m->clear_and_abort(403);
  ```

  This is equivalent to

  ```
      $m->res->status(403);
      $m->clear_and_abort();
  ```

  If a status is not provided, the methods work just as before.

- redirect (url\[, status\])

  Sets headers and status for redirect, then clears the Mason buffer and aborts the request. e.g.

  ```
      $m->redirect("http://somesite.com", 302);
  ```

  is equivalent to

  ```
      $m->res->redirect("http://somesite.com", 302);
      $m->clear_and_abort();
  ```

- not\_found ()

  Sets the status to 404, then clears the Mason buffer and aborts the request. e.g.

  ```
      $m->not_found();
  ```

  is equivalent to

  ```
      $m->clear_and_abort(404);
  ```

- session

  A shortcut for `"$m->req->session"`, the Plack session.  This is simply a persistent hash that you can read from and write to. It is tied to the user's browser session via cookies and stored in a file cache in the data directory (by default).

  ```
      my $value = $m->session->{key};
      $m->session->{key} = { some_complex => ['value'] };
  ```

- send\_json ($data)

  Output the JSON-encoded *$data*, set the content type to "application/json", and abort. e.g.

  ```
      method handle {
          my $data;
          # compute data somehow
          $m->send_json($data);
      }
  ```

  `"send_json"` is a shortcut for

  ```
      $m->clear_buffer;
      $m->print(JSON::XS::encode_json($data));
      $m->res->content_type("application/json");
      $m->abort();
  ```

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