##========================================================================
## 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
