<HTML>
<HEAD>
<TITLE>P4CGI - Support for CGI's that interface p4. Written specifically for P4DB
</TITLE>
</HEAD>
<BODY>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#CONSTANTS">CONSTANTS</A>
<UL>
<LI><A HREF="#Url_s">Url's</A>
<LI><A HREF="#Data_file_update_scripts">Data file update scripts</A>
<LI><A HREF="#Constants_for_Depot_Tree_Browser">Constants for Depot Tree Browser</A>
</UL>
<LI><A HREF="#SUBROUTINES">SUBROUTINES</A>
<UL>
<LI><A HREF="#P4CGI_cgi_">P4CGI::cgi()</A>
<LI><A HREF="#P4CGI_p4call_I_result_I_comman">P4CGI::p4call(<EM>result</EM>,<EM>command</EM>)</A>
<LI><A HREF="#P4CGI_start_page_I_title_I_le">P4CGI::start_page(<EM>title</EM>[,<EM>legend</EM>])</A>
<LI><A HREF="#P4CGI_end_page_">P4CGI::end_page()</A>
<LI><A HREF="#P4CGI_bail_I_message_">P4CGI::bail(<EM>message</EM>)</A>
<LI><A HREF="#P4CGI_start_table_I_table_attri">P4CGI::start_table(<EM>table_attribute_text</EM>)</A>
<LI><A HREF="#P4CGI_end_table_">P4CGI::end_table()</A>
<LI><A HREF="#P4CGI_table_row_I_options_I_li">P4CGI::table_row(<EM>options</EM>,<EM>listOfValues</EM>)</A>
<LI><A HREF="#P4CGI_ul_list_I_list_">P4CGI::ul_list(<EM>list</EM>)</A>
<LI><A HREF="#P4CGI_dl_list_I_list_of_pairs_">P4CGI::dl_list(<EM>list_of_pairs</EM>)</A>
<LI><A HREF="#P4CGI_valid_lockfile_I_file_">P4CGI::valid_lockfile(<EM>file</EM>)</A>
<LI><A HREF="#P4CGI_create_lockfile_I_file_">P4CGI::create_lockfile(<EM>file</EM>)</A>
<LI><A HREF="#P4CGI_fixSpecChar_I_str_">P4CGI::fixSpecChar(<EM>str</EM>)</A>
<LI><A HREF="#P4CGI_ahref_I_options_I_parame">P4CGI::ahref(<EM>options</EM>,<EM>parameters</EM>,<EM>text</EM>)</A>
<LI><A HREF="#P4CGI_magic_I_text_">P4CGI::magic(<EM>text</EM>)</A>
</UL>
</UL>
<!-- INDEX END -->
<HR>
<P>
<HR>
<H1><A NAME="CONSTANTS">CONSTANTS
</A></H1>
The constants are defined as perl subroutines.
<P>
<P>
<HR>
<H2><A NAME="Url_s">Url's
</A></H2>
<DL>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::MAIN_URL()
</A></STRONG><DD>
Main entry point.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::DTB_URL()
</A></STRONG><DD>
URL to depot tree browser.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::CHB_URL()
</A></STRONG><DD>
URL to change browser.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::CHV_URL()
</A></STRONG><DD>
URL to change viewer.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::FV_URL()
</A></STRONG><DD>
URL to file viewer.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::SFV_URL()
</A></STRONG><DD>
URL to special file viewer.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::FLV_URL()
</A></STRONG><DD>
URL to file log viewer.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::FDV_URL()
</A></STRONG><DD>
URL to file diff viewer.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::LDV_URL()
</A></STRONG><DD>
URL to label diff viewer.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::SFF_URL()
</A></STRONG><DD>
URL to search for file.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::LAU_URL()
</A></STRONG><DD>
URL to list all users.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::LU_URL()
</A></STRONG><DD>
URL to view a user.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::LAB_URL()
</A></STRONG><DD>
URL to list all branches.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::LAL_URL()
</A></STRONG><DD>
URL to list all labels.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::LV_URL()
</A></STRONG><DD>
URL to view a labels.
<P>
</DL>
<P>
<HR>
<H2><A NAME="Data_file_update_scripts">Data file update scripts
</A></H2>
<DL>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::DTB_UPDATE()
</A></STRONG><DD>
Update data files for depot tree browser.
<P>
</DL>
<P>
<HR>
<H2><A NAME="Constants_for_Depot_Tree_Browser">Constants for Depot Tree Browser
</A></H2>
<DL>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::DTB_LOCKFILE()
</A></STRONG><DD>
Lock file name
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::DTB_FILESPLIT()
</A></STRONG><DD>
Number of data files to split data to.
<P>
<DT><STRONG><A NAME="item_P4CGI">P4CGI::DTB_DATAFILE()
</A></STRONG><DD>
Data file base name
<P>
</DL>
<P>
<HR>
<H1><A NAME="SUBROUTINES">SUBROUTINES
</A></H1>
<P>
<HR>
<H2><A NAME="P4CGI_cgi_">P4CGI::cgi()
</A></H2>
Return CGI reference
<P>
Example:
<P>
<PRE> my $file = P4CGI::cgi()->param("file") ;
print "Parameter \"file\" value: $file\n" ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_p4call_I_result_I_comman">P4CGI::p4call(<EM>result</EM>,<EM>command</EM>)
</A></H2>
Request data from p4. Calls p4 with command <EM>command</EM> and returns data in <EM>result</EM>.
<P>
This function is really three different functions depeding in the type of
the
<EM>result</EM> parameter.
<P>
<DL>
<DT><STRONG><A NAME="item_result">result
</A></STRONG><DD>
This parameter can be of three different types:
<P>
<DL>
<DT><STRONG><A NAME="item_Filehandle">Filehandle (typeglob)
</A></STRONG><DD>
Data from command can be read from filehandle. NOTE! File must be closed by
caller.
<P>
<DT><STRONG><A NAME="item_Reference">Reference to array
</A></STRONG><DD>
Returns result from command in array (newlines stripped)
<P>
<DT><STRONG>Reference to scalar
</A></STRONG><DD>
Returns result from command in scalar. (lines separated by newline)
<P>
</DL>
Any other type of parameter will abort operation
<P>
<DT><STRONG><A NAME="item_command">command
</A></STRONG><DD>
Command to send to p4 command line client.
<P>
</DL>
Example:
<P>
<PRE> my $d ;
&P4CGI::p4call(\$d,"changes -m 1") ;
$d =~ /Change (\d+)/ or &bail("No contact with P4 server") ;
$currentChangeLevel=$1 ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_start_page_I_title_I_le">P4CGI::start_page(<EM>title</EM>[,<EM>legend</EM>])
</A></H2>
Start a page. Print http header and first part of HTML.
<P>
<DL>
<DT><STRONG><A NAME="item_title">title
</A></STRONG><DD>
Title of page
<P>
<DT><STRONG><A NAME="item_legend">legend (Optional)
</A></STRONG><DD>
Short help text to be displayed at top of page
<P>
</DL>
Example:
<P>
<PRE> my $start = P4CGI::start_page("Title of page",
&P4CGI::dl_list("This","Goto this",
"That","Goto that")) ;
print $start ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_end_page_">P4CGI::end_page()
</A></H2>
End a page. Print HTML trailer.
<P>
Example:
<P>
<PRE> print P4CGI::end_page() ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_bail_I_message_">P4CGI::bail(<EM>message</EM>)
</A></H2>
Report an error. This routine will emit HTML code for an error message and
exit.
<P>
<DL>
<DT><STRONG><A NAME="item_message">message
Message that will be displayed to user
</A></STRONG><DD>
</DL>
Example:
<P>
<PRE> unless(defined $must_be_defined) {
&P4CGI::bail("was not defined") ;
} ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_start_table_I_table_attri">P4CGI::start_table(<EM>table_attribute_text</EM>)
</A></H2>
Start a table with optional table attributes
<P>
<DL>
<DT><STRONG><A NAME="item_table_attribute_text">table_attribute_text
</A></STRONG><DD>
This text will be inserted as attributes to table tag
<P>
</DL>
Example:
<P>
<PRE> print P4CGI::start_table("align=center border") ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_end_table_">P4CGI::end_table()
</A></H2>
Return end of table string. (trivial function included mostly for symmetry)
<P>
<P>
<HR>
<H2><A NAME="P4CGI_table_row_I_options_I_li">P4CGI::table_row(<EM>options</EM>,<EM>listOfValues</EM>)
</A></H2>
Insert a row in table.
<P>
<DL>
<DT><STRONG><A NAME="item_options">options
</A></STRONG><DD>
A list of key/value pairs (a hash will do just fine) containing options for
the row.
<P>
The key must start with a ``-''.
<P>
Most key/value pairs are treated as attributes to the <TR>-tag. The
following keys are recognized as special:
<P>
<DL>
<DT><STRONG><A NAME="item__type">-type
</A></STRONG><DD>
Type of cells. Default is <TD>-type.
<P>
<DT><STRONG><A NAME="item__anykey">-anykey
</A></STRONG><DD>
<EM>anykey</EM> 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.
<P>
</DL>
<DT><STRONG><A NAME="item_listOfValues">listOfValues
</A></STRONG><DD>
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:
<P>
<DL>
<DT><STRONG><A NAME="item_undef">undef
</A></STRONG><DD>
An undefined value indicates that the next cell spans more than one column.
<P>
<DT><STRONG>Reference to a hash
</A></STRONG><DD>
The has 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.
<P>
</DL>
</DL>
Example:
<P>
<PRE> 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() ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_ul_list_I_list_">P4CGI::ul_list(<EM>list</EM>)
</A></H2>
Return a bulleted list.
<P>
<DL>
<DT><STRONG><A NAME="item_list">list
</A></STRONG><DD>
Lits of data to print as bulleted list
<P>
</DL>
Example:
<P>
<PRE> print P4CGI::ul_list("This","is","a","bulleted","list") ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_dl_list_I_list_of_pairs_">P4CGI::dl_list(<EM>list_of_pairs</EM>)
</A></H2>
Returns a definition list.
<P>
<DL>
<DT><STRONG><A NAME="item_list_of_pairs">list_of_pairs
</A></STRONG><DD>
List of data pairs to print as a definition list. A hash will do just fine,
only that You have no control of the order in the list.
<P>
</DL>
Example:
<P>
<PRE> print P4CGI::dl_list("This","Description of this",
"That","Description of that") ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_valid_lockfile_I_file_">P4CGI::valid_lockfile(<EM>file</EM>)
</A></H2>
Check if <EM>file</EM> is a valid lock file. Return true if <EM>file</EM> is a valid lock file.
<P>
<DL>
<DT><STRONG><A NAME="item_file">file
</A></STRONG><DD>
Name of lock file
<P>
</DL>
Example:
<P>
<PRE> if(P4CGI::valid_lockfile("/tmp/lockfile")) {
print "Locked\n" ;
}
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_create_lockfile_I_file_">P4CGI::create_lockfile(<EM>file</EM>)
</A></H2>
Create a valid lock file for this process. Returns true if success.
<P>
<DL>
<DT><STRONG>file
</A></STRONG><DD>
Name of lock file
<P>
</DL>
Example:
<P>
<PRE> P4CGI::create_lockfile("/tmp/lockfile") or die "can't create lockfile!" ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_fixSpecChar_I_str_">P4CGI::fixSpecChar(<EM>str</EM>)
</A></H2>
Convert all '>' to ``<CODE>&gt;</CODE>'', '<' to ``<CODE>&lt;</CODE>'' and '&' to ``<CODE>&amp;</CODE>''.
<P>
<DL>
<DT><STRONG><A NAME="item_str">str
</A></STRONG><DD>
String to convert
<P>
</DL>
Example:
<P>
<PRE> my $cvstr = &P4CGI::fixSpecChar("String containing <,> and &") ;
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_ahref_I_options_I_parame">P4CGI::ahref(<EM>options</EM>,<EM>parameters</EM>,<EM>text</EM>)
</A></H2>
Create a <A HREF...>...</A> tag pair.
<P>
<DL>
<DT><STRONG>options
</A></STRONG><DD>
Optional list of option-value pairs. Valid options are:
<P>
<DL>
<DT><STRONG><A NAME="item__url">-url
</A></STRONG><DD>
Url for link. Default is current.
<P>
<DT><STRONG><A NAME="item__anchor">-anchor
</A></STRONG><DD>
Anchor in url. Default is none.
<P>
</DL>
Any non-valid option marks the end of the options
<P>
<DT><STRONG><A NAME="item_parameters">parameters
</A></STRONG><DD>
Optional list of parameters for link.
<P>
<DT><STRONG><A NAME="item_text">text
</A></STRONG><DD>
The last parameter is used as text for link.
<P>
</DL>
Example:
<P>
<PRE> print &P4CGI::ahref("Back to myself") ; # link to this. No parameters.
</PRE>
<P>
<PRE> print &P4CGI::ahref("-url","www.perforce.com",
"To perforce") ; # link to perforce
</PRE>
<P>
<PRE> print &P4CGI::ahref("-anchor","THERE",
"Go there") ; # link to anchor THERE
</PRE>
<P>
<PRE> print &P4CGI::ahref("-url","chb.cgi",
"FSPC=//depot/.../doc/...",
"Changes for all documentation") ; # url with parameter
</PRE>
<P>
<P>
<HR>
<H2><A NAME="P4CGI_magic_I_text_">P4CGI::magic(<EM>text</EM>)
</A></H2>
Substitutes magic phrases in <EM>text</EM> with links.
<P>
Currently the pattern ``change <EM>number</EM>'' is replaced with a link to the change browser.
<P>
Example:
<P>
<PRE> my $t = "This change is the same as change 4711, but with a twist" ;
</PRE>
<P>
<PRE> print &P4CGI::magic($t) ; # inserts a link to change 4711
</PRE>
<P>
</DL>
</BODY>
</HTML>