<HTML>
<HEAD>
<TITLE>P4CGI - Support for CGI's that interface p4. Written specifically for P4DB</TITLE>
<LINK REV="made" HREF="mailto:feedback@suse.de">
</HEAD>
<BODY>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#NAME">NAME</A>
<LI><A HREF="#SUBROUTINES">SUBROUTINES</A>
<UL>
<LI><A HREF="#cgi">cgi</A>
<LI><A HREF="#p4call">p4call</A>
<LI><A HREF="#p4readform">p4readform</A>
<LI><A HREF="#start_page">start_page</A>
<LI><A HREF="#end_page">end_page</A>
<LI><A HREF="#bail">bail</A>
<LI><A HREF="#signalError">signalError</A>
<LI><A HREF="#start_table">start_table</A>
<LI><A HREF="#end_table">end_table</A>
<LI><A HREF="#table_row">table_row</A>
<LI><A HREF="#table_header">table_header</A>
<LI><A HREF="#ul_list">ul_list</A>
<LI><A HREF="#dl_list">dl_list</A>
<LI><A HREF="#fixSpecChar">fixSpecChar</A>
<LI><A HREF="#rmTabs">rmTabs</A>
<LI><A HREF="#ahref">ahref</A>
<LI><A HREF="#image">image</A>
<LI><A HREF="#magic">magic</A>
<LI><A HREF="#fixspaces">fixspaces</A>
</UL>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="NAME">NAME</A></H1>
<P>
P4CGI - Support for CGI's that interface p4. Written specifically for P4DB
<P>
<HR>
<H1><A NAME="SUBROUTINES">SUBROUTINES</A></H1>
<P>
<HR>
<H2><A NAME="cgi">cgi</A></H2>
<P>
<CODE>&P4CGI::cgi()</CODE>
<P>
Return CGI reference
<P>
Example:
<P>
<PRE> my $file = P4CGI::cgi()->param("file") ;
print "File parameter value: $file\n" ;
</PRE>
<P>
<HR>
<H2><A NAME="p4call">p4call</A></H2>
<P>
<CODE>&P4CGI::p4call(</CODE><STRONG>result</STRONG><CODE>,</CODE><STRONG>command</STRONG><CODE>)</CODE>
<P>
Request data from p4. Calls p4 with command <STRONG>command</STRONG> and returns data in <STRONG>result</STRONG>.
<P>
This function is really three different functions depeding in the type of
the
<STRONG>result</STRONG> parameter.
<DL>
<DT><STRONG><A NAME="item_result">result</A></STRONG><DD>
<P>
This parameter can be of three different types:
<DL>
<DT><STRONG><A NAME="item_Filehandle">Filehandle (typeglob)</A></STRONG><DD>
<P>
Data from command can be read from filehandle. NOTE! File must be closed by
caller.
<DT><STRONG><A NAME="item_Reference">Reference to array</A></STRONG><DD>
<P>
Returns result from command into array (newlines stripped)
<DT><STRONG>Reference to scalar</STRONG><DD>
<P>
Returns result from command into scalar. (lines separated by newline)
</DL>
<P>
Any other type of parameter will abort operation
<DT><STRONG><A NAME="item_command">command</A></STRONG><DD>
<P>
Command to send to p4 command line client.
</DL>
<P>
Example:
<P>
<PRE> my $d ;
&P4CGI::p4call(\$d,"changes -m 1") ;
$d =~ /Change (\d+)/ or &bail("No contact with P4 server") ;
$lastChange=$1 ;
</PRE>
<P>
<HR>
<H2><A NAME="p4readform">p4readform</A></H2>
<P>
<CODE>&P4CGI::p4readform(</CODE><STRONG>command</STRONG>,<STRONG>resulthash</STRONG><CODE>)</CODE>
<P>
Reads output from a P4 command and assumes the data is a form (e.g.
``client -o'').
<P>
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.
<DL>
<DT><STRONG>command</STRONG><DD>
<P>
Command to send to p4 command line client.
<DT><STRONG><A NAME="item_resulthash">resulthash</A></STRONG><DD>
<P>
Reference to a hash to receive reults
</DL>
<P>
Example:
<P>
<PRE> my %fields ;
my @fields = &P4CGI::p4readforml("client -o",\%fields) ;
my $f ;
foreach $f (@fields) {
print "field $f: $fields{$f}\n" ;
}
</PRE>
<P>
<HR>
<H2><A NAME="start_page">start_page</A></H2>
<P>
<CODE>&P4CGI::start_page(</CODE><STRONG>title</STRONG>[<CODE>,</CODE><STRONG>legend</STRONG>]<CODE>)</CODE>
<P>
Start a page. Print http header and first part of HTML.
<DL>
<DT><STRONG><A NAME="item_title">title</A></STRONG><DD>
<P>
Title of page
<DT><STRONG><A NAME="item_legend">legend (Optional)</A></STRONG><DD>
<P>
Short help text to be displayed at top of page
</DL>
<P>
Example:
<P>
<PRE> my $start = P4CGI::start_page("Title of page",
&P4CGI::dl_list("This","Goto this",
"That","Goto that")) ;
print $start ;
</PRE>
<P>
<HR>
<H2><A NAME="end_page">end_page</A></H2>
<P>
<CODE>&P4CGI::end_page()</CODE>
<P>
End a page. Print HTML trailer.
<P>
Example:
<P>
<PRE> print P4CGI::end_page() ;
</PRE>
<P>
<HR>
<H2><A NAME="bail">bail</A></H2>
<P>
<CODE>&P4CGI::bail(</CODE><STRONG>message</STRONG><CODE>)</CODE>
<P>
Report an error. This routine will emit HTML code for an error message,
print the error log and exit.
<P>
This rouine is intended to report internal errors in the code (much like
<CODE>assert(3)</CODE> in c).
<DL>
<DT><STRONG><A NAME="item_message">message
Message that will be displayed to user</A></STRONG><DD>
</DL>
<P>
Example:
<P>
<PRE> unless(defined $must_be_defined) {
&P4CGI::bail("was not defined") ;
} ;
</PRE>
<P>
<HR>
<H2><A NAME="signalError">signalError</A></H2>
<P>
<CODE>&P4CGI::signalError(</CODE><STRONG>message</STRONG><CODE>)</CODE>
<P>
Report an operator error in a reasonable fashion. SignalError can be called
before or after <CODE>start_page()</CODE> but if it is called before
<CODE>start_page()</CODE> a ``default'' page header will appear. It is
recommended to call <CODE>signalError()</CODE> after
<CODE>start_page()</CODE> to make it more obvious to the operator what the
problem was.
<DL>
<DT><STRONG>message
Message that will be displayed to user</STRONG><DD>
</DL>
<P>
Example:
<P>
<PRE> unless(defined $must_be_defined) {
&P4CGI::signalError("was not defined") ;
} ;
</PRE>
<P>
<HR>
<H2><A NAME="start_table">start_table</A></H2>
<P>
<CODE>&P4CGI::start_table(</CODE><STRONG>table_attribute_text</STRONG><CODE>)</CODE>
<P>
Start a table with optional table attributes
<DL>
<DT><STRONG><A NAME="item_table_attribute_text">table_attribute_text</A></STRONG><DD>
<P>
This text will be inserted as attributes to table tag
</DL>
<P>
Example:
<P>
<PRE> print P4CGI::start_table("align=center border") ;
</PRE>
<P>
<HR>
<H2><A NAME="end_table">end_table</A></H2>
<P>
<CODE>&P4CGI::end_table()</CODE>
<P>
Return end of table string. (trivial function included mostly for symmetry)
<P>
<HR>
<H2><A NAME="table_row">table_row</A></H2>
<P>
<CODE>&P4CGI::table_row(</CODE><STRONG>options</STRONG><CODE>,</CODE><STRONG>listOfValues</STRONG><CODE>)</CODE>
<P>
Insert a row in table.
<DL>
<DT><STRONG><A NAME="item_options">options</A></STRONG><DD>
<P>
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:
<DL>
<DT><STRONG><A NAME="item__type">-type</A></STRONG><DD>
<P>
Type of cells. Default is <TD>-type.
<DT><STRONG><A NAME="item__anykey">-anykey</A></STRONG><DD>
<P>
<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.
</DL>
<DT><STRONG><A NAME="item_listOfValues">listOfValues</A></STRONG><DD>
<P>
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:
<DL>
<DT><STRONG><A NAME="item_undef">undef</A></STRONG><DD>
<P>
An undefined value indicates that the next cell spans more than one column.
<DT><STRONG>Reference to a hash</STRONG><DD>
<P>
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.
</DL>
</DL>
<P>
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>
<HR>
<H2><A NAME="table_header">table_header</A></H2>
<P>
<CODE>&P4CGI::table_header(</CODE><STRONG>list of label/hint</STRONG><CODE>)</CODE>
<P>
Create a table header row with a a description and an optional hint for
each column.
<DL>
<DT><STRONG><A NAME="item_list">list of label/hint</A></STRONG><DD>
<P>
A list of column labels optionally followed by a '/' and a hint.
</DL>
<P>
Example:
<P>
<PRE> 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() ;
</PRE>
<P>
<HR>
<H2><A NAME="ul_list">ul_list</A></H2>
<P>
<CODE>&P4CGI::ul_list(</CODE><STRONG>list</STRONG><CODE>)</CODE>
<P>
Return a bulleted list.
<DL>
<DT><STRONG>list</STRONG><DD>
<P>
Lits of data to print as bulleted list
</DL>
<P>
Example:
<P>
<PRE> print P4CGI::ul_list("This","is","a","bulleted","list") ;
</PRE>
<P>
<HR>
<H2><A NAME="dl_list">dl_list</A></H2>
<P>
<CODE>&P4CGI::dl_list(</CODE><STRONG>list_of_pairs</STRONG><CODE>)</CODE>
<P>
Returns a definition list.
<DL>
<DT><STRONG><A NAME="item_list_of_pairs">list_of_pairs</A></STRONG><DD>
<P>
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.
</DL>
<P>
Example:
<P>
<PRE> print P4CGI::dl_list("This","Description of this",
"That","Description of that") ;
</PRE>
<P>
<HR>
<H2><A NAME="fixSpecChar">fixSpecChar</A></H2>
<P>
<CODE>&P4CGI::fixSpecChar(</CODE><STRONG>str</STRONG><CODE>)</CODE>
<P>
Convert all '>' to ``<CODE>&gt;</CODE>'', '<' to ``<CODE>&lt;</CODE>'' and '&' to ``<CODE>&amp;</CODE>''.
<DL>
<DT><STRONG><A NAME="item_str">str</A></STRONG><DD>
<P>
String to convert
</DL>
<P>
Example:
<P>
<PRE> my $cvstr = &P4CGI::fixSpecChar("String containing <,> and &") ;
</PRE>
<P>
<HR>
<H2><A NAME="rmTabs">rmTabs</A></H2>
<P>
<CODE>&P4CGI::rmTabs(</CODE><STRONG>str</STRONG><CODE>)</CODE>
<P>
Returns <STRONG>str</STRONG> with all tabs converted to spaces
<DL>
<DT><STRONG>str</STRONG><DD>
<P>
String to convert
</DL>
<P>
<HR>
<H2><A NAME="ahref">ahref</A></H2>
<P>
<CODE>&P4CGI::ahref(</CODE><STRONG>options</STRONG><CODE>,</CODE><STRONG>parameters</STRONG><CODE>,</CODE><STRONG>text</STRONG><CODE>)</CODE>
<P>
Returns a <A HREF...>...</A> tag pair.
<DL>
<DT><STRONG>options</STRONG><DD>
<P>
Optional list of option-value pairs. Valid options are:
<DL>
<DT><STRONG><A NAME="item__url">-url</A></STRONG><DD>
<P>
Url for link. Default is current.
<DT><STRONG><A NAME="item__anchor">-anchor</A></STRONG><DD>
<P>
Anchor in url. Default is none.
</DL>
<P>
Any non-valid option marks the end of the options
<DT><STRONG><A NAME="item_parameters">parameters</A></STRONG><DD>
<P>
Optional list of parameters for link.
<DT><STRONG><A NAME="item_text">text</A></STRONG><DD>
<P>
The last parameter is used as text for link.
</DL>
<P>
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","changeList.cgi",
"FSPC=//.../doc/...",
"Changes for all documentation") ; # url with parameter
</PRE>
<P>
<HR>
<H2><A NAME="image">image</A></H2>
<P>
<CODE>&P4CGI::image(</CODE><STRONG>image</STRONG>[<CODE>,</CODE><STRONG>text</STRONG>]<CODE>)</CODE>
<P>
Returns <IMG>-tag
<P>
Example:
<P>
<PRE> &P4CGI::image("picture.gif","Picture Here") ;
</PRE>
<P>
<HR>
<H2><A NAME="magic">magic</A></H2>
<P>
<CODE>&P4CGI::magic(</CODE><STRONG>text</STRONG><CODE>)</CODE>
<P>
Returns <STRONG>text</STRONG> with some magic ``patterns'' substituted with links.
<P>
Currently the pattern ``change <EM>number</EM>'' (and some variants) is replaced with a link to the change browser.
<P>
Example:
<P>
<PRE> my $t = "Integrated change 4711 to this codeline" ;
</PRE>
<P>
<PRE> print &P4CGI::magic($t) ; # inserts a link to change 4711
</PRE>
<P>
<HR>
<H2><A NAME="fixspaces">fixspaces</A></H2>
<P>
<CODE>&P4CGI::fixspaces(</CODE><STRONG>text</STRONG><CODE>)</CODE>
<P>
Returns <STRONG>text</STRONG> with characters like space substituted with ``%<ASCII value>''.
<P>
Example:
<P>
<PRE> my $t = "/File with spaces" ;
</PRE>
<P>
<PRE> print &P4CGI::fixspaces($t) ; # prints: /File%20with%20spaces
</PRE>
</BODY>
</HTML>