NAME
CGI::PathRequest - get file info in a cgi environment
SYNOPSIS
use CGI::PathRequest;
my $rq = new CGI::PathRequest;
$rq || die('no request, no default');
DESCRIPTION
This is kind of my swiss army knife of dealing with files in a cgi environment. It's mainly geared for taking requests from a client and setting default information about that resource. The constructor is told the relative path to a file (or directory) and from that you can ask a lot of really useful things like, relative path, absoltue path, filename, filesize, absolute location, relative location, etc. Things you normally have to regex for, they are already done here.
new()
Constructor. Takes hash ref as argument. Each key is a parameter.
my $rq = CGI::PathRequest->new({
param_name => 'path',
default => '/',
DOCUMENT_ROOT => '/home/superduper/html',
SERVER_NAME => 'superduper.com',
rel_path => $url,
cgi => $cgi,
}); Optional Parameters
- param_name
-
if you are taking data from a form imput via POST or GET , by default we are looking for a cgi param named 'path' - this can be overridden
- rel_path
-
specify the relative path to the file or dir we want
- default
-
if POST or GET do not yield a path and that path exists on disk, then default to what rel_path? Defaults to / (which would be your DOCUMENT ROOT )
- DOCUMENT_ROOT
-
Will try to determine automatically from ENV DOCUMENT_ROOT unless provided. Croaks if not determinded.
- cgi
-
Pass it an already existing cgi object for re use.
- SERVER_NAME
-
The name of your server or domain.
abs_path()
Absolute path on disk. Watch it, all /../ and links are resolved!
rel_path()
abs_loc()
The directory upon which the requested resource sits, everything but the filename
rel_loc()
Like abs_loc() but relative to ENV DOCUMENT_ROOT
filename()
Returns the filename portion of the file
filename_pretty()
Returns the filename, but prettyfied. Turns 'how_are_you.pdf' to 'How Are You'.
filetype()
Returns 'd' if directory, 'f' if file.
url()
Returns how this file would be accessed via a browser.
www()
Returns domain name of current site.
ext()
Returns filename's extension.
is_root()
Returns true if the request is the same as ENV DOCUMENT_ROOT This sets rel_loc(), rel_path(), and filename() to return "/", and also sets filetype() to return "d".
EXTENDED METHODS
These are methods that populate on call, that is, the values are not fed before you ask for them. If you are creating many CGI::PathRequest objects in one run and you use these, they should slow your process.
elements()
Returns an array of all data elements that are presently defined
my @elements = $r->elements;get_excerpt()
Get first x characters from file content if get_content() is or can be defined returns undef on failure
$r->get_excerpt;get_content()
Get contents of resource if is_text() returns true, returns undef on failure or zero size
$r->get_content();filesize()
Returns filesize in bites
$r->filesize;filesize_pretty()
Returns filesize in k, with the letter k in the end returns 0k if filesize is 0
$r->filesize_pretty;ctime()
Returns ctime, unix time
$r->ctime;ctime_pretty()
Returns ctime formatted to yyyy/mm/dd hh:mm by default
$r->ctime_pretty;atime()
Returns atime, unix time
$r->atime;atime_pretty()
Returns atime formatted to yyyy/mm/dd hh:mm by default
$r->atime_pretty;mtime()
Returns mtime, unix time
$r->mtime;mtime_pretty()
Returns mtime formatted to yyyy/mm/dd hh:mm by default
$r->mtime_pretty;is_dir()
Returns true if it is a directory
is_empty_dir()
Returns true if it is an empty directory, slow, feeds ls, lsf, and lsd.
is_file()
returns true if it is a file
is_image()
Returns true if mime type is an image type
$r->is_image;is_binary()
Returns true if resource was binary, directories return true
$r->is_binary;is_text()
Returns true if resource is text ( according to -T )
$r->is_text;
mime_type()
Returns mime type returned by File::Type
$r->mime_type;
alt()
Returns same as filename_pretty(), for use with an image alt tag, etc
$r->alt;
DIRECTORY METHODS
ls()
returns array ref listing of dir returns undef if it is not a dir returns all files, all dirs sorted returns empty array ref [] if none found excludes . and ..
lsd()
returns array ref listing of subdirs returns undef if it is not a dir returns only dirs sorted returns empty array ref [] if none found excludes . and ..
lsf()
returns array ref listing of files returns undef if it is not a dir returns only files sorted returns empty array ref [] if none found excludes . and ..
ERROR METHODS
error()
record an error
$r->error('this went wrong');errors()
returns array of errors, just strings. returns undef if no errors
my @errors = $r->errors;examples of viewing for errors:
# using Data::Dumper
if ($r->errors){
print STDERR Dumper($r->errors);
}
# using Smart::Comments
my $err = $r->errors;
### $err
get_datahash()
Returns hash with data, abs_path, rel_path, etc etc
METHODS FOR USE WITH HTML::Template
ls_prepped(), lsd_prepped() and lsf_prepped()
Alike ls lsf and lsd, returns array ref with hashes representing directory listing excluding . and .. in hash form, suitable for html template. for example, if your template has
<TMPL_LOOP LS>
<TMPL_VAR FILENAME>
<TMPL_VAR REL_PATH>
</TMPL_LOOP>You would feed it as
$html_template_object->param( LS => $cms->ls_prepped ); Returns empty array ref on none present [], that way it wont error on nothing there when you assign it to the tmpl loop
The same for lsd_prepped() and lsf_prepped() The name of the TMPL_VAR will be the same as the name of the method, (LS, LSF, LSD).
The TMPL_VAR set are :
rel_path, rel_loc, abs_path, abs_loc, filename, is_file, is_dir, filetypeget_datahash_prepped()
returns hash with data suitable for HTML::Template, none of the data that are arrays, etc are included For example:
my $prepped = $r->get_datahash_prepped;
for (keys %{$prepped}){
$html_template_object->param($_,$prepped->{$_});
}Your template could say:
<TMPL_IF IS_DIR>
This is a directory.
</TMPL_IF> Your HTML::Template construction should include die_on_bad_params=>0 to make use of this.
PREREQUISITES
File::stat; File::Type; File::Slurp; Time::Format;
TODO
option not to resolve symlinks
get rid of default. if resource does not exist, just return undef.
AUTHOR
Leo Charre leo (at) leocharre (dot) com