NAME
CGI::PathRequest - get file info in a cgi environment
SYNOPSIS
use CGI::PathRequest;
my $r = new CGI::PathRequest;
if( $r->set('/home/me/public_html/documents') ){
$r->is_in_DOCUMENT_ROOT or warn 'not in document root, sure you wanna serve?';
if ( $f->is_dir ){
print $f->filename . " is a directory in " . $f->rel_loc ." it contains ". $f->ls_count. " entries." ;
};
DESCRIPTION
Conventions used in this document:
resource = the main file requested, be it a directory, file, etc.
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.
CGI::PathRequest inherits File::PathInfo and all its methods.
new()
Constructor. Takes hash ref as argument. Each key is a parameter. If requested does not exist, new returns undef.
my $rq = CGI::PathRequest->new; Optional Parameters
my $rq = CGI::PathRequest->new({
param_name => 'path',
DOCUMENT_ROOT => '/home/superduper/html',
SERVER_NAME => 'superduper.com',
rel_path => $url,
cgi => $cgi,
});- 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
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 ref of all data elements that aare/can be defined for this resource.
my $elements = $r->elements;get_content() and get_content_encoded()
Get contents of resource if is_text() returns true, returns undef on failure or zero size. The encoded variant escapes for html.
$r->get_content();get_excerpt() and get_excerpt_encoded()
Get first x characters from file content if get_content() is or can be defined returns undef on failure. The encoded variant escapes for html. The excerpt is ripped of any html.
$r->get_excerpt;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::MMagic. If the resource is a directory, returns undef.
$r->mime_type;alt()
Returns same as filename_pretty(), for use with an image alt tag, etc
$r->alt;DIRECTORY METHODS
All directory methods issue warnings and return undef if the resource is not a directory.
ls()
Returns array ref. listing of files if the resource is a directory returns undef if it is not a dir. returns all files and all dirs sorted in array ref. returns empty array ref [] if none found excludes . and ..
lsd()
returns sorted array ref listing of subdirs if resource is a directory. returns undef if it is not a directory. returns empty array ref [] if none found excludes . and .. by default.
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 ..
ls_count(), lsd_count(), and lsf_count()
returns count of elements for all files, for directories, and for files, if the resource is a directory. If the resource is not a directory, returns undef.
is_empty_dir()
returns boolean true or false. returns undef if resource is not a directory.
ERROR METHODS
See File::PathInfo for details.
get_datahash()
Returns hash with data, abs_path, rel_path, etc etc
METHODS FOR WITH HTML::Template
nav_prepped()
returns array ref for loop for HTML::Template This is a place people can click back to go to previous directories. which should be:
<!-- BEGIN NAV-->
<h4> <a href="?rel_path=/">[ home ]</a>
<TMPL_LOOP NAV>
<TMPL_IF LAST>
» <TMPL_VAR FILENAME>
<TMPL_ELSE>
» <a href="?rel_path=<TMPL_VAR REL_PATH>"><TMPL_VAR FILENAME></a>
</TMPL_IF>
</TMPL_LOOP>
</h4>
<!--END NAV-->The vars that are returned for each are:
FILENAME, ABS_LOC, REL_PATH, REL_LOC, FILETYPE, EXTA problem right now is that if you are requesting / (document root) then the returned value is []- which sets off warnings in 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 ref with data suitable for HTML::Template, none of the data that are arrays, etc are included For example:
$html_template_object->param( %{ $r->get_datahash_prepped } ); Your template could say:
<TMPL_IF IS_DIR>
<p>This is a directory, it has <TMPL_VAR LSD_COUNT> sub directories and
<TMPL_VAR LSF_COUNT> files.</p>
</TMPL_IF>
<TMPL_IF IS_TEXT>
<p>The file <TMPL_VAR FILENAME> in <TMPL_VAR REL_LOC> is a
<TMPL_VAR FILESIZE_PRETTY> text file, created on <TMPL_VAR CTIME_PRETTY>.</p>
<p><small> excerpt: <TMPL_VAR EXCERPT></small></p>
</TMPL_IF> Your HTML::Template object construction should include die_on_bad_params=>0 to make use of this.
PREREQUISITES
File::MMagic, Carp, File::PathInfo
SEE ALSO
TODO
option not to resolve symlinks
get rid of default. if resource does not exist, just return undef.
CHANGES
a file requested which is not in DOCUMENT ROOT (symlink) no longer croaks module
AUTHOR
Leo Charre leo (at) leocharre (dot) com