view release on metacpan or  search on metacpan

lib/Continuity.pm  view on Meta::CPAN

package Continuity;

our $VERSION = '1.6';

=head1 NAME

Continuity - Abstract away statelessness of HTTP, for stateful Web applications

=head1 SYNOPSIS

  #!/usr/bin/perl

  use strict;
  use Continuity;

  my $server = new Continuity;
  $server->loop;

  sub main {
    my $request = shift;
    $request->print("Your name: <form><input type=text name=name></form>");
    $request->next; # this waits for the form to be submitted!
    my $name = $request->param('name');
    $request->print("Hello $name!");
  }

=head1 DESCRIPTION

Continuity is a library to simplify web applications. Each session is written
and runs as a persistent application, and is able to request additional input
at any time without exiting. This is significantly different from the
traditional CGI model of web applications in which a program is restarted for
each new request.

The program is passed a C<< $request >> variable which holds the request
(including any form data) sent from the browser. In concept, this is a lot like
a C<$cgi> object from CGI.pm with one very very significant difference. At any
point in the code you can call $request->next. Your program will then suspend,
waiting for the next request in the session. Since the program doesn't actually
halt, all state is preserved, including lexicals -- getting input from the
browser is then similar to doing C<< $line = <> >> in a command-line
application.

=head1 GETTING STARTED

The first thing to make a note of is that your application is a continuously
running program, basically a self contained webserver. This is quite unlike a
CGI.pm based application, which is re-started for each new request from a
client browser. Once you step away from your CGI.pm experience this is actually
more natural (IMO), more like writing an interactive desktop or command-line
program.

Here's a simple example:

  #!/usr/bin/perl

  use strict;
  use Continuity;

  my $server = new Continuity;
  $server->loop;

  sub main {
    my $request = shift;
    while(1) {
      $request->print("Hello, world!");
      $request->next;
      $request->print("Hello again!");
    }
  }

First, check out the small demo applications in the eg/ directory of the
distribution. Sample code there ranges from simple counters to more complex
multi-user ajax applications. All of the basic uses and some of the advanced
uses of Continuity are covered there.

Here is an brief explanation of what you will find in a typical application.

Declare all your globals, then declare and create your server. Parameters to
the server will determine how sessions are tracked, what ports it listens on,
what will be served as static content, and things of that nature. You are
literally initializing a web server that will serve your application to client
browsers. Then call the C<loop> method of the server, which will get the server
listening for incoming requests and starting new sessions (this never exits).

  use Continuity;
  my $server = Continuity->new( port => 8080 );
  $server->loop;

Continuity must have a starting point when starting new sessions for your
application. The default is C<< \&::main >> (a sub named "main" in the default
global scope), which is passed the C<< $request >> handle. See the
L<Continuity::Request> documentation for details on the methods available from
the C<$request> object beyond this introduction.

  sub main {
    my $request = shift;
    # ...
  }

Outputting to the client (that is, sending text to the browser) is done by
calling the C<$request-E<gt>print(...)> method, rather than the plain C<print> used
in CGI.pm applications.

  $request->print("Hello, guvne'<br>");
  $request->print("'ow ya been?");

HTTP query parameters (both GET and POST) are also gotten through the
C<$request> handle, by calling C<$p = $request-E<gt>param('x')>, just like in
CGI.pm.