DiaColloDB-WWW/lib/DiaColloDB/WWW/CGI.pod
##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl
##========================================================================
## NAME
=pod
=head1 NAME
DiaColloDB::WWW::CGI - diachronic collocation db, www wrappers: (f)cgi wrapper utility class
=cut
##========================================================================
## SYNOPSIS
=pod
=head1 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);
=cut
##========================================================================
## DESCRIPTION
=pod
=head1 DESCRIPTION
DiaColloDB::WWW::CGI
provides abstractions and utilities for instantiating
L<Template Toolkit|Template> template files in a CGI-like
environment. It can be used together with the
shared scripts and templates in the F<share/htdocs/> directory of the
L<DiaColloDB::WWW|DiaColloDB::WWW> distribution to create a
CGI-wrapper directory for use with an external web server such as apache
(via L<dcdb-www-create.perl(1)|dcdb-www-create.perl>),
and is implicitly called by the standalone L<DiaColloDB::WWW::Server|DiaColloDB::WWW::Server> class
(see L<dcdb-www-server.perl(1)|dcdb-www-server.perl>).
=cut
##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::CGI: globals
=pod
=head2 Globals
=over 4
=item Variable: @ISA
DiaColloDB::WWW::CGI
inherits from L<DiaColloDB::Logger|DiaColloDB::Logger>,
and imports the
L<CGI|CGI> C<:standard> and C<:cgi-lib> aliases.
=back
=cut
##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::CGI: constructors etc.
=pod
=head2 Constructors etc.
=over 4
=item 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})
=item _param
@keys = $dbcgi->_param();
$val = $dbcgi->_param($name);
Wraps L<CGI::param()|CGI>.
=item _reset
$dbcgi = $dbcgi->_reset();
resets CGI environment
=item _getenv
$dbcgi = $dbcgi->_getenv();
populate $dbcgi keys from CGI environment variables.
=item fromRequest
$dbcgi = $dbcgi->fromRequest($httpRequest,$csock);
populates $dbcgi keys from an HTTP::Request object,
implicitly calls L<$dbcgi-E<gt>vars()|/vars>.
=item vars
\%vars = $dbcgi->vars();
\%vars = $dbcgi->vars(\%vars);
Get or set CGI variables, instantiating $dbcgi-E<gt>{defaults} if present.
=back
=cut
##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::CGI: config loading (optional)
=pod
=head2 config loading (optional)
=over 4
=item load_config
$dbcgi = $dbcgi->load_config($filename);
loads %$dbcgi keys from JSON filename, clobbering any existing values.
=back
=cut
##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::CGI: Template Toolkit stuff
=pod
=head2 Template Toolkit stuff
=over 4
=item ttk_key
$key = $dbcgi->ttk_key();
$key = $dbcgi->ttk_key($key);
returns requested template key C<$key> if specified and defined,
otherwise returns default template key
C<basename($dbcgi-E<gt>{prog})> without any final extension.
=item ttk_include
@paths = $dbcgi->ttk_include();
$paths = $dbcgi->ttk_include();
returns ttk search path C<@$dbcgi-E<gt>{qw(ttk_dir ttk_sharedir)}>,
in scalar context as a ":"-separated list.
=item ttk_file
$file = $dbcgi->ttk_file();
$file = $dbcgi->ttk_file($key);
Returns template filename for template key (basename) C<$key>,
which defaults to L<C<$dbcgi-E<gt>ttk_key($key)>|/ttk_key>.
Returns first matching file found in
L<C<$dbcgi-E<gt>ttk_include()>|ttk_include>,
throwing an error if no matching file was found.
=item ttk_template
$t = $dbcgi->ttk_template(\%templateConfigArgs);
returns a new L<Template|Template> object for processing.
C<\$templateConfigArgs> can be used to override the defaults
in C<$dbcgi-E<gt>{ttk_config}>.
=item 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 L<Template|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()
=back
=cut
##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::CGI: CGI stuff: generic
=pod
=head2 CGI stuff: generic
=over 4
=item htmlerror
@error = $dbcgi->htmlerror($status,@message);
Returns a print()-able HTML error.
=item cgi
@whatever = $dbcgi->cgi($method, @args);
Call a named C<$method> from the designated CGI package,
convenience wrapper for C<$dbcgi-E<gt>{cgipkg}-E<gt>can($method)-E<gt>(@args)>.
=item cgi_main
undef = $dbcgi->cgi_main();
undef = $dbcgi->cgi_main($ttk_key);
Top-level runtime routine for key L<C<$dbcgi-E<gt>ttk_key($ttk_key)>|/ttk_key>,
with output to STDOUT.
=item fcgi_main
undef = $dbcgi->fcgi_main();
undef = $dbcgi-E<gt>fcgi_main($ttk_key);
Top-level runtime routine for key L<C<$dbcgi-E<gt>ttk_key($ttk_key)>|/ttk_key>
using the L<CGI::Fast|CGI::Fast> module.
=back
=cut
##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::CGI: Template stuff: useful aliases
=pod
=head2 Template stuff: useful aliases
The following methods are provided for use within templates via the
template C<cdb> variable provided by L<ttk_process|/ttk_process>.
=head3 Template stuff: useful aliases: CGI environment
Accessors only.
=over 4
=item remoteAddr
=item remoteUser
=item requestMethod
=item requestUri
=item requestQuery
=item httpReferer
=item httpHost
=item serverAddr
=item serverPort
=back
=head3 Template stuff: useful aliases: URIs
URI parsing & manipulation; optional argument C<$uri> should be either a
L<URI|URI> object, a valid URI string, or C<undef>, in which
case a URI is constructed from the
L<httpHost|/httpHost>,
L<serverPort|/serverPort>,
and L<requestUri|/requestUri> methods;
see L<URI> for details.
=over 4
=item uri
$uri = $dbcgi->uri($uri?);
Returns a URI object for C<$uri>.
=item uriScheme
$scheme = $dbcgi->uriScheme($uri?);
=item uriOpaque
$opaque = $dbcgi-E<gt>uriOpaque($uri?);
=item uriPath
$path = $dbcgi-E<gt>uriPath($uri?);
=item uriFragment
$frag = $dbcgi-E<gt>uriFragment($uri?);
=item uriCanonical
$canon = $dbcgi-E<gt>uriCanonical($uri?);
=item uriAbs
$abs = $dbcgi-E<gt>uriAbs($uri?);
=item uriDir
$dir = $dbcgi->uriDir($uri?);
=item uriAuthority
$auth = $dbcgi->uriAuthority($uri?);
=item uriPathQuery
$path_query = $dbcgi->uriPathQuery($uri?);
=item uriPathSegments
\@segs = $dbcgi->uriPathSegments($uri?);
=item uriQuery
$query = $dbcgi->uriQuery($uri?);
=item uriQueryForm
\%form = $dbcgi->uriQueryForm($uri?);
=item uriQueryKeywords
\@kws = $dbcgi->uriQueryKeywords($uri?);
=item userinfo
$userinfo = $dbcgi->uriUserInfo($uri?);
=item uriHost
$host = $dbcgi-E<gt>uriHost($uri?);
=item uriPort
$port = $dbcgi-E<gt>uriPort($uri?);
=item quri
$uristr = quri($base, \%form);
Returns a new query URI for base C<$base> and query form C<\%form>.
=item uuri
$urisub = uuri($base, \%form);
$uristr = $urisub->(\%form);
Returns a CODE-ref for generating query URIs.
=back
=head3 Template stuff: useful aliases: miscellany
=over 4
=item sqstring
$sqstring = sqstring($str);
Single-quoted string.
=item sprintf_
$str = sprintf_(...);
Wrapper for C<CORE::sprintf()|perlfunc/sprintf>.
=item mtime
$mtime = $dbcgi->mtime($filename);
Returns last file modification time for C<$filename>,
as returned by L<stat()|perlfunc/stat>.
=item timestamp
$str = $dbcgi->timestamp();
Gets current timestamp via L<localtime()|perlfunc/localtime>
and L<POSIX::strftime|POSIX/strftime> as a string of the form
C<YYYY-MM-DD HH:MM:SS>.
=item 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 L<JSON::to_json()|JSON/to_json>.
=item from_json
$json_str = PACKAGE->from_json($data);
$json_str = PACKAGE::from_json($data);
Wraps L<JSON::from_json()|JSON/from_json>.
=item gettimeofday
\@timeofday = PACKAGE->gettimeofday();
\@timeofday = PACKAGE::gettimeofday();
Wraps L<Time::HiRes::gettimeofday|Time::HiRes/gettimeofday>.
=item tv_interval
$secs = PACKAGE->tv_interval($t0,$t1);
$secs = PACKAGE::tv_interval($t0,$t1);
Wraps L<Time::HiRes::tv_interval|Time::HiRes/tv_interval>.
=item t_start
$t_started = PACKAGE->t_start();
Start a global timer (for profiling)
using L<Time::HiRes|Time::HiRes>.
=item 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
L<Time::HiRes|Time::HiRes> \@timeofday ARRAY-refs $t0 and $t1.
$t0 defaults to the time of the last call to
the L<t_start|/t_start> method,
and $t1 defaults to the current time.
=item 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.
=item 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.
=back
=cut
##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl
##======================================================================
## Footer
##======================================================================
=pod
=head1 AUTHOR
Bryan Jurish E<lt>moocow@cpan.orgE<gt>
=head1 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.
=head1 SEE ALSO
L<DiaColloDB(3pm)|DiaColloDB>,
L<DiaColloDB::WWW::Server(3pm)|DiaColloDB::WWW::Server>,
L<CGI(3pm)|CGI>,
L<CGI::Fast(3pm)|CGI::Fast>,
L<perl(1)|perl>,
...
=cut