To get us started with Web development and Perl, we’re going to use Plack (http://plackperl.org/). We won’t be doing anything too complicated, but we’ll see the basics of how it works. You can install Plack with your favorite CPAN client:

$ cpan PSGI Plack

Plack and PSGI were created by Tatsuhiko Miyagawa, an extremely talented and prolific programmer. PSGI is a specification of how a Web server can talk to a Web application. It is modeled after WSGI, a Web server/application interface originally developed for the Python language. Plack is an implementation of the PSGI specification.

Prior to PSGI, many companies found themselves having to choose between different Web servers that accept HTTP requests and Web applications that might process those requests. When the server receives a request that should be handled by an application, it needed to know how to talk to that application and the application needed to know how to respond.

PSGI changes the game tremendously. It sits between the Web server and the Web application, guaranteeing a standard Web interface. As long as both your Web server and Web application “speak” PSGI (today, you’ll find that your popular options all understand PSGI), you can switch to different servers or applications without having to reconfigure how they talk to one another. This is one of many examples of why Perl is duct tape in the web world.

Now it’s time to show you what we really mean. Be aware that Plack is actually a set of building blocks for Web applications and is not intended to be used by application developers directly. However, it’s easy to use and a great compromise between showing how web applications work and how HTTP operates.

Create a chapter15/ directory, change into it, and save the following as app.psgi:

my $app = sub {
    return [
        200,
        [ 'Content-Type' => 'text/plain' ],
        ['Hello World'],
    ];
};

A Plack application is a code reference. It’s expected to return an array reference with three values:

Once you have saved the app.psgi, run plackup (it’s installed when you install Plack):

$ plackup
HTTP::Server::PSGI: Accepting connections at http://0:5000/

$ plackup hello.psgi

Congratulations! You now have a Web server running on your computer.

When you run plackup, it will start a Web server for you. You can configure it to use different Web servers, but we’ll use the default HTTP::Server::PSGI Web server that is installed with Plack.

The plackup command will appear to hang, but that’s because it is waiting for requests. Open your favorite browser and go to http://localhost:5000/. You should see the text Hello World displayed. After you see the page, look at your terminal window that plackup is running in. You’ll see something like this (reformatted for the book, this is all on two lines):

HTTP::Server::PSGI: Accepting connections at http://0:5000/
127.0.0.1 - - [11/Apr/2012:11:42:13 +0200] "GET / HTTP/1.1" 200 11 "-"
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.19
(KHTML,like Gecko) Chrome/18.0.1025.151 Safari/535.19"

The first line tells us that HTTP::Server::PSGI is listening on port 5000.

The second line shows a request from IP address 127.0.0.1 (your browser) came in at a particular time and issued an HTTP GET / request. It also contains information about the response code (200 OK in this case) and the type of client that attempted to connect.

With our simple Web application, connecting to any path, such as http://localhost:5000/asdf/asdf will display Hello World because that’s all you’ve programmed it to do. Let’s quickly expand this to take a look at our environment. Stop plackup (CTRL-C) and edit your app.psgi to look like this:

use strict;
use warnings;
use Data::Dumper;
$Data::Dumper::Indent   = 1;
$Data::Dumper::Sortkeys = 1;
$Data::Dumper::Terse    = 1;
my $app = sub {
    my $environment = Dumper( \%ENV );
    return [
        200,
        [ 'Content-Type' => 'text/plain' ],
        [ "Hello World\n", $environment ],
    ];
};

Restart plackup and refresh your browser page with http://localhost:5000/. You should now see Hello World, followed by a hash listing all of your environment variables. Here is an edited version of what your author’s browser shows:

Hello World
{
    'EDITOR'       => '/usr/bin/vim',
    'GIT_USER'     => 'ovid',
    'HISTFILESIZE' => '1000000000',
    'HISTSIZE'     => '1000000',
    'LC_CTYPE'     => 'UTF-8',
    'LOGNAME'      => 'ovid',
    'PLACK_ENV'    => 'development',
    'PWD'          => '/Users/ovid/beginning_perl/book/chapter15',
    'SHELL'        => '/bin/bash',
    'TERM'         => 'xterm-256color',
    'TERM_PROGRAM' => 'iTerm.app',
}

Let’s rewrite our app.psgi again to get a little closer to a real world example. This time we’ll add an image. Save the following in your app.psgi file:

use strict;
use warnings;
my $app = sub {
    my $env = shift;
    if ( $env->{PATH_INFO} eq '/anne_frank_stamp.jpg' ) {
        open my $fh, "<:raw", "anne_frank_stamp.jpg" or die $!;
        return [ 200, [ 'Content-Type' => 'image/jpeg' ], $fh ];
    }
    elsif ( $env->{PATH_INFO} eq '/' ) {
        return [
          200,
          [ 'Content-Type' => 'text/html' ],
          [ get_index() ]
        ];
    }
    else {
        return [
          404,
          [ 'Content-Type' => 'text/html' ],
          ['404 Not Found']
        ];
    }
};
sub get_index {
    return <<'END';
<html>
  <head><title>Sample page</title></head>
  <body>
    <p>Anne Frank was a young lady living in Amsterdam, hiding
    from the Nazis.</p>
    <p>Everyone should read her diaries.</p>
    <img src="/anne_frank_stamp.jpg"/>
  </body>
</html>
END
}

This program loads an image of the German Anne Frank stamp. It is in the public domain and is available at http://commons.wikimedia.org/wiki/File:Anne_Frank_stamp.jpg. Download this image and save as anne_frank_stamp.jpg and save it in the same directory as your app.psgi file.

Restart plackup and go to http://localhost:5000/. You should see a Web page similar to Figure 15.1, “Figure 15-1”.

Figure 15.1. Figure 15-1

This is all pretty normal, but let’s look at the opening lines of the $app subroutine reference:

my $env = shift;
if ( $env->{PATH_INFO} eq '/anne_frank_stamp.jpg' ) {
    open my $fh, "<:raw", "anne_frank_stamp.jpg" or die $!;
    return [ 200, [ 'Content-Type' => 'image/jpeg' ], $fh ];
}

The Plack subroutine reference is passed a single $env hashref argument, documented in perldoc PSGI. The PATH_INFO key points to the currently requested path. In this case, because we are asking for the Anne Frank image, we use open to create a filehandle, return image/jpeg as the content type and the filehandle is returned as the content of the request. Plack knows how to send that image back to your client.

When we navigate to http://localhost:5000/ in our browser, the following line of code is executed:

return [ 200, [ 'Content-Type' => 'text/html' ], [ get_index() ] ];

And that returns the HTML from the get_index() function:

sub get_index {
    return <<'END';
<html>
  <head><title>Sample page</title></head>
  <body>
    <p>Anne Frank was a young lady living in Amsterdam, hiding
    from the Nazis.</p>
    <p>Everyone should read her diaries.</p>
    <img src="/anne_frank_stamp.jpg"/>
  </body>
</html>
END

In that HTML is an img tag:

<img src="/anne_frank_stamp.jpg"/>

That tag causes the browser to issue GET /anne_frank_stamp.jpg to our Plack server. Our app.psgi sees that path and returns the image.

In other words, you went to the http://localhost:5000/ URL in your browser, but your browser actually makes two requests to the server. In fact, for most Web pages on the Internet, a single page will generate many more requests to get everything the page needs to render properly, including the HTML, Javascript, CSS, multiple images, Flash, and many other potential requests. It actually can seem quite complicated, as you can see from the example above, much of this is handled for you and it’s really not as hard as it seems.

Now let’s rewrite app.psgi one last time before moving to the next section.

use strict;
use warnings;
use Plack::Builder;
builder {
    mount '/anne_frank_stamp.jpg' => sub {
        open my $fh, "<:raw", "anne_frank_stamp.jpg" or die $!;
        return [ 200, [ 'Content-Type' => 'image/jpeg' ], $fh ];
    };
    mount '/' => sub {
        my $env = shift;
        return $env->{PATH_INFO} eq '/'
          ? [200,['Content-Type' => 'text/html'],[get_index()]]
          : [404,['Content-Type' => 'text/html'],['404 Not Found']];
    };
};
sub get_index {
    return <<'END';
<html>
  <head><title>Sample page</title></head>
  <body>
    <p>Anne Frank was a young lady living in Amsterdam, hiding
    from the Nazis.</p>
    <p>Everyone should read her diaries.</p>
    <img src="/anne_frank_stamp.jpg"/>
  </body>
</html>
END
}

Plack::Builder is a module that provides a DSL (domain-specific language) to make writing Plack applications a little bit easier. This app.psgi does the same thing as our last app.psgi, but it does so with the builder and mount commands. The builder function says “I’m going to take the following code reference and use this to build the app”.

The mount function allows you to map a particular path to a particular section of code. This is much easier than managing long if/else/elsif blocks. We do have a ?: ternary operator in the / path, but that’s only to show that we can still use this if needed.

The mount command is implemented with Plack::App::URLMap and it does not allow “dynamic” mappings. Thus, there’s no way to say “everything that is not mapped is a 404”. Web frameworks like Dancer, Catalyst and Mojolicious give you much more flexibility here, but this is enough for us to do what we need.

Many times you’ll see a URL like this:

http://www.example.com/?name=john&color=blue&color=red

The question mark in a URL indicates the beginning of a query string. A query string is defined in RFC 3986 (http://www.ietf.org/rfc/rfc3986.txt). It’s a collection of name/value pairs. Each name and value is separated by an equals (=) sign and each pair is separated by an ampersand (&) or a semicolon (;). In the example above, we have two parameters, name and color. The name has one value, john, and color has two values, blue and red. We’re going to use Plack::Request to handle query strings.

Save the following code as params.psgi:

use strict;
use warnings;
use Plack::Builder;
use Plack::Request;
builder {
    mount '/' => sub {
        my $env     = shift;
        my $request = Plack::Request->new($env);
        my @params  = sort $request->param;
        my $body    = '';
        foreach my $param (@params) {
            my $values = join ',' => $request->param($param);
            $body .= "$param=$values\n";
        }
        $body ||= "No params found";
        return [ 200, [ 'Content-Type' => 'text/plain' ], [$body] ];
    };
};

Open a separate terminal window and run the following command:

plackup -r params.psgi

By using -r with plackup, we can have plackup running in one terminal window while we continue to develop in another terminal window.

When you request http://localhost:5000/ in your browser, it should display:

No params found

However, request http://localhost:5000/?name=john;color=red;color=blue and you should see this in your browser window.

color=red,blue
name=john

By now, you may be tired of returning a 3-element array reference because it can be a bit harder to read:

return [ 200, [ 'Content-Type' => 'text/plain' ], [$body] ];

We can replace that return statement with a response object. It’s much easier to read:

my $response = $request->new_response(200);
$response->content_type('text/plain');
$response->content($body);
return $response->finalize;

The $response->finalize handles building and returning that final array reference for you.

Up until now, we’ve included our HTML in our code. While that might be fine for small application, it’s can be hard to maintain for larger applications, particularly as you code becomes a mess of Perl, HTML, plain text, SQL (we’ll cover databases in the Chapter 16, Databases).

As a general rule, you want the different logical sections of your programs separated. One common way of doing this is using what is known as the Model-View-Controller pattern, more commonly referred to as MVC. There are a few variants of MVC, but we’ll cover a popular one for the Web.

We’re not going to show a full-blown MVC system here, but the basic components are described in Table 15.1, “Table 15-1”.

So someone visits your Web page, the view, enters a number on a form and that data gets sent to a controller (the mount points, in our PSGI example), The controller receives the data and passes it to the correct model (the sub references in our examples) and returns the results to a view.

In Plack, there’s really not a clean separation of these concepts, but we can fake it well enough to give you an idea of what’s going on. So we’re going to create small templates with Template::Tiny to give you an idea of what’s going on.

Template::Tiny is a very small templating engine written by Adam Kennedy. It is designed to be minimal, fast, and appropriate for small applications. In short, it’s what we need. Later, you’d want to use the Template Toolkit module (the package name of the module is Template), Text::Xslate or other more robust templating modules than Template::Tiny.

First, in the same directory as your app.psgi and your params.psgi, create a templates directory. In that directory, create a file names params.tt that contains the following:

<html>
  <head><title>Parameters</title></head>
  <body>
[% IF have_params %]
    <p>Our list of params:</p>
    <table rules="all">
      <tr><th>Name</th><th>Value</th></tr>
  [% FOREACH param IN params %]
      <tr><td>[% param.name %]</td><td>[% param.value %]</td></tr>
  [% END %]
    </table>
[% ELSE %]
    <p><strong>No params supplied!</strong></p>
[% END %]
  </body>
</html>

At this point, our directory structure (assuming you’ve been typing in all the examples), should look like this:

./
|--anne_frank_stamp.jpg
|--app.psgi
|--params.psgi
|  templates/
|  |--params.tt

This HTML code with the strange syntax is Template::Tiny syntax. Template::Tiny actually doesn’t know anything about HTML. It does nothing except handle loops, if/else/unless statements and variable interpolation. All Template::Tiny commands are wrapped in [% %] brackets.

Consider the following hash reference:

{
    have_params => 1,
    params      => [
        { param => 'name',  value => 'john'     },
        { param => 'color', value => 'red,blue' },
    ],
}

If you process the above Template::Tiny template with this hash reference, this tag:

[% IF have_params %]

Will evaluate to true, passing control to the block with the <table> HTML tag. In that, you’ll see this:

[% FOREACH param IN params %]
      <tr><td>[% param.name %]</td><td>[% param.value %]</td></tr>
[% END %]

The [% FOREACH param IN params %] will iterate over the params array reference, setting param to each contained hash reference, in turn. Then when you call [% param.name %] and [% param.value %], it’s identical to calling $param->{name} and $param->{value}. In Perl code, the entire template would look like this (omitting the HTML for clarity):

my $hashref = { ... };
if ( $hashref->{have_params} ) {
    foreach my $param (@{ $hashref->{params} }) {
        print $param->{name},$param->{value};
    }
}
else {
    print "No params supplied!";
}

And that’s pretty much the entire Template::Tiny syntax. And here’s how we use it in our new params.psgi. We’re going to use File::Slurp to make reading the template code a bit easier.

use strict;
use warnings;
use Plack::Builder;
use Plack::Request;
use Template::Tiny;
use File::Slurp 'read_file';
builder {
    mount '/' => sub {
        my $env     = shift;
        my $request = Plack::Request->new($env);
        my @params;
        foreach my $param ( sort $request->param ) {
            my $values = join ',' => $request->param($param);
            push @params => { name => $param, value => $values };
        }
        my $content = get_content(
            'templates/params.tt',
            {
                params      => \@params,
                have_params => scalar @params,
            }
        );
        my $response = $request->new_response(200);
        $response->content_type('text/html');
        $response->content($content);
        return $response->finalize;
    };
};
sub get_content {
    my ( $file, $vars ) = @_;
    my $template_code = read_file($file);
    my $output;
    my $template      = Template::Tiny->new;
    $template->process( \$template_code, $vars, \$output );
    return $output;
}

We build up an array reference of parameters and pass that, along with the template name to the get_content subroutine. We use read_file from File::Slurp to read the contents of the template. We then pass the contents of the file as a scalar reference as the first argument to the instantiated Template::Tiny object. The hash referee of variables is passed as the second argument and a reference to the scalar containing our output is the third argument. (The syntax is a bit odd to maintain forward compatibility with the Template Toolkit module).

my $output;
my $template      = Template::Tiny->new;
$template->process( \$template_code, $vars, \$output );
return $output;

Once the template is processed, we return the output variable and set that as our $response->content.

Now, we you visit http://localhost:5000/, you should see this on your Web page:

No params supplied!

When you visit http://localhost:5000/?name=john;color=red;color=blue;job=janitor you should see a page that looks vaguely like this:

Our list of params:
Name    Value
color   red,blue
job     janitor
name    john

It’s not a pretty Web page, but now you can see how we’re separating out the view (sometimes called the presentation layer) from the main logic of our code.

In fact, at this point we could even take our some code from our anonymous subroutine and put that into a module in lib/ and start making the params.cgi a very tiny controller, with your model in lib/ and your view in templates/. As we’ve mentioned, though, if we start trying to do too much in Plack, it’s time to look at a real Web framework.

One last caveat: what do you think happens if you visit this URL?

http://localhost/?job=%3Chr/%3E%3Cstrong%3Ehi%20there!%3C/strong%3E

That’s the URL encoded form of this:

http://localhost/?job=<hr/><strong>hi there!</strong>

The exact appearance will depend on your browser, but basically, in the Value column, you should see hi there! in bold print with a line above it. Why? Because this is that line in the template after the value is added:

<tr><td>job</td><td><hr/><strong>hi there!</strong></td></tr>

This is sadly a common problem on the Web. People write Web applications and forget to encode user supplied data before sending it to a Web page. To fix this, add the following line to your code:

use HTML::Entities 'encode_entities';

And when you push the parameters onto the array:

push @params => { name => $param, value => $values };

Change it to this:

push @params => {
    name  => encode_entities($param),
    value => encode_entities($values)
};

Now when you visit that URL, you should see something like this:

Name    Value
job     <hr/><strong>hi there!</strong>

And if you look at the source code, you’ll see this (formatted to fit the page):

<tr>
  <td>job</td>
  <td>&lt;hr/&gt;&lt;strong&gt;hi there!&lt;/strong&gt;</td>
</tr>

The encode_entities function from HTML::Entities will encode strings into their corresponding HTML entities. For example, < becomes < and > becomes >.

There are hundreds of pre-defined character entities for HTML and they’re beyond the scope of what we’re doing here, but see http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references for a complete list. For the brave, you can also read the w3c specification: http://www.w3.org/TR/REC-html40/sgml/entities.html. Be warned, though: W3C specifications are not designed to be easy to read. They’re designed to be complete.

So far we’ve been handling GET requests. If you wish to pass extra data to the page, you do so via the query string in the URL. However, if you have data that should not be in a URL, such as a username and password, someone’s going to be very upset when they share that URL with someone before they notice that they’re sharing their private data.

This is where POST comes in. In HTTP, your client would send a POST request that looks similar to this:

POST /login HTTP/1.1
Content-Length: 31
Content-Type: application/x-www-form-urlencoded
Host: localhost:5000
Origin: http://localhost:5000
Referer: http://localhost:5000/login

username=ovid&password=youwish

In the example above, the POST tells the server that the data is in the entity body. The entity body begins after two consecutive newlines (after the Referer: header in the example above. Because the POST content is sent in the entity body, it will not show up in the URL.

Let’s create a login page. This page doesn’t really “work” in the sense of allowing you to login (hey, this is an intro!), but it shows how a POST request works and also lets us see a bit more refactoring of the params.psgi application.

First, create templates/login.tt with the following:

<html>
  <head><title>Login</title></head>
  <body>
    <fieldset>
      <legend>Pretend to Login, please</legend>
      <form action="/login" method="POST">
        <table>
          <tr><td>Username</td><td><input type="text"
            name="username" /></td></tr>
          <tr><td>Password</td><td><input type="password"
            name="password" /></td></tr>
        </table>
        <div align="center"><input type="submit" value="Submit" /></div>
      </form>
  </body>
</html>

This doesn’t actually have any template parameters in it and there’s better ways of handling it then putting it in templates/, but this is fine for our purposes. Note that the form’s action sends us back to /login, because that path is what will handle the “login” request.

When you render that HTML, it should resemble Figure 15.2, “Figure 15-2”.

Figure 15.2. Figure 15-2

Now to see how to render it. Modify your params.psgi to contain the following code:

use strict;
use warnings;
use Plack::Builder;
use Plack::Request;
use Template::Tiny;
use File::Slurp 'read_file';
use HTML::Entities 'encode_entities';
builder {
    mount '/' => sub {
        my $env     = shift;
        my $request = Plack::Request->new($env);
        my @params  = get_params_array($request);
        my $content = get_content(
            'templates/params.tt',
            {
                params      => \@params,
                have_params => scalar @params,
            }
        );
        return response( $request, $content );
    };
    mount '/login' => sub {
        my $request = Plack::Request->new(shift);
        my $content;
        if ( $request->param('username') && $request->param('password') ) {
            my @params = get_params_array($request);
            $content = get_content(
                'templates/params.tt',
                {
                    params      => \@params,
                    have_params => scalar @params,
                }
            );
        }
        else {
            $content = get_content('templates/login.tt');
        }
        return response( $request, $content );
    };
};
sub get_params_array {
    my $request = shift;
    my @params;
    foreach my $param ( sort $request->param ) {
        my $values = join ',' => $request->param($param);
        push @params => {
            name  => encode_entities($param),
            value => encode_entities($values)
        };
    }
    return @params;
}
sub response {
    my ( $request, $content ) = @_;
    my $response = $request->new_response(200);
    $response->content_type('text/html');
    $response->content($content);
    return $response->finalize;
}
sub get_content {
    my ( $file, $vars ) = @_;
    $vars ||= {};
    my $template_code = read_file($file);
    my $template      = Template::Tiny->new;
    my $output;
    $template->process( \$template_code, $vars, \$output );
    return $output;
}

We have factored out our response() generation into its own subroutine. The code to get the content for the parameters has also been factored into get_params_array(). It takes the request as an argument and returns the array of parameter key/value pairs. That leaves us with our builder section,

You can still recognize the / path once you understand the get_params_array() and response() code. It does the same thing it did before. Our “login” code merely checks to see that we have POSTed both a username and a password (any will do). If you haven’t, it will render the login form. If you have, it will render the templates/params.tt page that we saw from our previous example.

Try it now by going to http://localhost:5000/login. Any username and password combination should return the template that shows the values you entered. For example, if you entered ovid and youwish for your username and password, you should see this:

Our list of params:
Name      Value
password  youwish
username  ovid

The URL, however, remains http://localhost:5000/login. As far as Plack::Request (and many other request handlers) are concerned, it makes no difference if it read your params from a POST or a GET. Thus, even if you switch this to a GET request, you’ll still see the table listing params:

http://localhost:5000/login?username=ovid;password=youwish

You can protect against this, if you wish, by only allowing processing of the username and password with a POST request method.

if (   'POST' eq $request->method
    && $request->param('username')
    && $request->param('password') )
{
    return response( $request, get_params_content($request) );
}

Your author would ask, at this point, for all serious Web professionals to turn to the next section and ignore the horrible, horrible abuse of sessions that will happen here.

HTTP is, by design, a stateless protocol. This means that each request is independent of every other request. In the early days of the Web, every time you visited a Web page, the server had no idea you had been there before. Then a Netscape employee named Lou Montulli had the brilliant idea of taking “magic cookies” (no, not the type you buy in Amsterdam), which were already in use in other software, and implementing them in Netscape Navigator, a browser popular back in the mid-to-late 1990s. This was one of the most important events in the history of the Web. Now, if a browser returns a cookie to a host, the host can know that the user had previously visited.

In the code that follows, Plack::Session uses cookies to pass a session key back and forth between the Plack software and the client. The Plack software will use the value of the cookie to look up its in-memory session data. Because this data is not persistent, it will not survive between server restarts. In serious production applications, session data is generally saved in a persistent state, such as in a database or memcached.

Now let the abuse begin!

First, you need to install Plack::Middleware::Session from the CPAN. Then, at the top of your params.psgi, after the modules you use, add the following two lines:

use Plack::Session;
use constant SESSION_TIME => 30;

The session time is in seconds. We’re only use 30 second sessions because your author is sadistic. Feel free to adjust that to taste.

Next, add the following two subroutines:

sub time_remaining {
    my $session = shift;
    my $remaining = SESSION_TIME - ( time - $session->get('time') );
    $remaining = 0 if $remaining < 0;
    return $remaining;
}
sub session_expired {
    my ( $request, $session ) = @_;
    return if time_remaining($session);
    $session->expire;
    my $response = $request->new_response;
    $response->redirect('/login');
    return $response->finalize;
}

The time_remaining() subroutine returns the number of left in your session.

The session_expired() subroutine will return false if you have time remaining in your session.

Then, change your templates/params.tt file to this:

<html>
  <head><title>Parameters</title></head>
  <body>
    <p>Hello [% username %]. You have [% time %] seconds left.</p>
[% IF have_params %]
    <p>Our list of params:</p>
    <table rules="all">
      <tr><th>Name</th><th>Value</th></tr>
  [% FOREACH param IN params %]
      <tr><td>[% param.name %]</td><td>[% param.value %]</td></tr>
  [% END %]
    </table>
[% ELSE %]
    <p><strong>No params supplied!</strong></p>
[% END %]
  </body>
</html>

The only change is immediately after the body tag where we display the session username and the time remaining.

Next, rewrite your builder, again, to match the following:

builder {
    enable 'Session';
    mount '/' => sub {
        my $env     = shift;
        my $request = Plack::Request->new($env);
        my $session = Plack::Session->new($env);
        if ( my $redirect = session_expired( $request, $session ) ) {
            return $redirect;
        }
        my @params = get_params_array($request);
        if ( $session->get('from_login') ) {
            push @params => {
                name  => 'username',
                value => $session->get('username'),
            };
            $session->remove('from_login');
        }
        my %template_vars = (
            params      => \@params,
            have_params => scalar( @params ),
            username    => $session->get('username'),
            time        => remaining_time($session),
        );
        my $content = get_content( 'templates/params.tt', \%template_vars, );
        return response( $request, $content );
    };
    mount '/login' => sub {
        my $env     = shift;
        my $request = Plack::Request->new($env);
        my $session = Plack::Session->new($env);
        my $content;
        if ( $request->param('username') && $request->param('password') ) {
            $session->set( 'username', $request->param('username') );
            $session->set( 'time', time );
            $session->set( 'from_login', 1 );
            my $response = $request->new_response;
            $response->redirect('/');
            return $response->finalize;
        }
        else {
            $content = get_content('templates/login.tt');
        }
        return response( $request, $content );
    };
};

When you first restart the app, you’re presented with the login screen. Let’s say you login with a username of Bob and a password of Dobbs. You’ll see a screen like this:

Hello Bob. You have 30 seconds left.
Our list of params:

Name      Value
username  Bob

You can refresh this screen as often as you like and as soon as you have zero seconds left, you’re redirected to the /login screen. Your “username” and the time left on your session are stored in the session itself. Let’s break down how this works.

my $session = Plack::Session->new($env);

HTTP/1.1 302 Found
Content-Length: 0
Date: Thu, 12 Apr 2012 08:58:04 GMT
Location: /
Server: HTTP::Server::PSGI
Set-Cookie: plack_session=9f7539872c9b15d1ac30b8557742f3; path=/

Cookie: plack_session=9f7539872c9b15d1ac30b8557742f3

When you have entered both a username and password, the following code is executed:

if ( $request->param('username') && $request->param('password') ) {
    $session->set( 'username', $request->param('username') );
    $session->set( 'time', time );
    $session->set( 'from_login', 1 );
    my $response = $request->new_response;
    $response->redirect('/');
    return $response->finalize;
}

This sets the username, time, and from_login values in our session. In our toy example, this session is held in memory.

When the browser is redirected to /, the following is the relevant bit of code related to the session:

if ( my $redirect = session_expired( $request, $session ) ) {
    return $redirect;
}
my @params = get_params_array($request);
if ( $session->get('from_login') ) {
    push @params => {
        name  => 'username',
        value => $session->get('username'),
    };
    $session->remove('from_login');
}

The session_expired() function will return a redirect to /login if the session is greater than SESSION_TIME seconds ago or if there is no username in the session.

The $session->get('from_login') checks to see if the from_login value was set in the session (you can’t rely on the Referer: value because the end-user can change that, too) and, if it was, the from_login value is cleared and the username is added to the list of params for rendering.

Try it out Create a simple character generator for role-playing games.

Now that you have some of the basics of Web application under your belt, we’re going to put it all together and create a character generator for a game. You will be able to choose your name, place of birth and profession. You will have statistics for strength, intelligence and health randomly generated, but they will be adjusted for you profession and birthplace. This example is longer than your author would like because there is a lot of data which should be stored in a configuration file or database, but we’ve not covered those yet.

This example will also require one .psgi file and two templates.

1. Type in the following program and save it as character.psgi.

   use strict;
    use warnings;
    use Plack::Builder;
    use Plack::Request;
    use Template::Tiny;
    use File::Slurp 'read_file';
    use HTML::Entities 'encode_entities';
    builder {
        mount '/' => sub {
            my $env     = shift;
            my $request = Plack::Request->new($env);
            my $template = 'templates/character_display.tt';
            my $content;
            if ( $request->param ) {
                my ( $character, $errors )
                  = generate_character($request);
                $template = 'templates/character.tt' if @$errors;
                $content = get_content(
                    $template,
                    {
                        character => $character,
                        errors    => $errors,
                    }
                );
            }
            else {
                $content = get_content(
                  $template,
                  { no_character_found => 1 }
                );
            }
            return response( $request, $content );
        };
        mount '/character' => sub {
            my $env     = shift;
            my $request = Plack::Request->new($env);
            my $content = get_content('templates/character.tt');
            return response( $request, $content );
        };
    };
    sub generate_character {
        my $request        = shift;
        my %adjustments_for = (
            profession => {
                programmer => {
                    strength     => −3,
                    intelligence => 8,
                    health       => −2,
                },
                pilot    => { intelligence => 3 },
                redshirt => { strength     => 5 }
            },
            birthplace => {
                earth => {
                    strength     => 2,
                    intelligence => 0,
                    health       => −2,
                },
                mars => { strength     => −5, health => 2 },
                vat  => { intelligence => 2,  health => −2 }
            },
        );
        my @errors;
        my %label_for = (
            profession => {
                pilot      => "Starship Pilot",
                programmer => "Programmer",
                redshirt   => "Doomed",
            },
            birthplace => {
                earth => "Earth",
                mars  => "Mars",
                vat   => "Vat 3-5LX",
            },
        );
        my %value_for = map { $_ => roll_dice() }
          qw/strength intelligence health/;
        foreach my $attribute (qw/name profession birthplace/) {
            if ( my $value = $request->param($attribute) ) {
                if (my $adj=$adjustments_for{$attribute}{$value} ) {
                    while (my ($stat, $adjustment) = each %$adj) {
                        $value_for{$stat} += $adjustment;
                    }
                }
                $value_for{$attribute} =
                  encode_entities(
                    $label_for{$attribute}{$value} || $value
                  );
            }
            else {
                push @errors => "\U$attribute is required";
            }
        }
        if ( 'redshirt' eq $request->param('profession') ) {
            $value_for{health} = 1;
        }
        return \%value_for, \@errors;
    }
    sub roll_dice {
        my $total = 0;
        for ( 1 .. 3 ) {
            $total += 1 + int(rand(10));
        }
        return $total;
    }
    sub response {
        my ( $request, $content ) = @_;
        my $response = $request->new_response(200);
        $response->content_type('text/html');
        $response->content($content);
        return $response->finalize;
    }
    sub get_content {
       my ( $file, $vars ) = @_;
       $vars ||= {};
       my $template_code = read_file($file);
       my $template      = Template::Tiny->new;
       my $output;
       $template->process( \$template_code, $vars, \$output );
       return $output;
    }

2. We need a form to let the user make choices about their character. Save the following as templates/character.tt.

   <html>
     <head><title>Character Generation</title></head>
     <body>
       <fieldset>
         <legend>Create your character</legend>
   [% FOREACH error IN errors %]
         <p style="color:red; font-weight:bold">[% error %]</p>
   [% END %]
         <form action="/" method="POST" name="awesome">
           <table>
             <tr><td>Name</td>
               <td>
                 <input type="text" name="name"
                   value="[% character.name %]" />
               </td>
             </tr>
             <tr>
               <td>Profession</td>
               <td>
                 <select name="profession">
                   <option value="programmer">Programmer</option>
                   <option value="pilot">Starship Pilot</option>
                   <option value="redshirt">Security Officer
                     </option>
                 </select>
               </td>
             </tr>
             <tr>
               <td>Birth place</td>
               <td>
                 Earth <input type="radio" name="birthplace"
                   value="earth" /> |
                 Mars <input type="radio" name="birthplace"
                   value="mars" /> |
                 Vat 3-5LX <input type="radio" name="birthplace"
                   value="vat" />
               </td>
             </tr>
           </table>
           <div align="center">
             <input type="submit" value="Submit" />
           </div>
         </form>
       </fieldset>
     </body>
   </html>

3. Next, we need a form to display the generated character. Save the following as templates/character_display.tt.

   <html>
     <head>
       <title>The Awesome "This does nothing!" Game</title>
     </head>
     <body>
       <fieldset>
   [% IF no_character_found %]
         <legend>Create your character</legend>
         <p>
           <a href="/character">Click here to create a character</a>
         </p>
   [% ELSE %]
         <legend>Character Stats</legend>
         <table style="border-spacing:5px;">
           <tr><td>Name</td>
               <td>[% character.name %]</td></tr>
           <tr><td>Profession</td>
               <td>[% character.profession %]</td></tr>
           <tr><td>Birth place</td>
               <td>[% character.birthplace %]</td></tr>
           <tr><td>Strength</td>
               <td>[% character.strength %]</td></tr>
           <tr><td>Intelligence</td>
               <td>[% character.intelligence %]</td></tr>
           <tr><td>Health</td>
               <td>[% character.health %]</td></tr>
         </table>
         <p>
           <a href="/character">
             Click here to generate another character.
           </a>
         </p>
   [% END %]
       </fieldset>
     </body>
   </html>

   Note

   character.psgi, templates/character.tt and templates/character_display.tt available for download at Wrox.com.

4. Run the program with plackup character.psgi. In your favorite Web browser, go to http://localhost:5000/. You should see a link reading Click here to create a character.

When you click on that link, you’re taken to a form with a field for entering the character name, a drop down for selecting the character profession, and three radio buttons for choosing Earth, Mars, or Vat 3-5LX as your birthplace. If you fill out the form completely and click submit, a character will be randomly generated for you and displayed. If you forget to fill out one of the options, you will be returned to the form and a list of errors presented (due to limitations in how Template::Tiny works, when errors occur, only your name will be filled in).

How it works

Each of the templates is very simple and just glancing at them should explain what they’re doing. However, the .psgi file is a little bit more complex.

The get_content() and response() subroutines were used and explained earlier in the chapter. The roll_dice() subroutine simulates the rolling of three ten-sided dice and summing them for a character stat. Thus, each stat of Strength, Intelligence and Health can have a base score of 3 to 30 (rolling three ones and rolling three tens, respectively).

The generate_character() code is the same procedural code you’ve been writing throughout the entire book. It has too much data hard-coded into it, but for illustration purposes, it’s fine. It’s worth reading to see how well-chosen variable names can make the code clear, so let’s take a moment and do that.

1: my %value_for = map { $_ => roll_dice() }
       qw/strength intelligence health/;
 2: foreach my $attribute (qw/name profession birthplace/) {
 3:     if ( my $value = $request->param($attribute) ) {
 4:         if (my $adj = $adjustments_for{$attribute}{$value}) {
 5:             while ( my ($stat, $adjustment) = each %$adj ) {
 6:                 $value_for{$stat} += $adjustment;
 7:             }
 8:         }
 9:         $value_for{$attribute} =
10:           encode_entities(
                $label_for{$attribute}{$value} || $value );
11:     }
12:     else {
13:         push @errors => "\U$attribute is required";
14:     }
15: }

Line 1 sets random, default values for strength, intelligence and health. Starting with line 2, we iterate over the values the user entered and that’s when things are interesting.

On line 3, if we don’t have a value for an attribute (actually, because we’re testing for truth, this means that the number 0 cannot be a character name), control jumps to line 13 where we push an error onto our errors array.

On line 4, we see if we have $adjustments_for{$attribute}{$value}. That’s very easy to read and when you substitute the values for the variables, if someone chose Mars for their birthplace, that line evaluates to $adjustments_for{birthplace}{mars}. That points to the following hash reference:

{ strength => −5, health => 2 }

We then iterate over the keys and values and adjust the character’s base strength and health accordingly.

Lines 9 and 10 assign the label for the attribute. This is the value we display on the resulting templates/character_display.tt page. The || $value is there because we don’t have default display values for the character name.

It’s the builder that we really want to focus on because this contains the Web application control flow logic we’re concerned with. We have two paths mounted, / and /character. The latter is used to generate the form and we’ll look at that first.

mount '/character' => sub {
    my $env     = shift;
    my $request = Plack::Request->new($env);
    my $content = get_content('templates/character.tt');
    return response( $request, $content );
};

As you can see, all we do here is get the contents of their form submit and display the templates/character.tt page and that displays the form the user will use to fill out their character information. When you work through the logic of the program, you’ll see that for /character, we never really have any parameters submitted here.

The / path is where the interesting bit is.

1:  mount '/' => sub {
 2:      my $env     = shift;
 3:      my $request = Plack::Request->new($env);
 4:
 5:      my $template = 'templates/character_display.tt';
 6:      my $content;
 7:      if ( $request->param ) {
 8:          my ( $character, $errors )
               = generate_character($request);
 9:          $template = 'templates/character.tt' if @$errors;
10:          $content = get_content(
11:              $template,
12:              {
13:                  character => $character,
14:                  errors    => $errors,
15:              }
16:          );
17:      }
18:      else {
19:          $content = get_content(
                $template,
                {no_character_found=>1}
             );
20:      }
21:      return response( $request, $content );
22:  };

The first time you visit http://localhost:5000/, the $template name will be set to templates/character_display.tt on line 5. However, line 7 will see that you have not submitted parameters and thus control will fall to line 19, where we get the content of the template and pass it a hashref with no_character_found having a true value. In the template, that will cause this path to be executed:

[% IF no_character_found %]
      <legend>Create your character</legend>
      <p>
        <a href="/character">Click here to create a character</a>
      </p>
[% ELSE %]

So you click the link to create your character, fill out the form and you’ll click submit. That will POST your data to /. At this point, the test in line 7 will see that we did have parameters submitted and we attempt to generate the character. If there are errors, such as no name found, the template will be set back to templates/character.tt and the list of errors is displayed. Figure 15.3, “Figure 15-3” shows an example of what the Web page might look like if you have not filled it in correctly.

Figure 15.3. Figure 15-3

If you did complete the form, the generated character information will be sent to templates/character_display.tt and you’ll see your new character it all its glory.

Sometimes you want to fetch the links on a Web page. We’ll use LWP::Simple from the libwww-perl distribution to get the HTML for a Web page and HTML::SimpleLinkExtor to extract the links.

You will need to download both of these modules from the CPAN:

$ cpan libwww-perl HTML::SimpleLinkExtor

So here’s a little script to get us started:

use strict;
use warnings;
use HTML::SimpleLinkExtor;
use LWP::Simple 'get';
my $url       = shift @ARGV or die "Hey, gimme a URL!";
my $html      = get($url) or die "Could not get '$url'";
my $extractor = HTML::SimpleLinkExtor->new;
$extractor->parse($html);
my @links = $extractor->links;
unless (@links) {
    print "No links founds for $url\n";
    exit;
}
for my $link (sort @links) {
    print "$link\n";
}

You can run this against, say, a popular search engine like this:

http://searchenginename/

It will print out a sort list of all links found on that page. The get() function exported from LWP::Simple accepts a URL and returns the contents. The HTML::SimpleLinkExtor is used for extracting the links. You can play with this for a few Web pages and you’ll be amazed at how many links they have. But after a while, you may get tired of the No links found error, particularly if you visit the Web page and you know that there are links there. So let’s update the program using LWP::UserAgent instead of LWP::Simple.

use strict;
use warnings;
use HTML::SimpleLinkExtor;
use LWP::UserAgent;
my $url = shift @ARGV or die "Hey, gimme a URL!";
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
my $response = $ua->get($url) or die "Could not get '$url'";
unless ( $response->is_success ) {
    die $response->status_line;
}
my $html = $response->decoded_content;
my $extractor = HTML::SimpleLinkExtor->new;
$extractor->parse($html);
my @links = $extractor->links;
unless (@links) {
    print "No links founds for $url\n";
    exit;
}
for my $link ( sort @links ) {
    print "$link\n";
}

Now try running this with perl get_links.pl whitehouse.gov (note the lack of http://). You should get an error similar to the following:

400 URL must be absolute at get_links.pl line 14.

Ah! That’s better. Now at least we have some idea of what our errors are.

Your author has a friend, whom we shall presume wishes to be nameless, who has a habit of responding in online forums in a very friendly, informative manner. One of the forums she participates in allows a subset of HTML to be used, including HTML comments. So she embeds HTML comments in her replies. In HTML, they look like this:

<!-- this is a comment -->

The comments can span multiple lines. Her HTML comments span multiple jurisdictions of vitriol spewed at the person she is responding to. So let’s write a small program that prints the HTML comments in a Web page. Sadly, I cannot point you to her comments as this is a family-friendly book, but you’ll enjoy the end result nonetheless.

use strict;
use warnings;
use HTML::SimpleLinkExtor;
use HTML::TokeParser::Simple;
my $url = shift @ARGV or die "Hey, gimme a URL!";
my $ua = LWP::UserAgent->new;
$ua->timeout(10);
my $response = $ua->get($url) or die "Could not get '$url'";
unless ( $response->is_success ) {
    die $response->status_line;
}
my $html = $response->decoded_content;
my $parser = HTML::TokeParser::Simple->new( \$html );
while ( my $token = $parser->get_token ) {
    print $token->as_is, "\n" if $token->is_comment;
}

This program uses HTML::TokeParser::Simple to parse the HTML returned by LWP::UserAgent. There are a wide variety of parsers available, some more suited to extracting information than others, but this is a pretty easy one to start with (disclaimer: your author wrote it).

The key portion of this code is here:

1:  my $parser = HTML::TokeParser::Simple->new( \$html );
2:  while ( my $token = $parser->get_token ) {
3:      print $token->as_is, "\n" if $token->is_comment;
4:  }

If you have the text of a Web page, you must pass it as a reference to the constructor. Then, you can keep calling $parser->get_token to get the next “bit” of the Web page. Tokens are things such as HTML tags, HTML comments, text, and so on. We walk through all of the tokens and only print the ones that are comments. Easy, eh?

One major Web comic has an ASCII pterodactyl embedded in their comments. Another site has <!--IE6sux--> 54 times. You can have a lot of fun finding unexpected comments on Web sites (remember to obey their terms of service).

OK, so we’ve written two simple examples so far. Boooooring. Let’s do something a little more involved. Let’s write some software to fill out a form on a Web site and see what happens when we submit it!

Er, except that’s hard to do in a book for a couple of reasons: websites often change their content or TOS and your author would not like to be sued down to his skivvies for encouraging people to do this. Fortunately, we have a workaround.

Our last “Try it out” section had a Web form that you can fill in and submit. Perfect! So go back and run plackup characters.psgi for this example and leave that running in another terminal window. That’s going to be the Web server you’ll run this example against. You’ll need to install WWW::Mechanize and HTML::TableExtract to make this work.

Type in the following example and save it as post_character.pl.

use strict;
use warnings;
use WWW::Mechanize;
use HTML::TableExtract;
my $url  = 'http://localhost:5000/';
my $mech = WWW::Mechanize->new;
$mech->get($url);
$mech->follow_link( text_regex => qr/click here/i );
$mech->submit_form(
    form_number => 1,
    fields      => {
        name       => 'Bob',
        profession => 'redshirt',
        birthplace => 'mars',
    },
);
my $extractor = HTML::TableExtract->new;
$extractor->parse($mech->content);
foreach my $table ( $extractor->tables ) {
    foreach my $row ( $table->rows ) {
        printf "%-20s - %s\n" => @$row;
    }
}

Assuming that you didn’t do something silly like change the HTML in the character.psgi example, you should get output similar to the following (obviously the numeric values will be different):

Name                 - Bob
Profession           - Doomed
Birth place          - Mars
Strength             - 24
Intelligence         - 22
Health               - 1

It looks like our poor red shirt is going to die. On the plus side, at least he’s smart enough to know it.

WWW::Mechanize has a lovely interface. The code looks remarkably similar to what you might do as a human.

my $mech = WWW::Mechanize->new;
$mech->get($url);
$mech->follow_link( text_regex => qr/click here/i );

As you will recall, when you go the main page it has a link telling you to Please click here to create a new character.

There is only one form on the page, so we submit our values to form number 1.

$mech->submit_form(
    form_number => 1,
    fields      => {
        name       => 'Bob',
        profession => 'redshirt',
        birthplace => 'mars',
    },
);

Obviously, you’d have to read the HTML of the page to know the names and appropriate values for a given form, but it’s pretty darned easy to do. Just make sure your field refer to the value="..." data and not the human visible names.

Then we use HTML::TableExtract to get the values from the table printed on the next page:

my $extractor = HTML::TableExtract->new;
$extractor->parse($mech->content);
foreach my $table ( $extractor->tables ) {
    foreach my $row ( $table->rows ) {
        printf "%-20s - %s\n" => @$row;
    }
}

To be fair, this was a rather simple example. If you need to do this with more complicated Web sites, you’ll need to read the documentation carefully.

Be aware that many Web developers put all of their form validation in Javascript and not on the back end. Thus, if you use these techniques, you may be able to submit data and generate errors that are hard to reproduce using a browser (sometimes even if you have Javascript disabled). Be very careful with them and don’t use them irresponsibly.

Try it out Using Google’s JSON API to get directions.

So far we’ve been writing a few simple clients that read data from HTML. This is often called scraping Web sites and it’s an unfortunate practice because HTML is not really designed to be machine readable in the sense of “extracting useful information”. However, many Web sites offer APIs for precisely that purpose. We’re going to use the Google Directions API to find driving directions between two points. We won’t over the API in detail, but Google offers excellent documentation at:

https://developers.google.com/maps/documentation/directions/

We’re going to use their JSON API because JSON is very easy to parse. Essentially, the JSON::Any class will allow us to convert Google Maps API into a hash reference that we can read directly. We’ll use this API to find the driving directions between the lovely Portland, Oregon, and the somewhat less lovely Boring, Oregon.

1. Type in the following program and save it as google_directions.pl.

   use strict;
   use warnings;
   use WWW::Mechanize;
   use HTML::Strip;
   use JSON::Any;
   use URI::Encode 'uri_encode';
   use utf8::all;
   my $origin      = uri_encode('Boring, OR');
   my $destination = uri_encode('Portland, OR');
   my $url="http://maps.googleapis.com/maps/api/directions/json";
   my $query="origin=$origin&destination=$destination&sensor=false";
   my $mech = WWW::Mechanize->new;
   $mech->get("$url?$query");
   my $object = JSON::Any->new->decode( $mech->content );
   unless ( 'OK' eq $object->{status} ) {
       die $object->{status};
   }
   my $route      = $object->{routes}[0];
   my $copyrights = $route->{copyrights};
   my $warnings   = $route->{warnings};
   my $legs       = $route->{legs}[0];         # only take the first
   my $distance   = $legs->{distance}{text};
   my $duration   = $legs->{duration}{text};
   print
   "$copyrights\nThe trip is $distance long and lasts $duration\n";
   print join "\n" => @$warnings;
   print "\n";
   my $strip = HTML::Strip->new;
   foreach my $step ( @{ $legs->{steps} } ) {
       my $distance     = $step->{distance}{text};
       my $duration     = $step->{duration}{text};
       my $instructions = $strip->parse($step->{html_instructions});
       $strip->eof;
       print "$instructions for $distance ($duration)\n";
   }

   Note

   google_directions.pl available for download at Wrox.com.

2. Run the program with perl google_directions.pl. You should see output similar to the following (formatted to fit the page):

   Map data ©2012 Google, Sanborn
   The trip is 23.3 mi long and lasts 37 mins
   Head east on OR-212 E/Clackamas-Boring Hwy No 174 toward
     Meadow Creek Ln for 0.6 mi (2 mins)
   Turn left to merge onto US-26 W toward Gresham/Portland
     for 13.6 mi (23 mins)
   Turn right onto the I-205 N ramp for 0.1 mi (1 min)
   Keep left at the fork and merge onto I-205 N for 1.7 mi
     (2 mins)
   Take exit 21B to merge onto I-84 W/U.S. 30 W toward Portland
     for 5.7 mi (6 mins)
   Take the I-5 S exit on the left toward
     City Center/Beaverton/Salem for 0.4 mi (1 min)
   Keep right at the fork, follow signs for City Center and merge
     onto SE Morrison Bridge for 0.7 mi (1 min)
   Continue onto SW Washington St for 0.2 mi (1 min)
   Turn right onto SW 6th Ave Destination will be on the right
     for 0.2 mi (1 min)

How it works

In a nutshell, we:

• Construct an appropriate URL

• GET the URL from Google

• Parse the JSON response

• Profit!

OK, that last bullet point should have read print.

First, we load a bunch of modules you’re mostly familiar with:

use WWW::Mechanize;
use HTML::Strip;
use JSON::Any;
use URI::Encode 'uri_encode';
use utf8::all;

The JSON::Any module is a front end to other JSON modules that you may have installed. You probably want to install the JSON module but it requires a C compiler. If you can’t install that, the JSON::PP (Pure Perl) module is a decent, but slow, substitute. The JSON::Any module tries to load whatever JSON back end it can find.

The HTML::Strip module is used to strip some HTML data from our results. The rest of the modules you should already be familiar with.

We then construct the URL:

my $origin      = uri_encode('Boring, OR');
my $destination = uri_encode('Portland, OR');
my $url="http://maps.googleapis.com/maps/api/directions/json";
my $query="origin=$origin&destination=$destination&sensor=false";

Naturally, we uri_encode() our $origin and $destination because we don’t want them breaking our URL if we use data that must be encoded.

And we fetch the JSON and convert it into a hash reference (called $object because that’s what JSON calls hashes):

my $mech = WWW::Mechanize->new;
$mech->get("$url?$query");
my $object = JSON::Any->new->decode( $mech->content );

At this point, you could use Data:Dumper and print the hash reference:

use Data::Dumper;
print Dumper($object);

But we want something a bit easier to read. By reading the Google Maps API documentation, we figure out how to extract the correct data and print out each part of our route from Boring, Oregon to the lovely Portland, Oregon.

We’ve used this example to show you how APIs work, but there is a Google::Directions module on the CPAN, along with many other Google:: modules. Google is awesome and using their APIs can help you solve problems that would otherwise be very difficult to solve. Thanks, Google!