NAME

P4CGI - Support for CGI's that interface p4. Written specifically for P4DB


SUBROUTINES


cgi

&P4CGI::cgi()

Return CGI reference

Example:

    my $file = P4CGI::cgi()->param("file") ;
    print "File parameter value: $file\n" ;


p4call

&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.

result

This parameter can be of three different types:

Filehandle (typeglob)

Data from command can be read from filehandle. NOTE! File must be closed by caller.

Reference to array

Returns result from command into array (newlines stripped)

Reference to scalar

Returns result from command into scalar. (lines separated by newline)

Any other type of parameter will abort operation

command

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 ;    


p4readform

&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

Command to send to p4 command line client.

resulthash

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" ;
    }


start_page

&P4CGI::start_page(title[,legend])

Start a page. Print http header and first part of HTML.

title

Title of page

legend (Optional)

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 ;


end_page

&P4CGI::end_page()

End a page. Print HTML trailer.

Example:

 print P4CGI::end_page() ;


bail

&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).

message Message that will be displayed to user

Example:

 unless(defined $must_be_defined) { 
     &P4CGI::bail("was not defined") ; 
 } ;


signalError

&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.

message Message that will be displayed to user

Example:

 unless(defined $must_be_defined) { 
     &P4CGI::signalError("was not defined") ; 
 } ;


start_table

&P4CGI::start_table(table_attribute_text)

Start a table with optional table attributes

table_attribute_text

This text will be inserted as attributes to table tag

Example:

    print P4CGI::start_table("align=center border") ;


end_table

&P4CGI::end_table()

Return end of table string. (trivial function included mostly for symmetry)


table_row

&P4CGI::table_row(options,listOfValues)

Insert a row in table.

options

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

Type of cells. Default is <TD>-type.

-anykey

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.

listOfValues

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:

undef

An undefined value indicates that the next cell spans more than one column.

Reference to a hash

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() ;


table_header

&P4CGI::table_header(list of label/hint)

Create a table header row with a a description and an optional hint for each column.

list of label/hint

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() ;


ul_list

&P4CGI::ul_list(list)

Return a bulleted list.

list

Lits of data to print as bulleted list

Example:

 print P4CGI::ul_list("This","is","a","bulleted","list") ;


dl_list

&P4CGI::dl_list(list_of_pairs)

Returns a definition list.

list_of_pairs

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") ;


fixSpecChar

&P4CGI::fixSpecChar(str)

Convert all '>' to ``&gt;'', '<' to ``&lt;'' and '&' to ``&amp;''.

str

String to convert

Example:

    my $cvstr = &P4CGI::fixSpecChar("String containing <,> and &") ;


rmTabs

&P4CGI::rmTabs(str)

Returns str with all tabs converted to spaces

str

String to convert


ahref

&P4CGI::ahref(options,parameters,text)

Returns a <A HREF...>...</A> tag pair.

options

Optional list of option-value pairs. Valid options are:

-url

Url for link. Default is current.

-anchor

Anchor in url. Default is none.

Any non-valid option marks the end of the options

parameters

Optional list of parameters for link.

text

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


image

&P4CGI::image(image[,text])

Returns <IMG>-tag

Example:

    &P4CGI::image("picture.gif","Picture Here") ;


magic

&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


fixspaces

&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