The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DiaColloDB-WWW-0.02.005
River stage zero No dependents
++
/ DiaColloDB::WWW::CGI

NAME

DiaColloDB::WWW::CGI - diachronic collocation db, www wrappers: (f)cgi wrapper utility class

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::WWW::CGI;
 
 ##========================================================================
 ## constructors etc.
 
 $dbcgi = $that->new(%args);
 @keys  = $dbcgi->_param();
 $dbcgi = $dbcgi->_reset();
 $dbcgi = $dbcgi->_getenv();
 $dbcgi = $dbcgi->fromRequest($httpRequest,$csock);
 \%vars = $dbcgi->vars();
 
 ##========================================================================
 ## config loading (optional)
 
 $dbcgi = $dbcgi->load_config($filename);
 
 ##========================================================================
 ## Template Toolkit stuff
 
 $key   = $dbcgi->ttk_key($key);
 @paths = $dbcgi->ttk_include();
 $file  = $dbcgi->ttk_file();
 $t     = $dbcgi->ttk_template(\%templateConfigArgs);
 $data  = $dbcgi->ttk_process($srcFile, \%templateVars, \%templateConfigArgs, \%templateProcessArgs);
 
 ##========================================================================
 ## CGI stuff: generic
 
 @error    = $dbcgi->htmlerror($status,@message);
 @whatever = $dbcgi->cgi($method, @args);
 undef     = $dbcgi->cgi_main();
 undef     = $dbcgi->fcgi_main();
 
 ##========================================================================
 ## Template stuff: useful aliases
 
 $uri      = $dbcgi->uri();
 $scheme   = $dbcgi->uriScheme($uri?);
 $dir      = $dbcgi->uriDir($uri?);
 $userinfo = $dbcgi->uriUserInfo($uri?);
 $uristr   = $dbcgi->quri($base, \%form);
 $urisub   = $dbcgi->uuri($base, \%form);
 $sqstring = $dbcgi->sqstring($str);
 $str      = $dbcgi->sprintf_(...);
 $mtime    = $dbcgi->mtime($filename);
 $str      = $dbcgi->timestamp();
 $json_str = PACKAGE->to_json($data);
 $json_str = PACKAGE->from_json($data);
 \@daytime = PACKAGE->gettimeofday();
 $secs     = PACKAGE->tv_interval($t0,$t1);
 $secs     = PACKAGE->t_elapsed();
 $enc      = PACKAGE->encode_utf8($str);
 $enc      = PACKAGE->decode_utf8($str);

DESCRIPTION

DiaColloDB::WWW::CGI provides abstractions and utilities for instantiating Template Toolkit template files in a CGI-like environment. It can be used together with the shared scripts and templates in the share/htdocs/ directory of the DiaColloDB::WWW distribution to create a CGI-wrapper directory for use with an external web server such as apache (via dcdb-www-create.perl(1)), and is implicitly called by the standalone DiaColloDB::WWW::Server class (see dcdb-www-server.perl(1)).

Globals

Variable: @ISA

DiaColloDB::WWW::CGI inherits from DiaColloDB::Logger, and imports the CGI :standard and :cgi-lib aliases.

Constructors etc.

new
 $dbcgi = $that->new(%args);

%args, object structure:

 ##-- Basic Properties
 prog   => $prog,               ##-- handler basename for template resolution & error reporting; default=basename($0)
 cgipkg => $cgipkg,             ##-- back-end CGI package to use (default='CGI')
 ##
 ##-- CGI params
 defaults => \%defaults,        ##-- default parameter values (default={})
 vars     => \%vars,            ##-- current parameters (after $dbcgi->vars())
 charset  => $charset,          ##-- charset (default='utf-8')
 nodecode => \%varnames,        ##-- names of variables not to be decoded (default=none)
 ##
 ##-- CGI environment stuff : see getenv() method
 remote_addr => $remote_addr,
 remote_user => $remote_user,
 request_method => $request_method,
 request_uri => $request_uri,
 request_query => $request_query,
 http_referer => $http_referer,
 http_host    => $http_host,
 server_addr  => $server_addr,
 server_port  => $server_port,
 ##
 ##-- template toolkit stuff
 ttk_package => $ttk_package,           ##-- package label for template processing (default=ref($dbcgi)||$dbcgi)
 ttk_vars    => \%ttk_vars,             ##-- extra template processing variables (default=$dbcgi->vars())
 ttk_config  => \%ttk_config,           ##-- extra options for Template->new()
 ttk_process => \%ttk_process,          ##-- extra options for $template->process()
 ttk_dir     => $ttk_dir,               ##-- template toolkit directory (default=abs_path(dirname($0)))
 ttk_sharedir=> $ttk_sharedir,          ##-- fallback template directory (default=File::ShareDir::dist_dir("DiaColloDB-WWW")."/htdocs")
 ttk_key     => $ttk_key,               ##-- current template basename (default=basename($prog))
 ttk_rawkeys => \%ttk_rawkeys           ##-- pseudo-set of raw keys (default={profile=>1})
_param
 @keys = $dbcgi->_param();
 $val  = $dbcgi->_param($name);

Wraps CGI::param().

_reset
 $dbcgi = $dbcgi->_reset();

resets CGI environment

_getenv
 $dbcgi = $dbcgi->_getenv();

populate $dbcgi keys from CGI environment variables.

fromRequest
 $dbcgi = $dbcgi->fromRequest($httpRequest,$csock);

populates $dbcgi keys from an HTTP::Request object, implicitly calls $dbcgi->vars().

vars
 \%vars = $dbcgi->vars();
 \%vars = $dbcgi->vars(\%vars);

Get or set CGI variables, instantiating $dbcgi->{defaults} if present.

config loading (optional)

load_config
 $dbcgi = $dbcgi->load_config($filename);

loads %$dbcgi keys from JSON filename, clobbering any existing values.

Template Toolkit stuff

ttk_key
 $key = $dbcgi->ttk_key();
 $key = $dbcgi->ttk_key($key);

returns requested template key $key if specified and defined, otherwise returns default template key basename($dbcgi->{prog}) without any final extension.

ttk_include
 @paths = $dbcgi->ttk_include();
 $paths = $dbcgi->ttk_include();

returns ttk search path @$dbcgi->{qw(ttk_dir ttk_sharedir)}, in scalar context as a ":"-separated list.

ttk_file
 $file = $dbcgi->ttk_file();
 $file = $dbcgi->ttk_file($key);

Returns template filename for template key (basename) $key, which defaults to $dbcgi->ttk_key($key). Returns first matching file found in $dbcgi->ttk_include(), throwing an error if no matching file was found.

ttk_template
 $t = $dbcgi->ttk_template(\%templateConfigArgs);

returns a new Template object for processing. \$templateConfigArgs can be used to override the defaults in $dbcgi->{ttk_config}.

ttk_process
 $data  = $dbcgi->ttk_process($srcFile, \%templateVars, \%templateConfigArgs, \%templateProcessArgs);
 $dbcgi = $dbcgi->ttk_process($srcFile, \%templateVars, \%templateConfigArgs, \%templateProcessArgs, $outfh);
 $dbcgi = $dbcgi->ttk_process($srcFile, \%templateVars, \%templateConfigArgs, \%templateProcessArgs, \$outbuf);

Process a Template $srcFile. In the first form, template output data is collected in a local string buffer and returned; in the second and third forms, template output is sent to the designated filehandle rsp. buffer. By default, the following top-level template variables are bound:

 package => $dbcgi->{ttk_package},           ##-- caller package label
 version => $DiaColloDB::WWW::CGI::VERSION,  ##-- caller package version
 ENV     => \%ENV,                           ##-- caller environment
 %{$dbcgi->{ttk_vars}},                      ##-- calling object-local template variables
 cdb     => $dbcgi,                          ##-- calling object
 %templateVars,                              ##-- call-local variables, usually $dbcgi->vars()

CGI stuff: generic

htmlerror
 @error = $dbcgi->htmlerror($status,@message);

Returns a print()-able HTML error.

cgi
 @whatever = $dbcgi->cgi($method, @args);

Call a named $method from the designated CGI package, convenience wrapper for $dbcgi->{cgipkg}->can($method)->(@args).

cgi_main
 undef = $dbcgi->cgi_main();
 undef = $dbcgi->cgi_main($ttk_key);

Top-level runtime routine for key $dbcgi->ttk_key($ttk_key), with output to STDOUT.

fcgi_main
 undef = $dbcgi->fcgi_main();
 undef = $dbcgi-E<gt>fcgi_main($ttk_key);

Top-level runtime routine for key $dbcgi->ttk_key($ttk_key) using the CGI::Fast module.

Template stuff: useful aliases

The following methods are provided for use within templates via the template cdb variable provided by ttk_process.

Template stuff: useful aliases: CGI environment

Accessors only.

remoteAddr
remoteUser
requestMethod
requestUri
requestQuery
httpReferer
httpHost
serverAddr
serverPort

Template stuff: useful aliases: URIs

URI parsing & manipulation; optional argument $uri should be either a URI object, a valid URI string, or undef, in which case a URI is constructed from the httpHost, serverPort, and requestUri methods; see URI for details.

uri
 $uri = $dbcgi->uri($uri?);

Returns a URI object for $uri.

uriScheme
 $scheme = $dbcgi->uriScheme($uri?);
uriOpaque
 $opaque = $dbcgi-E<gt>uriOpaque($uri?);
uriPath
 $path = $dbcgi-E<gt>uriPath($uri?);
uriFragment
 $frag = $dbcgi-E<gt>uriFragment($uri?);
uriCanonical
 $canon = $dbcgi-E<gt>uriCanonical($uri?);
uriAbs
 $abs = $dbcgi-E<gt>uriAbs($uri?);
uriDir
 $dir = $dbcgi->uriDir($uri?);
uriAuthority
 $auth = $dbcgi->uriAuthority($uri?);
uriPathQuery
 $path_query = $dbcgi->uriPathQuery($uri?);
uriPathSegments
 \@segs = $dbcgi->uriPathSegments($uri?);
uriQuery
 $query = $dbcgi->uriQuery($uri?);
uriQueryForm
 \%form = $dbcgi->uriQueryForm($uri?);
uriQueryKeywords
 \@kws = $dbcgi->uriQueryKeywords($uri?);
userinfo
 $userinfo = $dbcgi->uriUserInfo($uri?);
uriHost
 $host = $dbcgi-E<gt>uriHost($uri?);
uriPort
 $port = $dbcgi-E<gt>uriPort($uri?);
quri
 $uristr = quri($base, \%form);

Returns a new query URI for base $base and query form \%form.

uuri
 $urisub = uuri($base, \%form);
 $uristr = $urisub->(\%form);

Returns a CODE-ref for generating query URIs.

Template stuff: useful aliases: miscellany

sqstring
 $sqstring = sqstring($str);

Single-quoted string.

sprintf_
 $str = sprintf_(...);

Wrapper for CORE::sprintf()|perlfunc/sprintf.

mtime
 $mtime = $dbcgi->mtime($filename);

Returns last file modification time for $filename, as returned by stat().

timestamp
 $str = $dbcgi->timestamp();

Gets current timestamp via localtime() and POSIX::strftime as a string of the form YYYY-MM-DD HH:MM:SS.

to_json
 $json_str = PACKAGE->to_json($data);
 $json_str = PACKAGE::to_json($data);
 $json_str = PACKAGE->to_json($data,\%opts);
 $json_str = PACKAGE::to_json($data,\%opts);

Wraps JSON::to_json().

from_json
 $json_str = PACKAGE->from_json($data);
 $json_str = PACKAGE::from_json($data);

Wraps JSON::from_json().

gettimeofday
 \@timeofday = PACKAGE->gettimeofday();
 \@timeofday = PACKAGE::gettimeofday();

Wraps Time::HiRes::gettimeofday.

tv_interval
 $secs = PACKAGE->tv_interval($t0,$t1);
 $secs = PACKAGE::tv_interval($t0,$t1);

Wraps Time::HiRes::tv_interval.

t_start
 $t_started = PACKAGE->t_start();

Start a global timer (for profiling) using Time::HiRes.

t_elapsed
 $secs = PACKAGE->t_elapsed();
 $secs = PACKAGE->t_elapsed($t1);
 $secs = PACKAGE->t_elapsed($t0,$t1);
 $secs = PACKAGE::t_elapsed();
 $secs = PACKAGE::t_elapsed($t1);
 $secs = PACKAGE::t_elapsed($t0,$t1);

Get (fractional) number of seconds elapsed between two Time::HiRes \@timeofday ARRAY-refs $t0 and $t1. $t0 defaults to the time of the last call to the t_start method, and $t1 defaults to the current time.

encode_utf8
 $enc = PACKAGE->encode_utf8($str, $force=0);
 $enc = PACKAGE::encode_utf8($str, $force=0)

encodes only if $force is true or if not already flagged as a byte-string.

decode_utf8
 $enc = PACKAGE->decode_utf8($str, $force=0);
 $enc = PACKAGE::decode_utf8($str, $force=0);

decodes only if $force is true or if not flagged as a byte-string.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

DiaColloDB(3pm), DiaColloDB::WWW::Server(3pm), CGI(3pm), CGI::Fast(3pm), perl(1), ...