files/P4CGI.html

P4CGI.html 

  1. <HTML>
  2. <HEAD>
  3. <TITLE>P4CGI - Support for CGI's that interface p4. Written specifically for P4DB</TITLE>
  4. <LINK REV="made" HREF="mailto:feedback@suse.de">
  5. </HEAD>
  6.  
  7. <BODY>
  8.  
  9. <!-- INDEX BEGIN -->
  10.  
  11. <UL>
  12.  
  13. 	<LI><A HREF="#NAME">NAME</A>
  14. 	<LI><A HREF="#SUBROUTINES">SUBROUTINES</A>
  15. 	<UL>
  16.  
  17. 		<LI><A HREF="#cgi">cgi</A>
  18. 		<LI><A HREF="#p4call">p4call</A>
  19. 		<LI><A HREF="#p4readform">p4readform</A>
  20. 		<LI><A HREF="#start_page">start_page</A>
  21. 		<LI><A HREF="#end_page">end_page</A>
  22. 		<LI><A HREF="#bail">bail</A>
  23. 		<LI><A HREF="#signalError">signalError</A>
  24. 		<LI><A HREF="#start_table">start_table</A>
  25. 		<LI><A HREF="#end_table">end_table</A>
  26. 		<LI><A HREF="#table_row">table_row</A>
  27. 		<LI><A HREF="#table_header">table_header</A>
  28. 		<LI><A HREF="#ul_list">ul_list</A>
  29. 		<LI><A HREF="#dl_list">dl_list</A>
  30. 		<LI><A HREF="#fixSpecChar">fixSpecChar</A>
  31. 		<LI><A HREF="#rmTabs">rmTabs</A>
  32. 		<LI><A HREF="#ahref">ahref</A>
  33. 		<LI><A HREF="#image">image</A>
  34. 		<LI><A HREF="#magic">magic</A>
  35. 		<LI><A HREF="#fixspaces">fixspaces</A>
  36. 	</UL>
  37.  
  38. </UL>
  39. <!-- INDEX END -->
  40.  
  41. <HR>
  42. <P>
  43. <H1><A NAME="NAME">NAME</A></H1>
  44. <P>
  45. P4CGI - Support for CGI's that interface p4. Written specifically for P4DB
  46.  
  47. <P>
  48. <HR>
  49. <H1><A NAME="SUBROUTINES">SUBROUTINES</A></H1>
  50. <P>
  51. <HR>
  52. <H2><A NAME="cgi">cgi</A></H2>
  53. <P>
  54. <CODE>&amp;P4CGI::cgi()</CODE>
  55.  
  56.  
  57.  
  58. <P>
  59. Return CGI reference 
  60.  
  61. <P>
  62. Example:
  63.  
  64. <P>
  65. <PRE>    my $file = P4CGI::cgi()-&gt;param(&quot;file&quot;) ;
  66.     print &quot;File parameter value: $file\n&quot; ;
  67. </PRE>
  68. <P>
  69. <HR>
  70. <H2><A NAME="p4call">p4call</A></H2>
  71. <P>
  72. <CODE>&amp;P4CGI::p4call(</CODE><STRONG>result</STRONG><CODE>,</CODE><STRONG>command</STRONG><CODE>)</CODE>
  73.  
  74.  
  75.  
  76. <P>
  77. Request data from p4. Calls p4 with command <STRONG>command</STRONG> and returns data in <STRONG>result</STRONG>.
  78.  
  79. <P>
  80. This function is really three different functions depeding in the type of
  81. the
  82. <STRONG>result</STRONG> parameter.
  83.  
  84. <DL>
  85. <DT><STRONG><A NAME="item_result">result</A></STRONG><DD>
  86. <P>
  87. This parameter can be of three different types:
  88.  
  89. <DL>
  90. <DT><STRONG><A NAME="item_Filehandle">Filehandle (typeglob)</A></STRONG><DD>
  91. <P>
  92. Data from command can be read from filehandle. NOTE! File must be closed by
  93. caller.
  94.  
  95. <DT><STRONG><A NAME="item_Reference">Reference to array</A></STRONG><DD>
  96. <P>
  97. Returns result from command into array (newlines stripped)
  98.  
  99. <DT><STRONG>Reference to scalar</STRONG><DD>
  100. <P>
  101. Returns result from command into scalar. (lines separated by newline)
  102.  
  103. </DL>
  104. <P>
  105. Any other type of parameter will abort operation
  106.  
  107. <DT><STRONG><A NAME="item_command">command</A></STRONG><DD>
  108. <P>
  109. Command to send to p4 command line client.
  110.  
  111. </DL>
  112. <P>
  113. Example:
  114.  
  115. <P>
  116. <PRE>    my $d ;
  117.     &amp;P4CGI::p4call(\$d,&quot;changes -m 1&quot;) ;
  118.     $d =~ /Change (\d+)/ or &amp;bail(&quot;No contact with P4 server&quot;) ;
  119.     $lastChange=$1 ;    
  120. </PRE>
  121. <P>
  122. <HR>
  123. <H2><A NAME="p4readform">p4readform</A></H2>
  124. <P>
  125. <CODE>&amp;P4CGI::p4readform(</CODE><STRONG>command</STRONG>,<STRONG>resulthash</STRONG><CODE>)</CODE>
  126.  
  127.  
  128.  
  129. <P>
  130. Reads output from a P4 command and assumes the data is a form (e.g.
  131. ``client -o'').
  132.  
  133. <P>
  134. The form is stored in a hash and the function returns an array containing
  135. all field names in the order they appeared. The hash will contain the field
  136. names as key and field values as data.
  137.  
  138. <DL>
  139. <DT><STRONG>command</STRONG><DD>
  140. <P>
  141. Command to send to p4 command line client.
  142.  
  143. <DT><STRONG><A NAME="item_resulthash">resulthash</A></STRONG><DD>
  144. <P>
  145. Reference to a hash to receive reults
  146.  
  147. </DL>
  148. <P>
  149. Example:
  150.  
  151. <P>
  152. <PRE>    my %fields ;
  153.     my @fields = &amp;P4CGI::p4readforml(&quot;client -o&quot;,\%fields) ;
  154.     my $f ;
  155.     foreach $f (@fields) {
  156.         print &quot;field $f: $fields{$f}\n&quot; ;
  157.     }
  158. </PRE>
  159. <P>
  160. <HR>
  161. <H2><A NAME="start_page">start_page</A></H2>
  162. <P>
  163. <CODE>&amp;P4CGI::start_page(</CODE><STRONG>title</STRONG>[<CODE>,</CODE><STRONG>legend</STRONG>]<CODE>)</CODE>
  164.  
  165.  
  166.  
  167. <P>
  168. Start a page. Print http header and first part of HTML.
  169.  
  170. <DL>
  171. <DT><STRONG><A NAME="item_title">title</A></STRONG><DD>
  172. <P>
  173. Title of page
  174.  
  175. <DT><STRONG><A NAME="item_legend">legend (Optional)</A></STRONG><DD>
  176. <P>
  177. Short help text to be displayed at top of page
  178.  
  179. </DL>
  180. <P>
  181. Example:
  182.  
  183. <P>
  184. <PRE> my $start = P4CGI::start_page(&quot;Title of page&quot;,
  185.                                &amp;P4CGI::dl_list(&quot;This&quot;,&quot;Goto this&quot;,
  186.                                                &quot;That&quot;,&quot;Goto that&quot;)) ;
  187.  print $start ;
  188. </PRE>
  189. <P>
  190. <HR>
  191. <H2><A NAME="end_page">end_page</A></H2>
  192. <P>
  193. <CODE>&amp;P4CGI::end_page()</CODE>
  194.  
  195.  
  196.  
  197. <P>
  198. End a page. Print HTML trailer.
  199.  
  200. <P>
  201. Example:
  202.  
  203. <P>
  204. <PRE> print P4CGI::end_page() ;
  205. </PRE>
  206. <P>
  207. <HR>
  208. <H2><A NAME="bail">bail</A></H2>
  209. <P>
  210. <CODE>&amp;P4CGI::bail(</CODE><STRONG>message</STRONG><CODE>)</CODE>
  211.  
  212.  
  213.  
  214. <P>
  215. Report an error. This routine will emit HTML code for an error message,
  216. print the error log and exit.
  217.  
  218. <P>
  219. This rouine is intended to report internal errors in the code (much like
  220. <CODE>assert(3)</CODE> in c). 
  221.  
  222. <DL>
  223. <DT><STRONG><A NAME="item_message">message
  224. Message that will be displayed to user</A></STRONG><DD>
  225. </DL>
  226. <P>
  227. Example:
  228.  
  229. <P>
  230. <PRE> unless(defined $must_be_defined) { 
  231.      &amp;P4CGI::bail(&quot;was not defined&quot;) ; 
  232.  } ;
  233. </PRE>
  234. <P>
  235. <HR>
  236. <H2><A NAME="signalError">signalError</A></H2>
  237. <P>
  238. <CODE>&amp;P4CGI::signalError(</CODE><STRONG>message</STRONG><CODE>)</CODE>
  239.  
  240.  
  241.  
  242. <P>
  243. Report an operator error in a reasonable fashion. SignalError can be called
  244. before or after <CODE>start_page()</CODE> but if it is called before
  245. <CODE>start_page()</CODE> a ``default'' page header will appear. It is
  246. recommended to call <CODE>signalError()</CODE> after
  247. <CODE>start_page()</CODE> to make it more obvious to the operator what the
  248. problem was.
  249.  
  250. <DL>
  251. <DT><STRONG>message
  252. Message that will be displayed to user</STRONG><DD>
  253. </DL>
  254. <P>
  255. Example:
  256.  
  257. <P>
  258. <PRE> unless(defined $must_be_defined) { 
  259.      &amp;P4CGI::signalError(&quot;was not defined&quot;) ; 
  260.  } ;
  261. </PRE>
  262. <P>
  263. <HR>
  264. <H2><A NAME="start_table">start_table</A></H2>
  265. <P>
  266. <CODE>&amp;P4CGI::start_table(</CODE><STRONG>table_attribute_text</STRONG><CODE>)</CODE>
  267.  
  268.  
  269.  
  270. <P>
  271. Start a table with optional table attributes
  272.  
  273. <DL>
  274. <DT><STRONG><A NAME="item_table_attribute_text">table_attribute_text</A></STRONG><DD>
  275. <P>
  276. This text will be inserted as attributes to table tag
  277.  
  278. </DL>
  279. <P>
  280. Example:
  281.  
  282. <P>
  283. <PRE>    print P4CGI::start_table(&quot;align=center border&quot;) ;
  284. </PRE>
  285. <P>
  286. <HR>
  287. <H2><A NAME="end_table">end_table</A></H2>
  288. <P>
  289. <CODE>&amp;P4CGI::end_table()</CODE>
  290.  
  291.  
  292.  
  293. <P>
  294. Return end of table string. (trivial function included mostly for symmetry)
  295.  
  296. <P>
  297. <HR>
  298. <H2><A NAME="table_row">table_row</A></H2>
  299. <P>
  300. <CODE>&amp;P4CGI::table_row(</CODE><STRONG>options</STRONG><CODE>,</CODE><STRONG>listOfValues</STRONG><CODE>)</CODE>
  301.  
  302.  
  303.  
  304. <P>
  305. Insert a row in table.
  306.  
  307. <DL>
  308. <DT><STRONG><A NAME="item_options">options</A></STRONG><DD>
  309. <P>
  310. A list of key/value pairs (a hash will do just fine) containing options for
  311. the row. 
  312.  
  313. <P>
  314. The key must start with a ``-''.
  315.  
  316. <P>
  317. Most key/value pairs are treated as attributes to the &lt;TR&gt;-tag. The
  318. following keys are recognized as special:
  319.  
  320. <DL>
  321. <DT><STRONG><A NAME="item__type">-type</A></STRONG><DD>
  322. <P>
  323. Type of cells. Default is &lt;TD&gt;-type. 
  324.  
  325. <DT><STRONG><A NAME="item__anykey">-anykey</A></STRONG><DD>
  326. <P>
  327. <EM>anykey</EM> will be assumed to be a row option and will be inserted in the TR-tag. The
  328. value for the option is the key value, unless value is empty or undefined,
  329. in which case the option anykey is assumed to have no value.
  330.  
  331. </DL>
  332. <DT><STRONG><A NAME="item_listOfValues">listOfValues</A></STRONG><DD>
  333. <P>
  334. Row data. Remaining values are assumed to be data for each cell. The data
  335. is typically the text in the cell but can also be:
  336.  
  337. <DL>
  338. <DT><STRONG><A NAME="item_undef">undef</A></STRONG><DD>
  339. <P>
  340. An undefined value indicates that the next cell spans more than one column. 
  341.  
  342. <DT><STRONG>Reference to a hash</STRONG><DD>
  343. <P>
  344. The hash contains two keys: ``-text'' for cell text and ``-type'' for cell
  345. type. All other key/value pairs are treated as attributes to the &lt;TD&gt;
  346. or &lt;TH&gt; tag.
  347.  
  348. </DL>
  349. </DL>
  350. <P>
  351. Example:
  352.  
  353. <P>
  354. <PRE> print P4CGI::start_table(&quot;align=center&quot;) ;
  355.                                    ### print header row
  356.  print P4CGI::table_row(-type   =&gt; &quot;th&quot;,
  357.                         -valign =&gt; &quot;top&quot;,
  358.                         -align  =&gt; &quot;left&quot;,
  359.                         &quot;Heading 1&quot;,&quot;Heading 2&quot;,undef,&quot;Heading 3&quot;) ;
  360.                                    ### print data
  361.  my %h = (-text    =&gt; &quot;text in hash&quot;, 
  362.           -bgcolor =&gt; &quot;blue&quot;) ;
  363.  print P4CGI::table_row(-valign  =&gt; &quot;top&quot;,
  364.                         -bgcolor =&gt; &quot;white&quot;,
  365.                         &quot;Cell 1&quot;,
  366.                         {-text    =&gt; &quot;Cell 2&quot;,
  367.                          -bgcolor =&gt; &quot;red&quot;},
  368.                         \%h,
  369.                         &quot;Cell 3-2&quot;) ;
  370.  print P4CGI::end_table() ;
  371. </PRE>
  372. <P>
  373. <HR>
  374. <H2><A NAME="table_header">table_header</A></H2>
  375. <P>
  376. <CODE>&amp;P4CGI::table_header(</CODE><STRONG>list of label/hint</STRONG><CODE>)</CODE>
  377.  
  378.  
  379.  
  380. <P>
  381. Create a table header row with a a description and an optional hint for
  382. each column. 
  383.  
  384. <DL>
  385. <DT><STRONG><A NAME="item_list">list of label/hint</A></STRONG><DD>
  386. <P>
  387. A list of column labels optionally followed by a '/' and a hint.
  388.  
  389. </DL>
  390. <P>
  391. Example:
  392.  
  393. <P>
  394. <PRE> print P4CGI::start_table(&quot;align=center&quot;) ;
  395.                                    ### print header row
  396.  print P4CGI::table_header(&quot;File/click for story&quot;,&quot;Revision/click to view&quot;) ;
  397.                                    ### print data
  398.  my %h = (-text    =&gt; &quot;text in hash&quot;, 
  399.           -bgcolor =&gt; &quot;blue&quot;) ;
  400.  print P4CGI::table_row(-valign  =&gt; &quot;top&quot;,
  401.                         -bgcolor =&gt; &quot;white&quot;,
  402.                         &quot;Cell 1&quot;,
  403.                         {-text    =&gt; &quot;Cell 2&quot;,
  404.                          -bgcolor =&gt; &quot;red&quot;},
  405.                         \%h,
  406.                         &quot;Cell 3-2&quot;) ;
  407.  print P4CGI::end_table() ;
  408. </PRE>
  409. <P>
  410. <HR>
  411. <H2><A NAME="ul_list">ul_list</A></H2>
  412. <P>
  413. <CODE>&amp;P4CGI::ul_list(</CODE><STRONG>list</STRONG><CODE>)</CODE>
  414.  
  415.  
  416.  
  417. <P>
  418. Return a bulleted list.
  419.  
  420. <DL>
  421. <DT><STRONG>list</STRONG><DD>
  422. <P>
  423. Lits of data to print as bulleted list
  424.  
  425. </DL>
  426. <P>
  427. Example:
  428.  
  429. <P>
  430. <PRE> print P4CGI::ul_list(&quot;This&quot;,&quot;is&quot;,&quot;a&quot;,&quot;bulleted&quot;,&quot;list&quot;) ;
  431. </PRE>
  432. <P>
  433. <HR>
  434. <H2><A NAME="dl_list">dl_list</A></H2>
  435. <P>
  436. <CODE>&amp;P4CGI::dl_list(</CODE><STRONG>list_of_pairs</STRONG><CODE>)</CODE>
  437.  
  438.  
  439.  
  440. <P>
  441. Returns a definition list.
  442.  
  443. <DL>
  444. <DT><STRONG><A NAME="item_list_of_pairs">list_of_pairs</A></STRONG><DD>
  445. <P>
  446. List of data pairs to print as a definition list. A hash will do just fine,
  447. only you have no control over the order in the list. 
  448.  
  449. </DL>
  450. <P>
  451. Example:
  452.  
  453. <P>
  454. <PRE> print P4CGI::dl_list(&quot;This&quot;,&quot;Description of this&quot;,
  455.                       &quot;That&quot;,&quot;Description of that&quot;) ;
  456. </PRE>
  457. <P>
  458. <HR>
  459. <H2><A NAME="fixSpecChar">fixSpecChar</A></H2>
  460. <P>
  461. <CODE>&amp;P4CGI::fixSpecChar(</CODE><STRONG>str</STRONG><CODE>)</CODE>
  462.  
  463.  
  464.  
  465. <P>
  466. Convert all '&gt;' to ``<CODE>&amp;gt;</CODE>'', '&lt;' to ``<CODE>&amp;lt;</CODE>'' and '&amp;' to ``<CODE>&amp;amp;</CODE>''.
  467.  
  468. <DL>
  469. <DT><STRONG><A NAME="item_str">str</A></STRONG><DD>
  470. <P>
  471. String to convert
  472.  
  473. </DL>
  474. <P>
  475. Example:
  476.  
  477. <P>
  478. <PRE>    my $cvstr = &amp;P4CGI::fixSpecChar(&quot;String containing &lt;,&gt; and &amp;&quot;) ;
  479. </PRE>
  480. <P>
  481. <HR>
  482. <H2><A NAME="rmTabs">rmTabs</A></H2>
  483. <P>
  484. <CODE>&amp;P4CGI::rmTabs(</CODE><STRONG>str</STRONG><CODE>)</CODE>
  485.  
  486.  
  487.  
  488. <P>
  489. Returns <STRONG>str</STRONG> with all tabs converted to spaces
  490.  
  491. <DL>
  492. <DT><STRONG>str</STRONG><DD>
  493. <P>
  494. String to convert
  495.  
  496. </DL>
  497. <P>
  498. <HR>
  499. <H2><A NAME="ahref">ahref</A></H2>
  500. <P>
  501. <CODE>&amp;P4CGI::ahref(</CODE><STRONG>options</STRONG><CODE>,</CODE><STRONG>parameters</STRONG><CODE>,</CODE><STRONG>text</STRONG><CODE>)</CODE>
  502.  
  503.  
  504.  
  505. <P>
  506. Returns a &lt;A HREF...&gt;...&lt;/A&gt; tag pair.
  507.  
  508. <DL>
  509. <DT><STRONG>options</STRONG><DD>
  510. <P>
  511. Optional list of option-value pairs. Valid options are:
  512.  
  513. <DL>
  514. <DT><STRONG><A NAME="item__url">-url</A></STRONG><DD>
  515. <P>
  516. Url for link. Default is current.
  517.  
  518. <DT><STRONG><A NAME="item__anchor">-anchor</A></STRONG><DD>
  519. <P>
  520. Anchor in url. Default is none.
  521.  
  522. </DL>
  523. <P>
  524. Any non-valid option marks the end of the options
  525.  
  526. <DT><STRONG><A NAME="item_parameters">parameters</A></STRONG><DD>
  527. <P>
  528. Optional list of parameters for link.
  529.  
  530. <DT><STRONG><A NAME="item_text">text</A></STRONG><DD>
  531. <P>
  532. The last parameter is used as text for link. 
  533.  
  534. </DL>
  535. <P>
  536. Example:
  537.  
  538. <P>
  539. <PRE>    print &amp;P4CGI::ahref(&quot;Back to myself&quot;) ; # link to this. No parameters.
  540. </PRE>
  541. <P>
  542. <PRE>    print &amp;P4CGI::ahref(&quot;-url&quot;,&quot;www.perforce.com&quot;,
  543.                         &quot;To perforce&quot;) ; # link to perforce
  544. </PRE>
  545. <P>
  546. <PRE>    print &amp;P4CGI::ahref(&quot;-anchor&quot;,&quot;THERE&quot;,
  547.                         &quot;Go there&quot;) ; # link to anchor THERE
  548. </PRE>
  549. <P>
  550. <PRE>    print &amp;P4CGI::ahref(&quot;-url&quot;,&quot;changeList.cgi&quot;,
  551.                         &quot;FSPC=//.../doc/...&quot;,
  552.                         &quot;Changes for all documentation&quot;) ; # url with parameter
  553. </PRE>
  554. <P>
  555. <HR>
  556. <H2><A NAME="image">image</A></H2>
  557. <P>
  558. <CODE>&amp;P4CGI::image(</CODE><STRONG>image</STRONG>[<CODE>,</CODE><STRONG>text</STRONG>]<CODE>)</CODE>
  559.  
  560.  
  561.  
  562. <P>
  563. Returns &lt;IMG&gt;-tag
  564.  
  565. <P>
  566. Example:
  567.  
  568. <P>
  569. <PRE>    &amp;P4CGI::image(&quot;picture.gif&quot;,&quot;Picture Here&quot;) ;
  570. </PRE>
  571. <P>
  572. <HR>
  573. <H2><A NAME="magic">magic</A></H2>
  574. <P>
  575. <CODE>&amp;P4CGI::magic(</CODE><STRONG>text</STRONG><CODE>)</CODE>
  576.  
  577.  
  578.  
  579. <P>
  580. Returns <STRONG>text</STRONG> with some magic ``patterns'' substituted with links.
  581.  
  582. <P>
  583. Currently the pattern ``change <EM>number</EM>'' (and some variants) is replaced with a link to the change browser.
  584.  
  585. <P>
  586. Example:
  587.  
  588. <P>
  589. <PRE>    my $t = &quot;Integrated change 4711 to this codeline&quot; ;
  590. </PRE>
  591. <P>
  592. <PRE>    print &amp;P4CGI::magic($t) ; # inserts a link to change 4711
  593. </PRE>
  594. <P>
  595. <HR>
  596. <H2><A NAME="fixspaces">fixspaces</A></H2>
  597. <P>
  598. <CODE>&amp;P4CGI::fixspaces(</CODE><STRONG>text</STRONG><CODE>)</CODE>
  599.  
  600.  
  601.  
  602. <P>
  603. Returns <STRONG>text</STRONG> with characters like space substituted with ``%&lt;ASCII value&gt;''.
  604.  
  605. <P>
  606. Example:
  607.  
  608. <P>
  609. <PRE>    my $t = &quot;/File with spaces&quot; ;
  610. </PRE>
  611. <P>
  612. <PRE>    print &amp;P4CGI::fixspaces($t) ; # prints: /File%20with%20spaces
  613. </PRE>
  614. </BODY>
  615.  
  616. </HTML>
# Change User Description Committed
#1 1985 Sean Nolan my initial branch 23 years ago
//guest/perforce_software/utils/p4db/P4DB_2.01/P4CGI.html
#1 1884 rmg Update to the current (2.01) P4DB. 23 years ago