.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Web::Machine 3pm"
.TH Web::Machine 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Web::Machine \- A Perl port of Webmachine
.SH "VERSION"
.IX Header "VERSION"
version 0.17
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use strict;
\& use warnings;
\&
\& use Web::Machine;
\&
\& {
\& package HelloWorld::Resource;
\& use strict;
\& use warnings;
\&
\& use parent \*(AqWeb::Machine::Resource\*(Aq;
\&
\& sub content_types_provided { [{ \*(Aqtext/html\*(Aq => \*(Aqto_html\*(Aq }] }
\&
\& sub to_html {
\& q{
\&
\& Hello World Resource
\&
\&
\& Hello World
\&
\& }
\& }
\& }
\&
\& Web::Machine\->new( resource => \*(AqHelloWorld::Resource\*(Aq )\->to_app;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Web::Machine\*(C'\fR provides a RESTful web framework modeled as a state
machine. You define one or more resource classes. Each resource represents a
single RESTful \s-1URI\s0 end point, such as a user, an email, etc. The resource
class can also be the target for \f(CW\*(C`POST\*(C'\fR requests to create a new user, email,
etc.
.PP
Each resource is a state machine, and each request for a resource is handled
by running the request through that state machine.
.PP
\&\f(CW\*(C`Web::Machine\*(C'\fR is built on top of Plack, but it handles the full request
and response cycle.
.PP
See Web::Machine::Manual for more details on using \f(CW\*(C`Web::Machine\*(C'\fR in
general, and how \f(CW\*(C`Web::Machine\*(C'\fR and Plack interact.
.PP
This is a port of Webmachine , actually
it is much closer to the Ruby
version , with a little bit of
the JavaScript version and
even some of the Python version
thrown in for good measure.
.PP
You can learn a bit about Web::Machine's history from the slides for my 2012
\&\s-1YAPC::NA\s0 talk .
.PP
To learn more about Webmachine, take a look at the links in the \s-1SEE ALSO\s0
section.
.SH "METHODS"
.IX Header "METHODS"
\&\s-1NOTE:\s0 This module is a Plack::Component subclass and so follows the interface
set forward by that module.
.ie n .IP """new( resource => $resource_classname, ?resource_args => $arg_list, ?tracing => 1|0, ?streaming => 1|0, ?request_class => $request_class )""" 4
.el .IP "\f(CWnew( resource => $resource_classname, ?resource_args => $arg_list, ?tracing => 1|0, ?streaming => 1|0, ?request_class => $request_class )\fR" 4
.IX Item "new( resource => $resource_classname, ?resource_args => $arg_list, ?tracing => 1|0, ?streaming => 1|0, ?request_class => $request_class )"
The constructor expects to get a \f(CW$resource_classname\fR, which it will use to
load and create an instance of the resource class. If that class requires any
additional arguments, they can be specified with the \f(CW\*(C`resource_args\*(C'\fR
parameter. The contents of the \f(CW\*(C`resource_args\*(C'\fR parameter will be made
available to the \f(CW\*(C`init()\*(C'\fR method of \f(CW\*(C`Web::Machine::Resource\*(C'\fR.
.Sp
The \f(CW\*(C`new\*(C'\fR method can also take an optional \f(CW\*(C`tracing\*(C'\fR parameter which it will
pass on to Web::Machine::FSM and an optional \f(CW\*(C`streaming\*(C'\fR parameter, which
if true will run the request in a \s-1PSGI\s0 streaming
response. This can be useful if you need to run your content generation
asynchronously.
.Sp
The optional \f(CW\*(C`request_class\*(C'\fR parameter accepts the name of a module that will
be used as the request object. The module must be a class that inherits from
Plack::Request. Use this if you have a subclass of Plack::Request that
you would like to use in your Web::Machine::Resource.
.ie n .IP """inflate_request( $env )""" 4
.el .IP "\f(CWinflate_request( $env )\fR" 4
.IX Item "inflate_request( $env )"
This takes a raw \s-1PSGI\s0 \f(CW$env\fR and inflates it into a Plack::Request instance.
By default this also uses HTTP::Headers::ActionPack to inflate the headers
of the request to be complex objects.
.ie n .IP """create_fsm""" 4
.el .IP "\f(CWcreate_fsm\fR" 4
.IX Item "create_fsm"
This will create the Web::Machine::FSM object to run. It will get passed
the value of the \f(CW\*(C`tracing\*(C'\fR constructor parameter.
.ie n .IP """create_resource( $request )""" 4
.el .IP "\f(CWcreate_resource( $request )\fR" 4
.IX Item "create_resource( $request )"
This will create the Web::Machine::Resource instance using the class specified
in the \f(CW\*(C`resource\*(C'\fR constructor parameter. It will pass in the \f(CW$request\fR object
and call \f(CW\*(C`new_response\*(C'\fR on the \f(CW$request\fR object to get a Plack::Response
instance.
.ie n .IP """finalize_response( $response )""" 4
.el .IP "\f(CWfinalize_response( $response )\fR" 4
.IX Item "finalize_response( $response )"
Given a \f(CW$response\fR which is a Plack::Response object, this will finalize
it and return a raw \s-1PSGI\s0 response.
.ie n .IP """call( $env )""" 4
.el .IP "\f(CWcall( $env )\fR" 4
.IX Item "call( $env )"
This is the \f(CW\*(C`call\*(C'\fR method overridden from the Plack::Component superclass.
.SH "DEBUGGING"
.IX Header "DEBUGGING"
If you set the \f(CW\*(C`WM_DEBUG\*(C'\fR environment variable to \f(CW1\fR we will print
out information about the path taken through the state machine to \s-1STDERR.\s0
.PP
If you set \f(CW\*(C`WM_DEBUG\*(C'\fR to \f(CW\*(C`diag\*(C'\fR then debugging information will be printed
using Test::More's \f(CW\*(C`diag()\*(C'\fR sub instead.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "The diagram \- " 4
.IX Item "The diagram - "
.PD 0
.IP "Original Erlang \- " 4
.IX Item "Original Erlang - "
.IP "Ruby port \- " 4
.IX Item "Ruby port - "
.IP "Node \s-1JS\s0 port \- " 4
.IX Item "Node JS port - "
.IP "Python port \- " 4
.IX Item "Python port - "
.IP "2012 \s-1YAPC::NA\s0 slides \- " 4
.IX Item "2012 YAPC::NA slides - "
.IP "an elaborate machine is indispensable: a blog post by Justin Sheehy \- " 4
.IX Item "an elaborate machine is indispensable: a blog post by Justin Sheehy - "
.IP "Resources, For Real This Time (with Webmachine): a video by Sean Cribbs \- " 4
.IX Item "Resources, For Real This Time (with Webmachine): a video by Sean Cribbs - "
.PD
.SH "SUPPORT"
.IX Header "SUPPORT"
bugs may be submitted through .
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little
.IP "\(bu" 4
Dave Rolsky
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Andreas Marienborg
.IP "\(bu" 4
Andrew Nelson
.IP "\(bu" 4
Arthur Axel 'fREW' Schmidt
.IP "\(bu" 4
Carlos Fernando Avila Gratz
.IP "\(bu" 4
Fayland Lam
.IP "\(bu" 4
George Hartzell
.IP "\(bu" 4
Gregory Oschwald
.IP "\(bu" 4
Jesse Luehrs
.IP "\(bu" 4
John \s-1SJ\s0 Anderson
.IP "\(bu" 4
Mike Raynham
.IP "\(bu" 4
Nathan Cutler
.IP "\(bu" 4
Olaf Alders
.IP "\(bu" 4
Stevan Little
.IP "\(bu" 4
Thomas Sibley
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2016 by Infinity Interactive, Inc.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.