.\" -*- 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.