poet::util::debug(3pm) [debian man page]

Poet::Util::Debug(3pm)					User Contributed Perl Documentation				    Poet::Util::Debug(3pm)

NAME

       Poet::Util::Debug - Debug utilities

SYNOPSIS

	   # In a script...
	   use Poet::Script;

	   # In a module...
	   use Poet;

	   # Automatically available in Mason components

	   # then...

	   # die with value
	   dd $data;

	   # print value to STDERR
	   dp $data;

	   # print value to logs/console.log
	   dc $data;

	   # return value prepped for HTML
	   dh $data;

	   # same as above with full stacktraces
	   dds $data;
	   dps $data;
	   dcs $data;
	   dhs $data;

DESCRIPTION

       These debug utilities are automatically imported wherever "use Poet" or "use Poet::Script" appear, and in all components. Because let's
       face it, debugging is something you always want at your fingertips.

       However, for safety, the short named versions of these utilities are no-ops outside of development mode, in case debug statements
       accidentally leak into production (we've all done it). You have to use longer, less convenient names outside of development for them to
       work.

UTILITIES

       Each of these utilities takes a single scalar value. The value is serialized with Data::Dumper and prefixed with a file name, line number,
       and pid. e.g.

	   dp { a => 5, b => 6 };

       prints to STDERR

	   [dp at ./d.pl line 6.] [1436] {
	     a => 5,
	     b => 6
	   }

       The variants suffixed with 's' additionally output a full stack trace.

       dd ($val), dds ($val)
	   Die with the serialized $val.

       dp ($val), dps ($val)
	   Print the serialized $val to STDERR. Useful in scripts.

       dc ($val), dcs ($val)
	   Append the serialized $val to "console.log" in the "logs" subdirectory of the environment. Useful as a quick alternative to full-bore
	   logging.

       dh ($val), dhs ($val)
	   Returns the serialized $val, surrounded by "<pre> </pre>" tags. Useful for embedding in Mason components, e.g.

	       <% dh($data) %>

   Live variants
       Each of the functions above must be appended with "_live" in order to work in live mode. e.g.

	   # This is a no-op in live mode
	   dp [$foo];

	   # but this will work
	   dp_live [$foo];

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.

perl v5.14.2							    2012-06-05						    Poet::Util::Debug(3pm)

Poet::Mason(3pm)					User Contributed Perl Documentation					  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

       o   "comp_root" is set to $poet->comps_dir, by default the "comps" subdirectory under the environment root.

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

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

       o   "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.

perl v5.14.2							    2012-06-14							  Poet::Mason(3pm)