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

- NAME
- SUBROUTINES
  - cgi
  - p4call
  - p4readform
  - start_page
  - end_page
  - bail
  - signalError
  - start_table
  - end_table
  - table_row
  - table_header
  - ul_list
  - dl_list
  - fixSpecChar
  - rmTabs
  - ahref
  - image
  - magic
  - fixspaces

# 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