.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 "Mojolicious::Plugin::CGI 3pm"
.TH Mojolicious::Plugin::CGI 3pm "2018-12-22" "perl v5.28.1" "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"
Mojolicious::Plugin::CGI \- Run CGI script from Mojolicious
.SH "VERSION"
.IX Header "VERSION"
0.40
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin enables Mojolicious to run Perl \s-1CGI\s0 scripts. It does so by forking
a new process with a modified environment and reads the \s-1STDOUT\s0 in a non-blocking
manner.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Standard usage"
.IX Subsection "Standard usage"
.Vb 2
\&  use Mojolicious::Lite;
\&  plugin CGI => [ "/cgi\-bin/script" => "/path/to/cgi/script.pl" ];
.Ve
.PP
Using the code above is enough to run \f(CW\*(C`script.pl\*(C'\fR when accessing
<http://localhost:3000/cgi\-bin/script>.
.SS "Complex usage"
.IX Subsection "Complex usage"
.Vb 4
\&  plugin CGI => {
\&    # Specify the script and mount point
\&    script => "/path/to/cgi/script.pl",
\&    route  => "/some/route",
\&
\&    # %ENV variables visible from inside the CGI script
\&    env => {}, # default is \e%ENV
\&
\&    # Path to where STDERR from cgi script goes
\&    errlog => "/path/to/file.log",
\&
\&    # The "before" hook is called before script start
\&    # It receives a Mojolicious::Controller which can be modified
\&    before => sub {
\&      my $c = shift;
\&      $c\->req\->url\->query\->param(a => 123);
\&    },
\&  };
.Ve
.PP
The above contains all the options you can pass on to the plugin.
.SS "Helper"
.IX Subsection "Helper"
.Vb 1
\&  plugin "CGI";
\&
\&  # GET /cgi\-bin/some\-script.cgi/path/info?x=123
\&  get "/cgi\-bin/#script_name/*path_info" => {path_info => \*(Aq\*(Aq}, sub {
\&    my $c    = shift;
\&    my $name = $c\->stash("script_name");
\&    $c\->cgi\->run(script => File::Spec\->rel2abs("/path/to/cgi/$name"));
\&  };
.Ve
.PP
The helper can take most of the arguments that \*(L"register\*(R" takes, with the
exception of \f(CW\*(C`support_semicolon_in_query_string\*(C'\fR.
.PP
It is critical that \*(L"script_name\*(R" and \*(L"path_info\*(R" is present in
stash. Whether the values are extracted directly
from the path or set manually does not matter.
.PP
Note that the helper is registered in all of the examples.
.SS "Running code refs"
.IX Subsection "Running code refs"
.Vb 7
\&  plugin CGI => {
\&    route => "/some/path",
\&    run   => sub {
\&      my $cgi = CGI\->new;
\&      # ...
\&    }
\&  };
.Ve
.PP
Instead of calling a script, you can run a code block when accessing the route.
This is (pretty much) safe, even if the code block modifies global state,
since it runs in a separate fork/process.
.SS "Support for semicolon in query string"
.IX Subsection "Support for semicolon in query string"
.Vb 4
\&  plugin CGI => {
\&    support_semicolon_in_query_string => 1,
\&    ...
\&  };
.Ve
.PP
The code above needs to be added before other plugins or handlers which use
\&\*(L"url\*(R" in Mojo::Message::Request. It will inject a \f(CW\*(C`before_dispatch\*(C'\fR
hook which saves the original \s-1QUERY_STRING,\s0 before it is split on
\&\*(L"&\*(R" in Mojo::Parameters.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "env"
.IX Subsection "env"
Holds a hash ref containing the environment variables that should be
used when starting the \s-1CGI\s0 script. Defaults to \f(CW%ENV\fR when this module
was loaded.
.PP
This plugin will create a set of environment variables depenendent on the
request passed in which is according to the \s-1CGI\s0 spec. In addition to \*(L"env\*(R",
these dynamic variables are set:
.PP
.Vb 3
\&  CONTENT_LENGTH, CONTENT_TYPE, HTTPS, PATH, PATH_INFO, QUERY_STRING,
\&  REMOTE_ADDR, REMOTE_HOST, REMOTE_PORT, REMOTE_USER, REQUEST_METHOD,
\&  SCRIPT_NAME, SERVER_PORT, SERVER_PROTOCOL.
.Ve
.PP
Additional static variables:
.PP
.Vb 5
\&  GATEWAY_INTERFACE = "CGI/1.1"
\&  SERVER_ADMIN = $ENV{USER}
\&  SCRIPT_FILENAME = Script name given as argument to register.
\&  SERVER_NAME = Sys::Hostname::hostname()
\&  SERVER_SOFTWARE = "Mojolicious::Plugin::CGI"
.Ve
.PP
Plus all headers are exposed. Examples:
.PP
.Vb 7
\&  .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.
\&  | Header          | Variable             |
\&  |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
\&  | Referer         | HTTP_REFERER         |
\&  | User\-Agent      | HTTP_USER_AGENT      |
\&  | X\-Forwarded\-For | HTTP_X_FORWARDED_FOR |
\&  \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.SS "register"
.IX Subsection "register"
.Vb 3
\&  $self\->register($app, [ $route => $script ]);
\&  $self\->register($app, %args);
\&  $self\->register($app, \e%args);
.Ve
.PP
\&\f(CW\*(C`route\*(C'\fR and path need to exist as keys in \f(CW%args\fR unless given as plain
arguments.
.PP
\&\f(CW$route\fR can be either a plain path or a route object.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2014, Jan Henning Thorsen
.PP
This program is free software, you can redistribute it and/or modify it under
the terms of the Artistic License version 2.0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jan Henning Thorsen \- \f(CW\*(C`jhthorsen@cpan.org\*(C'\fR