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
is_html()
Returns boolean, accepts no argument. File is text and has htm type ext.
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