Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Compile(3)	      User Contributed Perl Documentation      CGI::Compile(3)

NAME
       CGI::Compile - Compile .cgi scripts to a	code reference like
       ModPerl::Registry

SYNOPSIS
	 use CGI::Compile;
	 my $sub = CGI::Compile->compile("/path/to/script.cgi");

DESCRIPTION
       CGI::Compile is a utility to compile CGI	scripts	into a code reference
       that can	run many times on its own namespace, as	long as	the script is
       ready to	run on a persistent environment.

       NOTE: for best results, load CGI::Compile before	any modules used by
       your CGIs.

RUN ON PSGI
       Combined	with CGI::Emulate::PSGI, your CGI script can be	turned into a
       persistent PSGI application like:

	 use CGI::Emulate::PSGI;
	 use CGI::Compile;

	 my $cgi_script	= "/path/to/foo.cgi";
	 my $sub = CGI::Compile->compile($cgi_script);
	 my $app = CGI::Emulate::PSGI->handler($sub);

	 # $app	is a PSGI application

CAVEATS
       If your CGI script has a	subroutine that	references the lexical scope
       variable	outside	the subroutine,	you'll see warnings such as:

	 Variable "$q" is not available	at ...
	 Variable "$counter" will not stay shared at ...

       This is due to the way this module compiles the whole script into a big
       "sub". To solve this, you have to update	your code to pass around the
       lexical variables, or replace "my" with "our". See also
       <http://perl.apache.org/docs/1.0/guide/porting.html#The_First_Mystery>
       for more	details.

METHODS
   new
       Does not	need to	be called, you only need to call it if you want	to set
       your own	"namespace_root" for the generated packages into which the
       CGIs are	compiled into.

       Otherwise you can just call "compile" as	a class	method and the object
       will be instantiated with a "namespace_root" of "CGI::Compile::ROOT".

       You can also set	"return_exit_val", see "RETURN CODE" for details.

       Example:

	   my $compiler	= CGI::Compile->new(namespace_root => 'My::CGIs');
	   my $cgi	= $compiler->compile('/var/www/cgi-bin/my.cgi');

   compile
       Takes either a path to a	perl CGI script	or a source code and some
       other optional parameters and wraps it into a coderef for execution.

       Can be called as	either a class or instance method, see "new" above.

       Parameters:

       o   $cgi_script

	   Path	to perl	CGI script file	or a scalar reference that contains
	   the source code of CGI script, required.

       o   $package

	   Optional, package to	install	the script into, defaults to the path
	   parts of the	script joined with "_",	and all	special	characters
	   converted to	"_%2x",	prepended with "CGI::Compile::ROOT::".

	   E.g.:

	       /var/www/cgi-bin/foo.cgi

	   becomes:

	       CGI::Compile::ROOT::var_www_cgi_2dbin_foo_2ecgi

       Returns:

       o   $coderef

	   $cgi_script or $$code compiled to coderef.

SCRIPT ENVIRONMENT
   ARGUMENTS
       Things like the query string and	form data should generally be in the
       appropriate environment variables that things like CGI expect.

       You can also pass arguments to the generated coderef, they will be
       locally aliased to @_ and @ARGV.

   "BEGIN" and "END" blocks
       "BEGIN" blocks are called once when the script is compiled.  "END"
       blocks are called when the Perl interpreter is unloaded.

       This may	cause surprising effects. Suppose, for instance, a script that
       runs in a forking web server and	is loaded in the parent	process. "END"
       blocks will be called once for each worker process and another time for
       the parent process while	"BEGIN"	blocks are called only by the parent
       process.

   %SIG
       The %SIG	hash is	preserved meaning the script can change	signal
       handlers	at will. The next invocation gets a pristine %SIG again.

   "exit" and exceptions
       Calls to	"exit" are intercepted and converted into exceptions. When the
       script calls "exit 19" and exception is thrown and $@ contains a
       reference pointing to the array

	   ["EXIT\n", 19]

       Naturally, "$^S"	in perlvar (exceptions being caught) is	always "true"
       during script runtime.

       If you really want to exit the process call "CORE::exit"	or set
       $CGI::Compile::USE_REAL_EXIT to true before calling exit:

	   $CGI::Compile::USE_REAL_EXIT	= 1;
	   exit	19;

       Other exceptions	are propagated out of the generated coderef. The
       coderef's caller	is responsible to catch	them or	the process will exit.

   Return Code
       The generated coderef's exit value is either the	parameter that was
       passed to "exit"	or the value of	the last statement of the script. The
       return code is converted	into an	integer.

       On a 0 exit, the	coderef	will return 0.

       On an explicit non-zero exit, by	default	an exception will be thrown of
       the form:

	   exited nonzero: <n>

       where "n" is the	exit value.

       This only happens for an	actual call to "exit" in perfunc, not if the
       last statement value is non-zero, which will just be returned from the
       coderef.

       If you would prefer that	explicit non-zero exit values are returned,
       rather than thrown, pass:

	   return_exit_val => 1

       in your call to "new".

       Alternately, you	can change this	behavior globally by setting:

	   $CGI::Compile::RETURN_EXIT_VAL = 1;

   Current Working Directory
       If "CGI::Compile->compile" was passed a script file, the	script's
       directory becomes the current working directory during the runtime of
       the script.

       NOTE: to	be able	to switch back to the original directory, the compiled
       coderef must establish the current working directory. This operation
       may cause an additional flush operation on file handles.

   "STDIN" and "STDOUT"
       These file handles are not touched by "CGI::Compile".

   The "DATA" file handle
       If the script reads from	the "DATA" file	handle,	it reads the
       "__DATA__" section provided by the script just as a normal script would
       do. Note, however, that the file	handle is a memory handle. So, "fileno
       DATA" will return "-1".

   CGI.pm integration
       If the subroutine "CGI::initialize_globals" is defined at script
       runtime,	it is called first thing by the	compiled coderef.

AUTHOR
       Tatsuhiko Miyagawa <miyagawa@bulknews.net>

CONTRIBUTORS
       Rafael Kitover <rkitover@cpan.org>

       Hans Dieter Pearcey <hdp@cpan.org>

       kocoureasy <igor.bujna@post.cz>

       Torsten Foertsch	<torsten.foertsch@gmx.net>

COPYRIGHT & LICENSE
       Copyright (c) 2009 Tatsuhiko Miyagawa <miyagawa@bulknews.net>

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

SEE ALSO
       ModPerl::RegistryCooker CGI::Emulate::PSGI

perl v5.32.0			  2015-03-06		       CGI::Compile(3)

NAME | SYNOPSIS | DESCRIPTION | RUN ON PSGI | CAVEATS | METHODS | SCRIPT ENVIRONMENT | AUTHOR | CONTRIBUTORS | COPYRIGHT & LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Compile&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help