/ 
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), ...