.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. 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 2024-03-08 "perl v5.38.2" "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 URI 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
YAPC::NA talk .
.PP
To learn more about Webmachine, take a look at the links in the SEE ALSO
section.
.SH METHODS
.IX Header "METHODS"
NOTE: 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(CWinit()\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 PSGI 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 PSGI \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 PSGI 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 STDERR.
.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(CWdiag()\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 JS port \- " 4
.IX Item "Node JS port - "
.IP "Python port \- " 4
.IX Item "Python port - "
.IP "2012 YAPC::NA 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 SJ 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.