File Coverage

lib/Leyland/Context.pm

Criterion	Covered	Total	%
statement	33	210	15.7
branch	0	84	0.0
condition	0	77	0.0
subroutine	11	37	29.7
pod	14	14	100.0
total	58	422	13.7

package Leyland::Context;

# ABSTRACT: The working environment of an HTTP request and Leyland response

use Moo;
use namespace::clean;

use Carp;
use Data::Dumper;
use JSON;
use Leyland::Exception;
use Leyland::Logger;
use Module::Load;
use Text::SpanningTable;
use Try::Tiny;
use XML::TreePP;

extends 'Plack::Request';

=head1 NAME

Leyland::Context - The working environment of an HTTP request and Leyland response

=head1 SYNOPSIS

	# every request automatically gets a Leyland::Context object, which
	# is available in your routes and your views:
	post '^/blog$' {
		my $post = Blog->new(
			subject => $c->params->{subject},
			user => $c->user,
			date => DateTime->now,
			text => $c->params->{text}
		);
		return $c->template('blog.html', { post => $post });
	}

	# by the way, since Leyland is RESTful, your application can accept
	# requests of any content type, making the above something like
	# this:
	post '^/blog$' accepts 'text/plain' {
		my $post = Blog->new(
			subject => $c->params->{subject},
			user => $c->user,
			date => DateTime->now,
			text => $c->data
		);
		return $c->template('blog.html', { post => $post });
	}

=head1 DESCRIPTION

The Leyland context object is the heart and soul of your application. Or
something. Anyway, it's an object that escorts an HTTP request to somewhere
in your application through its entire lifetime, up to the point where an
HTTP response is sent back to the client. This is quite similar to the
L context object.

The context object holds a lot of information about the request, such as
its content type, its method, the parameters/content provided with it,
the routes it matched in your application, etc. Your controllers and views
will mostly interact with this object, which apart from the information
mentioned just now, provides you with useful methods to generate the final
response, and perform other necessary operations such as logging.

The Leyland context object inherits from L, so you can
use all of its attributes and methods. But keep in mind that this class
performs some modifications on these methods, all documented in the
L section.

This document is for reference purposes only, please refer to L
for more information on using the context object.

=head1 EXTENDS

L

=head1 ATTRIBUTES

=head2 app

Holds the  object of the application.

=head2 cwe

Holds the L environment in which the application is running. This
is the C environment variable. See the C<-E> or C<--env> switch
in L for more information. Defaults to 'development'.

=head2 res

The L object used to respond to the client.

=head2 routes

An array reference of all routes matched by the request (there can be
more than one).

=head2 current_route

The index of the route to be invoked in the "routes" attribute above. By
default this would be the first route (i.e. index 0), unless Ces are
performed.

=head2 froutes

An array reference of all routes matched by an internal forward.

=head2 current_froute

The index of the route to be forwarded to in the "froutes" attribute above.
By default this would be the first route (i.e. index 0), unless Ces
are performed.

=head2 controller

The controller class of the current route.

=head2 wanted_mimes

An array reference of all media types the client accepts, ordered by
the client's preference, as defined by the "Accept" HTTP header.

=head2 want

The media type the L has decided to return to the
client.

=head2 lang

The language to use when localizing responses, probably according to the
client's wishes. Defaults to 'en' for English.

=head2 stash

A hash-ref of data meant to be available for the views/templates when
rendering resources.

=head2 user

Something (anything really) that describes the user that initiated the
request. This attribute will only be defined by the application, you are
free to choose whatever scheme of authentication as you wish, this attribute
is provided for your convenience. You will use the C method
to set the value of this attribute.

=head2 json

A L object for usage by routes as they see fit.

=head2 xml

An L object for usage by routes as they see fit.

=head2 _pass_next

Holds a boolean value indicating whether the route has decided to pass
the request to the next matching route. Not to be used directly.

=head2 _data

Holds the content of the HTTP request for POST and PUT requests after
parsing. Not to be used directly.

=cut

has 'app' => (
	is => 'ro',
	isa => sub { die "app must be a Leyland object" unless ref $_[0] && $_[0]->isa('Leyland') },
	required => 1,
	handles => ['cwe', 'views', 'config']
);

has 'res' => (
	is => 'lazy',
	isa => sub { die "res must be a Plack::Response object" unless ref $_[0] && $_[0]->isa('Plack::Response') }
);

has 'routes' => (
	is => 'ro',
	isa => sub { die "routes must be an array-ref" unless ref $_[0] && ref $_[0] eq 'ARRAY' },
	predicate => 'has_routes',
	writer => '_set_routes'
);

has 'current_route' => (
	is => 'ro',
	isa => sub { die "current_route must be an integer" unless $_[0] =~ m/^\d+$/ },
	default => sub { 0 },
	writer => '_set_current_route'
);

has 'froutes' => (
	is => 'ro',
	isa => sub { die "froutes must be an array-ref" unless ref $_[0] && ref $_[0] eq 'ARRAY' },
	predicate => 'has_froutes',
	writer => '_set_froutes',
	clearer => '_clear_froutes'
);

has 'current_froute' => (
	is => 'ro',
	isa => sub { die "current_froute must be an integer" unless $_[0] =~ m/^\d+$/ },
	default => sub { 0 },
	writer => '_set_current_froute'
);

has 'controller' => (
	is => 'ro',
	isa => sub { die "controller must be a scalar" if ref $_[0] },
	writer => '_set_controller'
);

has 'wanted_mimes' => (
	is => 'ro',
	isa => sub { die "wanted_mimes must be an array-ref" unless ref $_[0] && ref $_[0] eq 'ARRAY' },
	builder => '_build_mimes'
);

has 'want' => (
	is => 'ro',
	isa => sub { die "want must be a scalar" if ref $_[0] },
	writer => '_set_want'
);

has 'lang' => (
	is => 'ro',
	isa => sub { die "lang must be a scalar" if ref $_[0] },
	writer => 'set_lang',
	default => sub { 'en' }
);

has 'stash' => (
	is => 'ro',
	isa => sub { die "stash must be an hash-ref" unless ref $_[0] && ref $_[0] eq 'HASH' },
	default => sub { {} }
);

has 'user' => (
	is => 'ro',
	predicate => 'has_user',
	writer => 'set_user',
	clearer => 'clear_user'
);

has 'log' => (
	is => 'lazy',
	isa => sub { die "log must be a Leyland::Logger object" unless ref $_[0] && ref $_[0] eq 'Leyland::Logger' }
);

has 'json' => (
	is => 'ro',
	isa => sub { die "json must be a JSON object" unless ref $_[0] && ref $_[0] eq 'JSON' },
	default => sub { JSON->new->utf8(0)->convert_blessed }
);

has 'xml' => (
	is => 'ro',
	isa => sub { die "xml must be an XML::TreePP object" unless ref $_[0] && ref $_[0] eq 'XML::TreePP' },
	default => sub { my $xml = XML::TreePP->new(); $xml->set(utf8_flag => 1); return $xml; }
);

has '_pass_next' => (
	is => 'ro',
	default => sub { 0 },
	writer => '_set_pass_next'
);

has '_data' => (
	is => 'ro',
	predicate => '_has_data',
	writer => '_set_data'
);

=head1 OBJECT METHODS

Since this class extends L, it inherits all its methods,
so refer to Plack::Request for a full list. However, this module performs
some modifications on certain Plack::Request methods, all of which are
documented in the L section.

=head2 leyland

An alias for the "app" attribute.

=cut

sub leyland { shift->app }

=head2 has_routes()

Returns a true value if the request matched any routes.

=head2 has_froutes()

Returns a true value if the request has routes matched in an internal forward.

=head2 set_lang( $lang )

Sets the language to be used for localization.

=head2 has_user()

Returns a true value if the "user" argument has a value.

=head2 set_user( $user )

Sets the "user" argument with a new value. This value could be anything,
a simple string/number, a hash-ref, an object, whatever your app uses.

=head2 clear_user()

Clears the value of the "user" argument, if any. Useful for logout actions.

=head2 params()

A shortcut for C<< $c->parameters->as_hashref_mixed >>. Note that this
is read-only, so changes you make to the hash-ref returned by this method
are not stored. For example, if you run C<< $c->params->{something} = 'whoa' >>,
subsequent calls to C<< $c->params >> will not have the "something"
key.

=cut

sub params { shift->parameters->as_hashref_mixed }

=head2 data( [ $dont_parse ] )

Returns the data of the request for POST and PUT requests. If the data
is JSON or XML, this module will attempt to automatically convert it to a Perl
data structure, which will be returned by this method (if conversion will
fail, this method will return an empty hash-ref). Otherwise, the data will be returned
as is. You can force this method to return the data as is even if it's
JSON or XML by passing a true value to this method.

If the request had no content, an empty hash-ref will be returned. This is different
than version 0.003 and down where it would have returned C.

=cut

sub data {
	my ($self, $dont_parse) = @_;

	return {} unless $self->content_type && $self->content;

	return $self->_data if $self->_has_data;

	if ($self->content_type =~ m!^application/json! && !$dont_parse) {
		my $data = try { $self->json->decode($self->content) } catch { {} };
		return unless $data;
		$self->_set_data($data);
		return $self->_data;
	} elsif ($self->content_type =~ m!^application/(atom+)?xml! && !$dont_parse) {
		my $data = try { $self->xml->parse($self->content) } catch { {} };
		return unless $data;
		$self->_set_data($data);
		return $self->_data;
	} else {
		my $data = $self->content;
		$self->_set_data($data);
		return $self->_data;
	}

	return;
}

=head2 pass()

Causes Leyland to invoke the next matching route, if any, after this
request has finished (meaning it does not pass immediately). Since you
will most likely want to pass routes immediately, use C<< return $self->pass >>
in your routes to do so.

=cut

sub pass {
	my $self = shift;

	# are we passing inside an internal forward or externally?
	# in any case, do not allow passing if we don't have routes to pass to
	if ($self->has_froutes && $self->current_froute + 1 < scalar @{$self->froutes}) {
		$self->_set_current_froute($self->current_froute + 1);
		$self->_set_pass_next(1);
		return 1;
	} elsif (!$self->has_froutes && $self->current_route + 1 < scalar @{$self->routes}) {
		$self->_set_current_route($self->current_route + 1);
		$self->_set_pass_next(1);
		return 1;
	}

	return 0;
}

=head2 render( $tmpl_name, [ \%context, $use_layout ] )

=head2 template( $tmpl_name, [ \%context, $use_layout ] )

Renders the view/template named C<$tmpl_name> using the first view class
defined by the application. Anything in the C<$context> hash-ref will be
automatically available inside the template, which will be rendered inside
whatever layout template is defined, unless C<$use_layout> is provided
and holds a false value (well, 0 really). The context object (i.e. C<$c>)
will automatically be embedded in the C<$context> hash-ref under the name
"c", as well as the application object (i.e. C<< $c->app >>) under the
name "l". Anything in the stash (i.e. C<< $c->stash >>) will also be
embedded in the context hash-ref, but keys in C<$context> take precedence
to the stash, so if the stash has the key 'name' and C<$context> also has
the key 'name', then the one from C<$context> will be used.

Returns the rendered output. You will mostly use this at the end of your
routes as the return value.

The two methods are the same, C