P4CGI - Support for CGI's that interface p4. Written specifically for P4DB
&P4CGI::cgi()
Return CGI reference
Example:
my $file = P4CGI::cgi()->param("file") ;
print "File parameter value: $file\n" ;
&P4CGI::p4call(result,command)
Request data from p4. Calls p4 with command command and returns data in result.
This function is really three different functions depeding in the type of the result parameter.
This parameter can be of three different types:
Data from command can be read from filehandle. NOTE! File must be closed by caller.
Returns result from command into array (newlines stripped)
Returns result from command into scalar. (lines separated by newline)
Any other type of parameter will abort operation
Command to send to p4 command line client.
Example:
my $d ;
&P4CGI::p4call(\$d,"changes -m 1") ;
$d =~ /Change (\d+)/ or &bail("No contact with P4 server") ;
$lastChange=$1 ;
&P4CGI::p4readform(command,resulthash)
Reads output from a P4 command and assumes the data is a form (e.g. ``client -o'').
The form is stored in a hash and the function returns an array containing all field names in the order they appeared. The hash will contain the field names as key and field values as data.
Command to send to p4 command line client.
Reference to a hash to receive reults
Example:
my %fields ;
my @fields = &P4CGI::p4readforml("client -o",\%fields) ;
my $f ;
foreach $f (@fields) {
print "field $f: $fields{$f}\n" ;
}
&P4CGI::start_page(title[,legend])
Start a page. Print http header and first part of HTML.
Title of page
Short help text to be displayed at top of page
Example:
my $start = P4CGI::start_page("Title of page",
&P4CGI::dl_list("This","Goto this",
"That","Goto that")) ;
print $start ;
&P4CGI::end_page()
End a page. Print HTML trailer.
Example:
print P4CGI::end_page() ;
&P4CGI::bail(message)
Report an error. This routine will emit HTML code for an error message, print the error log and exit.
This rouine is intended to report internal errors in the code (much like
assert(3) in c).
Example:
unless(defined $must_be_defined) {
&P4CGI::bail("was not defined") ;
} ;
&P4CGI::signalError(message)
Report an operator error in a reasonable fashion. SignalError can be called
before or after start_page() but if it is called before
start_page() a ``default'' page header will appear. It is
recommended to call signalError() after
start_page() to make it more obvious to the operator what the
problem was.
Example:
unless(defined $must_be_defined) {
&P4CGI::signalError("was not defined") ;
} ;
&P4CGI::start_table(table_attribute_text)
Start a table with optional table attributes
This text will be inserted as attributes to table tag
Example:
print P4CGI::start_table("align=center border") ;
&P4CGI::end_table()
Return end of table string. (trivial function included mostly for symmetry)
&P4CGI::table_row(options,listOfValues)
Insert a row in table.
A list of key/value pairs (a hash will do just fine) containing options for the row.
The key must start with a ``-''.
Most key/value pairs are treated as attributes to the <TR>-tag. The following keys are recognized as special:
Type of cells. Default is <TD>-type.
anykey will be assumed to be a row option and will be inserted in the TR-tag. The value for the option is the key value, unless value is empty or undefined, in which case the option anykey is assumed to have no value.
Row data. Remaining values are assumed to be data for each cell. The data is typically the text in the cell but can also be:
An undefined value indicates that the next cell spans more than one column.
The hash contains two keys: ``-text'' for cell text and ``-type'' for cell type. All other key/value pairs are treated as attributes to the <TD> or <TH> tag.
Example:
print P4CGI::start_table("align=center") ;
### print header row
print P4CGI::table_row(-type => "th",
-valign => "top",
-align => "left",
"Heading 1","Heading 2",undef,"Heading 3") ;
### print data
my %h = (-text => "text in hash",
-bgcolor => "blue") ;
print P4CGI::table_row(-valign => "top",
-bgcolor => "white",
"Cell 1",
{-text => "Cell 2",
-bgcolor => "red"},
\%h,
"Cell 3-2") ;
print P4CGI::end_table() ;
&P4CGI::table_header(list of label/hint)
Create a table header row with a a description and an optional hint for each column.
A list of column labels optionally followed by a '/' and a hint.
Example:
print P4CGI::start_table("align=center") ;
### print header row
print P4CGI::table_header("File/click for story","Revision/click to view") ;
### print data
my %h = (-text => "text in hash",
-bgcolor => "blue") ;
print P4CGI::table_row(-valign => "top",
-bgcolor => "white",
"Cell 1",
{-text => "Cell 2",
-bgcolor => "red"},
\%h,
"Cell 3-2") ;
print P4CGI::end_table() ;
&P4CGI::ul_list(list)
Return a bulleted list.
Lits of data to print as bulleted list
Example:
print P4CGI::ul_list("This","is","a","bulleted","list") ;
&P4CGI::dl_list(list_of_pairs)
Returns a definition list.
List of data pairs to print as a definition list. A hash will do just fine, only you have no control over the order in the list.
Example:
print P4CGI::dl_list("This","Description of this",
"That","Description of that") ;
&P4CGI::fixSpecChar(str)
Convert all '>' to ``>'', '<' to ``<'' and '&' to ``&''.
String to convert
Example:
my $cvstr = &P4CGI::fixSpecChar("String containing <,> and &") ;
&P4CGI::rmTabs(str)
Returns str with all tabs converted to spaces
String to convert
&P4CGI::ahref(options,parameters,text)
Returns a <A HREF...>...</A> tag pair.
Optional list of option-value pairs. Valid options are:
Url for link. Default is current.
Anchor in url. Default is none.
Any non-valid option marks the end of the options
Optional list of parameters for link.
The last parameter is used as text for link.
Example:
print &P4CGI::ahref("Back to myself") ; # link to this. No parameters.
print &P4CGI::ahref("-url","www.perforce.com",
"To perforce") ; # link to perforce
print &P4CGI::ahref("-anchor","THERE",
"Go there") ; # link to anchor THERE
print &P4CGI::ahref("-url","changeList.cgi",
"FSPC=//.../doc/...",
"Changes for all documentation") ; # url with parameter
&P4CGI::image(image[,text])
Returns <IMG>-tag
Example:
&P4CGI::image("picture.gif","Picture Here") ;
&P4CGI::magic(text)
Returns text with some magic ``patterns'' substituted with links.
Currently the pattern ``change number'' (and some variants) is replaced with a link to the change browser.
Example:
my $t = "Integrated change 4711 to this codeline" ;
print &P4CGI::magic($t) ; # inserts a link to change 4711
&P4CGI::fixspaces(text)
Returns text with characters like space substituted with ``%<ASCII value>''.
Example:
my $t = "/File with spaces" ;
print &P4CGI::fixspaces($t) ; # prints: /File%20with%20spaces