Helix SwarmHelix Swarm
Loading...

P4.html

  • //
  • guest/
  • tony_smith/
  • perforce/
  • API/
  • Ruby/
  • main/
  • doc/
  • P4.html #21
  • View
  • Commits
  • Open Download .zip Download (36 KB) 
  1. <html>
  2. <head>
  3.   <title>P4/Ruby - P4 class</title>
  4.   <link rel="stylesheet" type="text/css" href="docstyle.css">
  5. </head>
  6. <body>
  7.   <p align="right">
  8.     <a href="index.html">Contents</a>
  9.   </p>
  10.  
  11.   <div class="classhdr">
  12.     <table border=0>
  13.       <tr>
  14. 	<td>
  15. 	  <span class="classtag">Class</span>
  16. 	  <span class="classname">P4</span>
  17. 	  <span class="classparent">&lt; Object</span>
  18. 	</td>
  19. 	<td id="righttext">
  20. 	  <span class="requiretag">require</span>
  21. 	  <span class="modulename">"P4"</span>
  22. 	</td>
  23.       </tr>
  24.     </table>
  25.   </div>
  26.  
  27.   <h3>Description</h3>
  28.  
  29.   Main interface to the Perforce client API. Each P4 object provides
  30.   you with a thread-safe API level interface to Perforce. The basic
  31.   model is to:
  32.  
  33.   <ol>
  34.     <li>
  35.     <a href="#new">Instantiate</a> your P4 object
  36.     </li>
  37.     <li>
  38.       Specify your Perforce client environment
  39.       <ul>
  40. 	<li><a href="#client-eq">client</a></li>
  41. 	<li><a href="#host-eq">host</a></li>
  42. 	<li><a href="#password-eq">password</a></li>
  43. 	<li><a href="#port-eq">port</a></li>
  44. 	<li><a href="#user-eq">user</a></li>
  45.       </ul>
  46.     </li>
  47.     <li>
  48.       Set any options to control output or error handling
  49.       <ul>
  50. 	<li><a href="#exception-level-eq">exception_level</a></li>
  51. 	<li><a href="#parse_forms">parse_forms</a></li>
  52. 	<li><a href="#tagged">tagged</a></li>
  53.       </ul>
  54.     </li>
  55.     <li><a href="#connect">Connect</a> to the Perforce Server</li>
  56.     <li><a href="#run">Run</a> your Perforce commands</li>
  57.     <li><a href="#disconnect">Disconnect</a> from the Perforce Server</li>
  58.   </ol>
  59.  
  60.   <div class="classmethods">
  61.     <a name="classmethods"></a>
  62.     <h3>Class Methods</h3>
  63.  
  64.     <div class="index">
  65.       <a href="#identify">P4.identify</a>
  66.       <a href="#new">P4.new</a>
  67.     </div>
  68.  
  69.     <a name="identify"></a>
  70.     <div class="method">
  71.       <div class="methodheader">
  72. 	<table>
  73. 	  <tr>
  74. 	    <td class="meth_name">identify</td>
  75. 	    <td class="proto"><i>P4</i>.identify -&gt; <i>aString</i></td>
  76. 	  </tr>
  77. 	</table>
  78.       </div>
  79.  
  80.       <br>
  81.  
  82.       Return the version of P4/Ruby you are using - for diagnostic purposes.
  83.  
  84.       <pre>
  85.     ruby -rP4 -e 'puts( P4.identify )'
  86.       </pre>
  87.     </div>
  88.  
  89.     <a name="new"></a>
  90.     <div class="method">
  91.       <div class="methodheader">
  92. 	<table>
  93. 	  <tr>
  94. 	    <td class="meth_name">new</td>
  95. 	    <td class="proto"><i>P4</i>.new -&gt; <i>aP4</i></td>
  96. 	  </tr>
  97. 	</table>
  98.       </div>
  99.  
  100.       Constructs a new P4 object. 
  101.  
  102.       <pre>
  103.     p4 = P4.new()
  104.       </pre>
  105.     </div>
  106.   </div>
  107.  
  108.   <div class="instancemethods">
  109.     <h3>Instance Methods</h3>
  110.  
  111.     <div class="index">
  112.       <table border="0">
  113. 	<tr>
  114. 	  <td>
  115. 	    <a href="#at_exception_level">at_exception_level</a>
  116. 	    <a href="#api-eq">api=</a>
  117. 	    <a href="#charset-eq">charset=</a>
  118. 	    <a href="#charset-q">charset?</a>
  119. 	    <a href="#client-eq">client=</a>
  120. 	    <a href="#client-q">client?</a>
  121. 	    <a href="#connect">connect</a>
  122. 	    <a href="#cwd-eq">cwd=</a>
  123. 	    <a href="#cwd-q">cwd?</a>
  124. 	    <a href="#debug-eq">debug=</a>
  125. 	    <a href="#delete_">delete_&lt;spec type&gt;</a>
  126. 	    <a href="#disconnect">disconnect</a>
  127. 	    <a href="#errors">errors</a>
  128. 	  </td>
  129. 	  <td>
  130. 	    <a href="#exception_level-eq">exception_level=</a>
  131. 	    <a href="#exception_level-q">exception_level?</a>
  132. 	    <a href="#fetch_">fetch_&lt;spec type&gt;</a>
  133. 	    <a href="#format_spec">format_spec</a>
  134. 	    <a href="#host-eq">host=</a>
  135. 	    <a href="#host-q">host?</a>
  136. 	    <a href="#input">input</a>
  137. 	    <a href="#maxresults-eq">maxresults=</a>
  138. 	    <a href="#maxscanrows-eq">maxscanrows=</a>
  139. 	    <a href="#output">output</a>
  140. 	    <a href="#parse_forms">parse_forms</a>
  141. 	    <a href="#parse_spec">parse_spec</a>
  142. 	    <a href="#password-eq">password=</a>
  143. 	  </td>
  144. 	  <td>
  145. 	    <a href="#password-q">password?</a>
  146. 	    <a href="#prog-eq">prog=</a>
  147. 	    <a href="#port-eq">port=</a>
  148. 	    <a href="#port-q">port?</a>
  149. 	    <a href="#run">run</a>
  150. 	    <a href="#run_filelog">run_filelog</a>
  151. 	    <a href="#run_password">run_password</a>
  152. 	    <a href="#run_resolve">run_resolve</a>
  153. 	    <a href="#save_">save_&lt;spec type&gt;</a>
  154. 	    <a href="#tagged">tagged</a>
  155. 	    <a href="#user-eq">user=</a>
  156. 	    <a href="#user-q">user?</a>
  157. 	    <a href="#warnings">warnings</a>
  158. 	  </td>
  159. 	</tr>
  160.       </table>
  161.     </div>
  162.  
  163.     <a name="at_exception_level"></a>
  164.     <div class="method">
  165.       <div class="methodheader">
  166. 	<table>
  167. 	  <tr>
  168. 	    <td class="meth_name">at_exception_level</td>
  169. 	    <td class="proto">
  170. 	      <i>p4</i>.at_exception_level( lev ) { ... } -&gt; <i>self</i>
  171. 	    </td>
  172. 	  </tr>
  173. 	</table>
  174.       </div>
  175.  
  176.       Executes the associated block under a specific exception level. Returns
  177.       to the previous exception level when the block returns.
  178.  
  179.       <pre>
  180.     p4 = P4.new
  181.     p4.client = "www"
  182.     p4.connect
  183.     p4.at_exception_level( P4::RAISE_ERRORS ) do
  184.       p4.run_sync
  185.     end
  186.     p4.disconnect
  187.       </pre>
  188.     </div>
  189.  
  190.     <a name="api-eq"></a>
  191.     <div class="method">
  192.       <div class="methodheader">
  193. 	<table>
  194. 	  <tr>
  195. 	    <td class="meth_name">api=</td>
  196. 	    <td class="proto">
  197. 	      <i>p4</i>.api=<i>integer</i> -&gt; <i>self</i>
  198. 	    </td>
  199. 	  </tr>
  200. 	</table>
  201.       </div>
  202.  
  203.       <p>
  204.       Sets the API compatibility level desired. This is useful when writing
  205.       scripts using Perforce commands that do not yet support tagged output.
  206.       In these cases, upgrading to a later server that supports tagged 
  207.       output for the commands in question can break your script. Using this
  208.       method allows you to lock your script to the output format of an
  209.       older Perforce release and facilitate seamless upgrades. Note that
  210.       this method <b>must</b> be called prior to calling 
  211.       <span class="inlinecode">P4#connect</span>.
  212.       </p>
  213.       <p>
  214.       See the Perforce
  215.       <a href="http://www.perforce.com/perforce/technical.html#releasenotes">C/C++ API Release Notes</a>
  216.       for the API integer levels that correspond to each Perforce release.
  217.       </p>
  218.  
  219.       <pre>
  220.     p4 = P4.new
  221.     p4.api = 57 # Lock to 2005.1 format
  222.     p4.connect
  223.     ...
  224.       </pre>
  225.     </div>
  226.  
  227.     <a name="charset-eq"></a>
  228.     <div class="method">
  229.       <div class="methodheader">
  230. 	<table>
  231. 	  <tr>
  232. 	    <td class="meth_name">charset=</td>
  233. 	    <td class="proto">
  234. 	      <i>p4</i>.charset = <i>aString</i> -&gt; <i>aBool</i>
  235. 	    </td>
  236. 	  </tr>
  237. 	</table>
  238.       </div>
  239.  
  240.       Sets the character set to use when connected to a Unicode enabled
  241.       server. Should not be used when working with non-Unicode-enabled
  242.       servers. Returns true if the charset was valid and returns false
  243.       or raises a P4Exception (at exception level P4::RAISE_ERRORS or
  244.       higher) if the charset is invalid. [Note: some versions of Ruby
  245.       seem not to honour the boolean return value and return the charset
  246.       string instead. This appears to be a bug in Ruby]
  247.  
  248.       <pre>
  249.     p4 = P4.new
  250.     p4.client = "www"
  251.     p4.charset = "iso8859-1"
  252.     p4.connect
  253.     p4.run_sync
  254.     p4.disconnect
  255.       </pre>
  256.     </div>
  257.  
  258.     <a name="charset-q"></a>
  259.     <div class="method">
  260.       <div class="methodheader">
  261. 	<table>
  262. 	  <tr>
  263. 	    <td class="meth_name">charset?</td>
  264. 	    <td class="proto">
  265. 	      <i>p4</i>.charset? -&gt; <i>aString</i>
  266. 	    </td>
  267. 	  </tr>
  268. 	</table>
  269.       </div>
  270.  
  271.       Get the name of the character set in use when working with 
  272.       Unicode-enabled servers.
  273.  
  274.       <pre>
  275.     p4 = P4.new
  276.     p4.charset = "utf8"
  277.     p4.charset?
  278.       </pre>
  279.     </div>
  280.  
  281.     <a name="client-eq"></a>
  282.     <div class="method">
  283.       <div class="methodheader">
  284. 	<table>
  285. 	  <tr>
  286. 	    <td class="meth_name">client=</td>
  287. 	    <td class="proto">
  288. 	      <i>p4</i>.client = <i>aString</i> -&gt; true
  289. 	    </td>
  290. 	  </tr>
  291. 	</table>
  292.       </div>
  293.  
  294.       Set the name of the clientspec you wish to use. If not called, defaults
  295.       to the value of P4CLIENT taken from any P4CONFIG file present, or from
  296.       the environment as per the usual Perforce convention. Must be called 
  297.       before you connect.
  298.  
  299.       <pre>
  300.     p4 = P4.new
  301.     p4.client = "www"
  302.     p4.connect
  303.     p4.run_sync
  304.     p4.disconnect
  305.       </pre>
  306.     </div>
  307.  
  308.     <a name="client-q"></a>
  309.     <div class="method">
  310.       <div class="methodheader">
  311. 	<table>
  312. 	  <tr>
  313. 	    <td class="meth_name">client?</td>
  314. 	    <td class="proto">
  315. 	      <i>p4</i>.client? -&gt; <i>aString</i>
  316. 	    </td>
  317. 	  </tr>
  318. 	</table>
  319.       </div>
  320.  
  321.  
  322.       Get the name of the Perforce client currently in use
  323.  
  324.       <pre>
  325.     p4 = P4.new
  326.     puts( p4.client? )
  327.       </pre>
  328.     </div>
  329.  
  330.     <a name="connect"></a>
  331.     <div class="method">
  332.       <div class="methodheader">
  333. 	<table>
  334. 	  <tr>
  335. 	    <td class="meth_name">connect</td>
  336. 	    <td class="proto">
  337. 	      <i>p4</i>.connect -&gt; <i>aBool</i>
  338. 	    </td>
  339. 	  </tr>
  340. 	</table>
  341.       </div>
  342.  
  343.       Connect to the Perforce Server. You must connect before you can 
  344.       execute commands. Raises a P4Exception if the connection attempt
  345.       fails.
  346.  
  347.       <pre>
  348.     p4 = P4.new
  349.     p4.connect
  350.       </pre>
  351.     </div>
  352.  
  353.     <a name="cwd-eq"></a>
  354.     <div class="method">
  355.       <div class="methodheader">
  356. 	<table>
  357. 	  <tr>
  358. 	    <td class="meth_name">cwd=</td>
  359. 	    <td class="proto">
  360. 	      <i>p4</i>.cwd = <i>aString</i> -&gt; true
  361. 	    </td>
  362. 	  </tr>
  363. 	</table>
  364.       </div>
  365.  
  366.       Sets the current working directory. Can be called prior to executing
  367.       any Perforce command. Sometimes necessary if your script executes a 
  368.       chdir() as part of its processing.
  369.  
  370.       <pre>
  371.     p4 = P4.new
  372.     p4.cwd = "/home/tony"
  373.       </pre>
  374.     </div>
  375.  
  376.     <a name="cwd-q"></a>
  377.     <div class="method">
  378.       <div class="methodheader">
  379. 	<table>
  380. 	  <tr>
  381. 	    <td class="meth_name">cwd?</td>
  382. 	    <td class="proto">
  383. 	      <i>p4</i>.cwd? -&gt; <i>aString</i>
  384. 	    </td>
  385. 	  </tr>
  386. 	</table>
  387.       </div>
  388.  
  389.       Get the current working directory
  390.  
  391.       <pre>
  392.     p4 = P4.new
  393.     puts( p4.cwd? )
  394.       </pre>
  395.     </div>
  396.  
  397.     <a name="debug-eq"></a>
  398.     <div class="method">
  399.       <div class="methodheader">
  400. 	<table>
  401. 	  <tr>
  402. 	    <td class="meth_name">debug=</td>
  403. 	    <td class="proto">
  404. 	      <i>p4</i>.debug = <i>aNumber</i>  -&gt; true
  405. 	    </td>
  406. 	  </tr>
  407. 	</table>
  408.       </div>
  409.  
  410.       Set debug level. Debug output is written to $stderr. Debug levels are:
  411.       <div class="itemdesc">
  412. 	<div>0: No debug output (default)</div>
  413. 	<div>1: Log connect/disconnect and command execution</div>
  414. 	<div>2: Log user interface function callbacks</div>
  415. 	<div>3: Log data</div>
  416. 	<div>4: Log Ruby garbage collection</div>
  417.       </div>
  418.  
  419.       Note that levels are cumulative so level 3 includes levels 2 and 1.
  420.  
  421.       <pre>
  422.     p4 = P4.new
  423.     p4.debug = 1
  424.     p4.connect
  425.     p4.run_sync
  426.     p4.disconnect
  427.       </pre>
  428.     </div>
  429.  
  430.     <a name="delete_"></a>
  431.     <div class="method">
  432.       <div class="methodheader">
  433. 	<table>
  434. 	  <tr>
  435. 	    <td class="meth_name">delete_&lt;spec type&gt;</td>
  436. 	    <td class="proto">
  437. 	      <i>p4</i>.delete_&lt;spec type&gt;( [options], name ) -&gt; <i>anArray</i>
  438. 	    </td>
  439. 	  </tr>
  440. 	</table>
  441.       </div>
  442.  
  443.       The delete_* methods are simply shortcut methods that allow you to quickly
  444.       delete the definitions of clients, labels, branches, etc. They're 
  445.       equivalent to
  446.       <span class="inlinecode">
  447. 	p4.run( &lt;spec type&gt;, '-d', [options], &lt;spec name&gt; ).shift
  448.       </span>
  449.  
  450.       <pre>
  451.     require "P4"
  452.     require "parsedate"
  453.     include ParseDate
  454.     now = Time.now
  455.     p4 = P4.new
  456.     begin
  457.       p4.connect
  458.       p4.run_clients.each do
  459.         |client|
  460. 	atime = parsedate( client[ "AccessDate" ] )
  461. 	if( (atime + 24 * 3600 * 365 ) < now ) 
  462. 	  p4.delete_client( '-f', client[ "Client" ] )
  463. 	end
  464.       end
  465.     rescue P4Exception 
  466.       p4.errors.each { |e| puts( e ) }
  467.     ensure
  468.       p4.disconnect
  469.     end
  470.       </pre>
  471.     </div>
  472.  
  473.     <a name="disconnect"></a>
  474.     <div class="method">
  475.       <div class="methodheader">
  476. 	<table>
  477. 	  <tr>
  478. 	    <td class="meth_name">disconnect</td>
  479. 	    <td class="proto">
  480. 	      <i>p4</i>.disconnect -&gt; true
  481. 	    </td>
  482. 	  </tr>
  483. 	</table>
  484.       </div>
  485.  
  486.       Disconnect from the Perforce Server.
  487.  
  488.       <pre>
  489.     p4 = P4.new
  490.     p4.connect
  491.     p4.disconnect
  492.       </pre>
  493.     </div>
  494.  
  495.     <a name="errors"></a>
  496.     <div class="method">
  497.       <div class="methodheader">
  498. 	<table>
  499. 	  <tr>
  500. 	    <td class="meth_name">errors</td>
  501. 	    <td class="proto">
  502. 	      <i>p4</i>.errors -&gt; <i>anArray</i>
  503. 	    </td>
  504. 	  </tr>
  505. 	</table>
  506.       </div>
  507.  
  508.       Returns the array of errors which occurred during execution of the 
  509.       previous command.
  510.  
  511.       <pre>
  512.     p4 = P4.new
  513.     begin
  514.       p4.connect
  515.       p4.exception_level( P4::RAISE_ERRORS ) # to ignore "File(s) up-to-date"
  516.       p4.run_sync
  517.     rescue P4Exception 
  518.       p4.errors.each { |e| puts( e ) }
  519.     ensure
  520.       files = p4.output
  521.       p4.disconnect
  522.     end
  523.       </pre>
  524.     </div>
  525.  
  526.     <a name="exception_level-eq"></a>
  527.     <div class="method">
  528.       <div class="methodheader">
  529. 	<table width="100%">
  530. 	  <tr>
  531. 	    <td class="meth_name">exception_level=</td>
  532. 	    <td class="proto">
  533. 	      <i>p4</i>.exception_level = <i>aLevel</i> -&gt; <i>aNumber</i>
  534. 	    </td>
  535. 	  </tr>
  536. 	</table>
  537.       </div>
  538.  
  539.       Configures the events which give rise to exceptions. 
  540.       <ul>
  541. 	<li>P4::RAISE_NONE -- disables all exception raising and makes the 
  542. 	    interface completely procedural.
  543. 	</li>
  544. 	<li>P4::RAISE_ERRORS -- causes exceptions to be raised only when errors 
  545. 	    are encountered.
  546. 	</li>
  547. 	<li>P4::RAISE_ALL -- causes exceptions to be raised for both errors and 
  548. 	    warnings. This is the default.
  549. 	</li>
  550.       </ul>
  551.  
  552.       <pre>
  553.     p4 = P4.new
  554.     p4.exception_level = P4::RAISE_ERRORS
  555.  
  556.     p4.connect			# P4Exception on failure
  557.     p4.run_sync			# File(s) up-to-date is a warning so
  558.     				# no exception is raised
  559.     p4.disconnect
  560.       </pre>
  561.     </div>
  562.  
  563.     <a name="exception_level-q"></a>
  564.     <div class="method">
  565.       <div class="methodheader">
  566. 	<table width="100%">
  567. 	  <tr>
  568. 	    <td class="meth_name">exception_level?</td>
  569. 	    <td class="proto">
  570. 	      <i>p4</i>.exception_level? -&gt; <i>aNumber</i>
  571. 	    </td>
  572. 	  </tr>
  573. 	</table>
  574.       </div>
  575.  
  576.       Returns the current exception level.
  577.     </div>
  578.  
  579.     <a name="fetch_"></a>
  580.     <div class="method">
  581.       <div class="methodheader">
  582. 	<table>
  583. 	  <tr>
  584. 	    <td class="meth_name">fetch_&lt;spec type&gt;</td>
  585. 	    <td class="proto">
  586. 	      <i>p4</i>.fetch_&lt;spec type&gt;( [name] ) -&gt; <i>aHash</i>
  587. 	    </td>
  588. 	  </tr>
  589. 	</table>
  590.       </div>
  591.  
  592.       The fetch_* methods are simply shortcut methods that allow you to quickly
  593.       fetch the definitions of clients, labels, branches, etc. They're 
  594.       equivalent to
  595.       <span class="inlinecode">
  596. 	p4.run( &lt;spec type&gt;, '-o', ... ).shift
  597.       </span>
  598.  
  599.       <pre>
  600.     p4 = P4.new
  601.     begin
  602.       p4.connect
  603.       client       = p4.fetch_client()
  604.       other_client = p4.fetch_client( "other" )
  605.       label        = p4.fetch_label( "somelabel" )
  606.     rescue P4Exception 
  607.       p4.errors.each { |e| puts( e ) }
  608.     ensure
  609.       p4.disconnect
  610.     end
  611.       </pre>
  612.     </div>
  613.  
  614.     <a name="format_spec"></a>
  615.     <div class="method">
  616.       <div class="methodheader">
  617. 	<table width="100%">
  618. 	  <tr>
  619. 	    <td class="meth_name">format_spec</td>
  620. 	    <td class="proto">
  621. 	      <i>p4</i>.format_spec( &lt;spec type&gt;, aHash )-&gt; aString
  622. 	    </td>
  623. 	  </tr>
  624. 	</table>
  625.       </div>
  626.  
  627.       Converts the fields in a hash containing the elements of a Perforce form
  628.       (spec) into the familiar string reprepresentation that users know and 
  629.       love.
  630.       <p>
  631.       Requires <i>parse_forms()</i> mode.
  632.       <p>
  633.       The first argument is the type of spec to format: 'client', 'branch',
  634.       'label' etc. The second is the hash to parse.
  635.       <p>
  636.       Note that there are shortcuts available for this method. 
  637.  
  638.       <pre>
  639.     p4.format_&lt;spec type&gt;( hash )
  640.       </pre>
  641.  
  642.       instead of 
  643.  
  644.       <pre>
  645.     p4.format_spec( &lt;spec type&gt;, hash )
  646.       </pre>
  647.  
  648.       Where &lt;spec type&gt; is 'client'/'branch'/'label' etc. etc.
  649.     </div>
  650.  
  651.     <a name="host-eq"></a>
  652.     <div class="method">
  653.       <div class="methodheader">
  654. 	<table width="100%">
  655. 	  <tr>
  656. 	    <td class="meth_name">host=</td>
  657. 	    <td class="proto">
  658. 	      <i>p4</i>.host = <i>aString</i> -&gt; true
  659. 	    </td>
  660. 	  </tr>
  661. 	</table>
  662.       </div>
  663.  
  664.       Set the name of the current host. If not called, defaults to P4HOST
  665.       taken from any P4CONFIG file in effect, then P4HOST in the environment
  666.       and finally the operating system host name.
  667.  
  668.       <pre>
  669.     p4 = P4.new
  670.     p4.host = "perforce.smee.org"
  671.     p4.connect
  672.     ...
  673.     p4.disconnect
  674.       </pre>
  675.     </div>
  676.  
  677.     <a name="host-q"></a>
  678.     <div class="method">
  679.       <div class="methodheader">
  680. 	<table width="100%">
  681. 	  <tr>
  682. 	    <td class="meth_name">host?</td>
  683. 	    <td class="proto">
  684. 	      <i>p4</i>.host? -&gt; <i>aString</i>
  685. 	    </td>
  686. 	  </tr>
  687. 	</table>
  688.       </div>
  689.  
  690.       Get the current hostname
  691.  
  692.       <pre>
  693.     p4 = P4.new
  694.     puts( p4.host? )
  695.       </pre>
  696.     </div>
  697.  
  698.     <a name="input"></a>
  699.     <div class="method">
  700.       <div class="methodheader">
  701. 	<table width="100%">
  702. 	  <tr>
  703. 	    <td class="meth_name">input</td>
  704. 	    <td class="proto">
  705. 	      <i>p4</i>.input( aString ) -&gt; true or false<br>
  706. 	      <i>p4</i>.input( aHash ) -&gt; true or false<br>
  707. 	      <i>p4</i>.input( anArray ) -&gt; true or false
  708. 	    </td>
  709. 	  </tr>
  710. 	</table>
  711.       </div>
  712.  
  713.       Call prior to running a command requiring input from the user. When
  714.       the command requests input, it's the data supplied here that will be
  715.       returned. This applies most commonly to commands of the form
  716.       <span class="inlinecode">"p4 cmd -i"</span>. Note that typically 
  717.       commands of that form are invoked using the 
  718.       <span class="inlinecode"><a href="#save_">P4#save_*</a></span>
  719.       methods which call 
  720.       <span class="inlinecode">P4#input()</span> internally. So there is no need
  721.       to call this method when using the <span class="inlinecode">save_*</span>
  722.       shortcuts.
  723.       <br><br>
  724.       You may pass a string, a hash or (for commands that take multiple inputs 
  725.       from the user) an array of strings/hashes. You may only pass hashes 
  726.       when working in <span class="inlinecode">parse_forms</span> mode. If you
  727.       pass an array, note that the array will be 'shifted' each time Perforce
  728.       asks the user for input.
  729.       <pre>
  730.     p4 = P4.new
  731.     p4.parse_forms
  732.     p4.connect
  733.  
  734.     change = p4.run_change( "-o" ).shift
  735.     change[ "Description" ] = "Autosubmitted changelist"
  736.  
  737.     p4.input( change )
  738.     p4.run_submit( "-i" )
  739.  
  740.     p4.disconnect
  741.       </pre>
  742.  
  743.       Note that <span class="inlinecode">P4#input</span> cannot predict
  744.       whether or not the supplied input will be acceptable to the next 
  745.       command the user runs so it always returns true - regardless of the
  746.       validity of the input.
  747.     </div>
  748.  
  749.     <a name="maxresults-eq"></a>
  750.     <div class="method">
  751.       <div class="methodheader">
  752. 	<table width="100%">
  753. 	  <tr>
  754. 	    <td class="meth_name">maxresults=</td>
  755. 	    <td class="proto">
  756. 	      <i>p4</i>.maxresults = <i>aNumber</i> -&gt; <i>aNumber</i>
  757. 	    </td>
  758. 	  </tr>
  759. 	</table>
  760.       </div>
  761.  
  762.       Limit the number of results Perforce will permit for subsequent 
  763.       commands. Commands that produce more than this number of results will
  764.       be aborted. The limit remains in force until you disable it by setting
  765.       it to zero. See <span class="inlinecode">p4 help maxresults</span> for
  766.       information on the commands that support this limit.
  767.  
  768.       <pre>
  769.     p4 = P4.new
  770.     begin
  771.       p4.connect
  772.       p4.maxresults = 100
  773.       files = p4.run_sync
  774.     rescue P4Exception =&gt; ex
  775.       p4.errors.each { |e| $stderr.puts( e ) }
  776.     ensure
  777.       p4.disconnect
  778.     end
  779.       </pre>
  780.     </div>
  781.  
  782.     <a name="maxscanrows-eq"></a>
  783.     <div class="method">
  784.       <div class="methodheader">
  785. 	<table width="100%">
  786. 	  <tr>
  787. 	    <td class="meth_name">maxscanrows=</td>
  788. 	    <td class="proto">
  789. 	      <i>p4</i>.maxscanrows = <i>aNumber</i> -&gt; <i>aNumber</i>
  790. 	    </td>
  791. 	  </tr>
  792. 	</table>
  793.       </div>
  794.  
  795.       Limit the number of database records Perforce will scan for subsequent 
  796.       commands. Commands that attempt to scan more than this number of 
  797.       records will be aborted. The limit remains in force until you disable 
  798.       it by setting it to zero. See 
  799.       <span class="inlinecode">p4 help maxresults</span> for
  800.       information on the commands that support this limit.
  801.  
  802.       <pre>
  803.     p4 = P4.new
  804.     begin
  805.       p4.connect
  806.       p4.maxscanrows = 100
  807.       files = p4.run_sync
  808.     rescue P4Exception =&gt; ex
  809.       p4.errors.each { |e| $stderr.puts( e ) }
  810.     ensure
  811.       p4.disconnect
  812.     end
  813.       </pre>
  814.     </div>
  815.  
  816.     <a name="output"></a>
  817.     <div class="method">
  818.       <div class="methodheader">
  819. 	<table width="100%">
  820. 	  <tr>
  821. 	    <td class="meth_name">output</td>
  822. 	    <td class="proto">
  823. 	      <i>p4</i>.output -&gt; <i>anArray</i>
  824. 	    </td>
  825. 	  </tr>
  826. 	</table>
  827.       </div>
  828.  
  829.       Get the results of the previous command. Returns an array 
  830.       containing the output of the command.  Useful in a rescue block when a 
  831.       command has partially worked, and you still need to look at the command 
  832.       output.
  833.  
  834.       <pre>
  835.     p4 = P4.new
  836.     begin
  837.       p4.connect
  838.       p4.exception_level( P4::RAISE_ERRORS ) # to ignore "File(s) up-to-date"
  839.       files = p4.run_sync
  840.     rescue P4Exception =&gt; ex
  841.       files = p4.output
  842.       if files.length
  843. 	puts( "Sync succeeded with errors" )
  844.       else
  845.         puts( "Sync failed!" )
  846.       end
  847.     ensure
  848.       p4.disconnect
  849.     end
  850.       </pre>
  851.     </div>
  852.  
  853.     <a name="parse_forms"></a>
  854.     <div class="method">
  855.       <div class="methodheader">
  856. 	<table width="100%">
  857. 	  <tr>
  858. 	    <td class="meth_name">parse_forms</td>
  859. 	    <td class="proto">
  860. 	      <i>p4</i>.parse_forms -&gt; true
  861. 	    </td>
  862. 	  </tr>
  863. 	</table>
  864.       </div>
  865.  
  866.  
  867.       Extends the capabilities of tagged output to include Perforce forms. Forms
  868.       returned by Perforce in response to commands such as "p4 client -o" will 
  869.       be parsed and returned to the caller as a Ruby hash containing keys for 
  870.       each of the fields on the form. Where a form element may contain more 
  871.       than one value, the hash value is an array containing the form elements. 
  872.       <span class="inlinecode">parse_forms</span> implies the use of 
  873.       <span class="inlinecode">tagged</span>.
  874.  
  875.       <pre>
  876.     p4 = P4.new
  877.     p4.parse_forms
  878.     p4.connect
  879.     clientspec = p4.run_client( "-o" ).shift
  880.     puts( clientspec[ "Options" ] )
  881.     p4.disconnect
  882.       </pre>
  883.  
  884.       Such parsed forms are also acceptable as input to commands of the form
  885.       <span class="inlinecode">"p4 XXXX -i"</span>. For example, to change 
  886.       the root of a clientspec you could use:
  887.  
  888.       <pre>
  889.     p4 = P4.new
  890.     p4.parse_forms
  891.     p4.connect
  892.     spec = p4.run_client( "-o" ).shift
  893.     spec[ "Root" ] = "/home/my/new/root" 
  894.     p4.input( spec )
  895.     p4.run_client( "-i" )
  896.     p4.disconnect
  897.       </pre>
  898.     </div>
  899.  
  900.     <a name="parse_spec"></a>
  901.     <div class="method">
  902.       <div class="methodheader">
  903. 	<table width="100%">
  904. 	  <tr>
  905. 	    <td class="meth_name">parse_spec</td>
  906. 	    <td class="proto">
  907. 	      <i>p4</i>.parse_spec( &lt;spec type&gt;, aString )-&gt; aHash
  908. 	    </td>
  909. 	  </tr>
  910. 	</table>
  911.       </div>
  912.  
  913.       Parses a Perforce form (spec) in text form into a Ruby hash using the
  914.       spec definition obtained from the server. Requires <i>parse_forms()</i>
  915.       mode.
  916.       <p>
  917.       The first argument is the type of spec to parse: "client", "branch",
  918.       "label" etc. The second is the raw buffer to parse.
  919.       <p>
  920.       Note that there are shortcuts available for this method. 
  921.  
  922.       <pre>
  923.     p4.parse_&lt;spec type&gt;( buf )
  924.       </pre>
  925.  
  926.       instead of 
  927.  
  928.       <pre>
  929.     p4.parse_spec( &lt;spec type&gt;, buf )
  930.       </pre>
  931.  
  932.       Where &lt;spec type&gt; is 'client'/'branch'/'label' etc. etc.
  933.     </div>
  934.  
  935.     <a name="password-eq"></a>
  936.     <div class="method">
  937.       <div class="methodheader">
  938. 	<table width="100%">
  939. 	  <tr>
  940. 	    <td class="meth_name">password=</td>
  941. 	    <td class="proto">
  942. 	      <i>p4</i>.password = <i>aString</i>  -&gt; true
  943. 	    </td>
  944. 	  </tr>
  945. 	</table>
  946.       </div>
  947.  
  948.       Set your Perforce password, in plain text. If not used, takes the value of
  949.       P4PASSWD from any P4CONFIG file in effect, or from the environment 
  950.       according to the normal Perforce conventions. This password will also be 
  951.       used if you later call <span class="inlinecode">p4.run_login</span> to 
  952.       login using the 2003.2 and later ticket system.
  953.  
  954.       <pre>
  955.     p4 = P4.new
  956.     p4.password = "mypass"
  957.     p4.connect
  958.     p4.run_login
  959.       </pre>
  960.     </div>
  961.  
  962.     <a name="password-q"></a>
  963.     <div class="method">
  964.       <div class="methodheader">
  965. 	<table width="100%">
  966. 	  <tr>
  967. 	    <td class="meth_name">password?</td>
  968. 	    <td class="proto">
  969. 	      <i>p4</i>.password? -&gt; <i>aString</i>
  970. 	    </td>
  971. 	  </tr>
  972. 	</table>
  973.       </div>
  974.  
  975.       Get the current password. This may be the password in plain text, or if
  976.       you've used <span class="inlinecode">p4.run_login</span>, it'll be the
  977.       value of the ticket you've been allocated by the server.
  978.  
  979.       <pre>
  980.     p4 = P4.new
  981.     puts( p4.password? )
  982.       </pre>
  983.     </div>
  984.  
  985.     <a name="prog-eq"></a>
  986.     <div class="method">
  987.       <div class="methodheader">
  988. 	<table width="100%">
  989. 	  <tr>
  990. 	    <td class="meth_name">prog=</td>
  991. 	    <td class="proto">
  992. 	      <i>p4</i>.prog = <i>aString</i> -&gt; true
  993. 	    </td>
  994. 	  </tr>
  995. 	</table>
  996.       </div>
  997.  
  998.       Set the name of your 'program'. This value is visible to Perforce
  999.       system administrators running 
  1000.       <span class="inlinecode">'p4 monitor show -e'</span>
  1001.       in Perforce 2004.2 or later releases.
  1002.  
  1003.       <pre>
  1004.     p4 = P4.new
  1005.     p4.prog = "sync-script"
  1006.     p4.connect
  1007.     ...
  1008.     p4.disconnect
  1009.       </pre>
  1010.     </div>
  1011.  
  1012.     <a name="port-eq"></a>
  1013.     <div class="method">
  1014.       <div class="methodheader">
  1015. 	<table width="100%">
  1016. 	  <tr>
  1017. 	    <td class="meth_name">port=</td>
  1018. 	    <td class="proto">
  1019. 	      <i>p4</i>.port = <i>aString</i> -&gt; true
  1020. 	    </td>
  1021. 	  </tr>
  1022. 	</table>
  1023.       </div>
  1024.  
  1025.  
  1026.       Set the host and port address of the Perforce server you want to 
  1027.       connect to. If not called, defaults to the value of P4PORT in any 
  1028.       P4CONFIG file in effect and then to the value of P4PORT taken from the
  1029.       environment.
  1030.  
  1031.       <pre>
  1032.     p4 = P4.new
  1033.     p4.port = "localhost:1666"
  1034.     p4.connect
  1035.     ...
  1036.     p4.disconnect
  1037.       </pre>
  1038.     </div>
  1039.  
  1040.     <a name="port-q"></a>
  1041.     <div class="method">
  1042.       <div class="methodheader">
  1043. 	<table width="100%">
  1044. 	  <tr>
  1045. 	    <td class="meth_name">port?</td>
  1046. 	    <td class="proto">
  1047. 	      <i>p4</i>.port? -&gt; <i>aString</i>
  1048. 	    </td>
  1049. 	  </tr>
  1050. 	</table>
  1051.       </div>
  1052.  
  1053.  
  1054.       Get the address of the current Perforce server.
  1055.  
  1056.       <pre>
  1057.     p4 = P4.new
  1058.     puts( p4.port? )
  1059.       </pre>
  1060.     </div>
  1061.  
  1062.     <a name="run">
  1063.     <div class="method">
  1064.       <div class="methodheader">
  1065. 	<table width="100%">
  1066. 	  <tr>
  1067. 	    <td class="meth_name">run</td>
  1068. 	    <td class="proto">
  1069. 	      <i>p4</i>.run( <i>aCommand</i>, <i>arguments...</i> ) -&gt; <i>anArray</i>
  1070. 	    </td>
  1071. 	  </tr>
  1072. 	</table>
  1073.       </div>
  1074.  
  1075.       Base interface to all the run methods in this API. Runs the specified 
  1076.       Perforce command with the arguments supplied. Arguments may be in 
  1077.       any form you like as long as it responds nicely to 
  1078.       <span class="inlinecode">to_s</span>.
  1079.       <p>
  1080.       If the command succeeds without errors or warnings, then run returns
  1081.       an array of results. Whether the elements of the array are strings or
  1082.       hashes depends on (a) the command executed and (b) whether 
  1083.       <span class="inlinecode">tagged()</span> or
  1084.       <span class="inlinecode">parse_forms()</span> have been called.
  1085.       <p>
  1086.       The array that is returned is equivalent to that returned by 
  1087.       <span class="inlinecode">p4.output</span>.
  1088.       <p>
  1089.       In the event of errors or warnings, and depending on the exception level
  1090.       in force at the time, run will raise a P4Exception. If the current 
  1091.       exception level is below the threshold for the error/warning, then run
  1092.       returns the output as normal and the caller must explicitly review 
  1093.       <span class="inlinecode">p4.errors</span> and 
  1094.       <span class="inlinecode">p4.warnings</span> to check for errors or 
  1095.       warnings.
  1096.  
  1097.       <pre>
  1098.     p4 = P4.new
  1099.     p4.connect
  1100.     spec = p4.run( "client", "-o" ).shift
  1101.     p4.disconnect
  1102.       </pre>
  1103.  
  1104.       Through the magic of Object#method_missing, you can save yourself some
  1105.       typing as 
  1106.  
  1107.       <pre>
  1108.     p4.run_XXX( args )
  1109.       </pre>
  1110.   
  1111.       is translated into
  1112.  
  1113.       <pre>
  1114.     p4.run( "XXX", args )
  1115.       </pre>
  1116.  
  1117.       There are also some shortcuts for common commands such as editing 
  1118.       Perforce forms and submitting. So this:
  1119.  
  1120.       <pre>
  1121.     p4 = P4.new
  1122.     p4.parse_forms
  1123.     p4.connect
  1124.     <b>clientspec = p4.run_client( "-o" ).shift</b>
  1125.     clientspec[ "Description" ] = "Build client"
  1126.     <b>p4.input( clientspec )
  1127.     p4.run_client( "-i" )</b>
  1128.     p4.disconnect
  1129.       </pre>
  1130.  
  1131.       May be shortened to 
  1132.  
  1133.       <pre>
  1134.     p4 = P4.new
  1135.     p4.parse_forms
  1136.     p4.connect
  1137.     <b>clientspec = p4.fetch_client</b>
  1138.     clientspec[ "Description" ] = "Build client"
  1139.     <b>p4.save_client( clientspec )</b>
  1140.     p4.disconnect
  1141.       </pre>
  1142.  
  1143.       In fact, the following are equivalent:
  1144.       <p>
  1145.       <table border=1 cellpadding="10">
  1146. 	<tr>
  1147. 	  <td>p4.delete_xxx</td>
  1148. 	  <td>p4.run_xxx( "-d ").shift</td>
  1149. 	</tr>
  1150. 	<tr>
  1151. 	  <td>p4.fetch_xxx</td>
  1152. 	  <td>p4.run_xxx( "-o ").shift</td>
  1153. 	</tr>
  1154. 	<tr>
  1155. 	  <td>p4.save_xxx( spec )</td>
  1156. 	  <td>p4.input( spec )<br>
  1157. 	      p4.run_xxx( "-i" ).shift
  1158. 	  </td>
  1159. 	</tr>
  1160.       </table>
  1161.       <p>
  1162.       Note that the fetch_xxx methods do not return an array as typically there
  1163.       is only one result item from such commands. Accordingly, they return the
  1164.       first result element.
  1165.       <p>
  1166.       There is also a special shortcut for submitting
  1167.  
  1168.       <pre>
  1169.     p4 = P4.new
  1170.     p4.parse_forms
  1171.     p4.connect
  1172.     spec = p4.fetch_change
  1173.     spec[ "Description" ] = "Automated change"
  1174.     <b>p4.submit_spec( spec )</b>
  1175.     p4.disconnect
  1176.       </pre>
  1177.     </div>
  1178.  
  1179.     <a name="run_filelog">
  1180.     <div class="method">
  1181.       <div class="methodheader">
  1182. 	<table>
  1183. 	  <tr>
  1184. 	    <td class="meth_name">run_filelog</td>
  1185. 	    <td class="proto">
  1186. 	      <i>p4</i>.run_filelog(<i>fileSpec</i>) -&gt; <i>anArray</i>
  1187. 	    </td>
  1188. 	  </tr>
  1189. 	</table>
  1190.       </div>
  1191.  
  1192.       Runs a <span class="inlinecode">p4 filelog</span> on the fileSpec
  1193.       provided and returns an array of 
  1194.       <a href="P4DepotFile.html">P4DepotFile</a> results when executed in
  1195.       tagged mode. The raw output of <span class="inlinecode">p4 filelog</span> 
  1196.       in tagged mode is difficult to work with so this method restructures
  1197.       the output into a more user-friendly (and object-oriented) form.
  1198.  
  1199.       <pre>
  1200.     p4 = P4.new
  1201.     p4.parse_forms
  1202.     begin
  1203.       p4.connect
  1204.       p4.run_filelog( "index.html" ).shift.each_revision do
  1205.           |r|
  1206. 	  r.each_integration do
  1207. 	      |i|
  1208. 	      # Do something
  1209. 	  end
  1210.       end
  1211.     rescue P4Exception 
  1212.       p4.errors.each { |e| puts( e ) }
  1213.     ensure
  1214.       p4.disconnect
  1215.     end
  1216.       </pre>
  1217.     </div>
  1218.  
  1219.     <a name="run_password">
  1220.     <div class="method">
  1221.       <div class="methodheader">
  1222. 	<table>
  1223. 	  <tr>
  1224. 	    <td class="meth_name">run_password</td>
  1225. 	    <td class="proto">
  1226. 	      <i>p4</i>.run_password(<i>oldpass</i>, <i>newpass</i>) -&gt; <i>anArray</i>
  1227. 	    </td>
  1228. 	  </tr>
  1229. 	</table>
  1230.       </div>
  1231.  
  1232.       A thin wrapper to make it easy to change your password. This method
  1233.       is (literally) equivalent to the following code:
  1234.       <pre>
  1235. 	p4.input( [ <i>oldpass</i>, <i>newpass</i>, <i>newpass</i> ] )
  1236. 	p4.run( "password" )
  1237.       </pre>
  1238.  
  1239.       For example:
  1240.  
  1241.       <pre>
  1242.     p4 = P4.new
  1243.     p4.password = "myoldpass"
  1244.     begin
  1245.       p4.connect
  1246.       p4.run_password( "myoldpass", "mynewpass" )
  1247.     rescue P4Exception 
  1248.       p4.errors.each { |e| puts( e ) }
  1249.     ensure
  1250.       p4.disconnect
  1251.     end
  1252.       </pre>
  1253.     </div>
  1254.  
  1255.     <a name="run_resolve">
  1256.     <div class="method">
  1257.       <div class="methodheader">
  1258. 	<table>
  1259. 	  <tr>
  1260. 	    <td class="meth_name">run_resolve</td>
  1261. 	    <td class="proto">
  1262. 	      <i>p4</i>.run_resolve( <i>args</i> ) [ <i>block</i> ] -&gt; <i>anArray</i>
  1263. 	    </td>
  1264. 	  </tr>
  1265. 	</table>
  1266.       </div>
  1267.  
  1268.       Interface to 'p4 resolve'. Without a block, simply runs a 
  1269.       non-interactive resolve - typically an automatic resolve. 
  1270.  
  1271.       <pre>
  1272. 	p4.run_resolve( "-at" )
  1273.       </pre>
  1274.  
  1275.       <p>
  1276.       When a block is supplied, the block is invoked once for each
  1277.       merge scheduled by Perforce. For each merge, a 
  1278.       <a href="P4MergeData.html">P4::MergeData</a>
  1279.       object is passed to the block. This object contains the 
  1280.       context of the merge. 
  1281.       </p>
  1282.       <p><b>
  1283. 	Note that this interface is evolving and is subject to 
  1284. 	change in future versions of P4Ruby.
  1285.       </b></p>
  1286.  
  1287.       <p>
  1288.       The block decides the outcome of the merge by evaluating to one
  1289.       of the following strings
  1290.       </p>
  1291.  
  1292.       <ul>
  1293. 	<li>"ay" - Accept Yours</li>
  1294. 	<li>"at" - Accept Theirs</li>
  1295. 	<li>"am" - Accept Merge result</li>
  1296. 	<li>"ae" - Accept Edited result</li>
  1297. 	<li>"s"	 - Skip this merge</li>
  1298. 	<li>"q"	 - Abort the merge</li>
  1299.       </ul>
  1300.  
  1301.       <pre>
  1302. 	p4.run_resolve() do
  1303. 	    |md|
  1304. 	    puts( "Merging..." )
  1305. 	    puts( "Yours: #{md.your_name}" )
  1306. 	    puts( "Theirs: #{md.their_name}" )
  1307. 	    puts( "Base: #{md.base_name}" )
  1308. 	    puts( "Yours file: #{md.your_path}" )
  1309. 	    puts( "Theirs file: #{md.their_path}" )
  1310. 	    puts( "Base file: #{md.base_path}" )
  1311. 	    puts( "Result file: #{md.result_path}" )
  1312. 	    puts( "Merge Hint: #{md.merge_hint}" )
  1313.  
  1314. 	    result = md.merge_hint
  1315. 	    if( result == "e" &amp;&amp; ENV.has_key?( "P4MERGE" ) )
  1316. 		puts( "Invoking external merge application" )
  1317. 		result = "s"	# If the merge doesn't work, we'll skip
  1318. 		result = "am" if md.run_merge()
  1319. 	    end
  1320. 	    result
  1321. 	end
  1322.       </pre>
  1323.     </div>
  1324.  
  1325.     <a name="save_">
  1326.     <div class="method">
  1327.       <div class="methodheader">
  1328. 	<table>
  1329. 	  <tr>
  1330. 	    <td class="meth_name">save_&lt;spec type&gt;</td>
  1331. 	    <td class="proto">
  1332. 	      <i>p4</i>.save_&lt;spec type&gt;( [options], <i>hashOrString</i> ) -&gt; <i>anArray</i>
  1333. 	    </td>
  1334. 	  </tr>
  1335. 	</table>
  1336.       </div>
  1337.  
  1338.       The save_* methods are simply shortcut methods that allow you to quickly
  1339.       update the definitions of clients, labels, branches, etc. They're 
  1340.       equivalent to
  1341.       <span class="inlinecode">
  1342. 	p4.run( &lt;spec type&gt;, '-i', [options,] <i>hashOrString</i> ).shift
  1343.       </span>
  1344.  
  1345.       <pre>
  1346.     p4 = P4.new
  1347.     begin
  1348.       p4.connect
  1349.       client       	= p4.fetch_client()
  1350.       client[ "Owner" ] = p4.user?
  1351.       p4.save_client( client )
  1352.     rescue P4Exception 
  1353.       p4.errors.each { |e| puts( e ) }
  1354.     ensure
  1355.       p4.disconnect
  1356.     end
  1357.       </pre>
  1358.     </div>
  1359.  
  1360.     <a name="tagged">
  1361.     <div class="method">
  1362.       <div class="methodheader">
  1363. 	<table width="100%">
  1364. 	  <tr>
  1365. 	    <td class="meth_name">tagged</td>
  1366. 	    <td class="proto">
  1367. 	      <i>p4</i>.tagged -&gt; true
  1368. 	    </td>
  1369. 	  </tr>
  1370. 	</table>
  1371.       </div>
  1372.  
  1373.       Enables tagged output. Responses to Perforce commands which support
  1374.       tagged output will be converted into Ruby hashes. Must be called 
  1375.       before connecting to the server.
  1376.  
  1377.       <pre>
  1378.     p4 = P4.new
  1379.     p4.tagged
  1380.     p4.connect
  1381.     ...
  1382.     p4.disconnect
  1383.       </pre>
  1384.     </div>
  1385.  
  1386.     <a name="user-eq">
  1387.     <div class="method">
  1388.       <div class="methodheader">
  1389. 	<table width="100%">
  1390. 	  <tr>
  1391. 	    <td class="meth_name">user=</td>
  1392. 	    <td class="proto">
  1393. 	      <i>p4</i>.user = <i>aString</i> -&gt; true
  1394. 	    </td>
  1395. 	  </tr>
  1396. 	</table>
  1397.       </div>
  1398.  
  1399.       Set your Perforce username. If not set defaults to the value of P4USER
  1400.       taken from any P4CONFIG file in effect, then the value of P4USER in your
  1401.       environment and lastly your operating system user name.
  1402.  
  1403.       <pre>
  1404.     p4 = P4.new
  1405.     p4.user = "tony"
  1406.     p4.connect
  1407.     ...
  1408.     p4.disconnect
  1409.       </pre>
  1410.     </div>
  1411.  
  1412.     <a name="user-q">
  1413.     <div class="method">
  1414.       <div class="methodheader">
  1415. 	<table width="100%">
  1416. 	  <tr>
  1417. 	    <td class="meth_name">user?</td>
  1418. 	    <td class="proto">
  1419. 	      <i>p4</i>.user? -&gt; <i>aString</i>
  1420. 	    </td>
  1421. 	  </tr>
  1422. 	</table>
  1423.       </div>
  1424.  
  1425.       Returns your current Perforce user name
  1426.  
  1427.       <pre>
  1428.     p4 = P4.new
  1429.     puts( p4.user? )
  1430.       </pre>
  1431.     </div>
  1432.  
  1433.     <a name="warnings">
  1434.     <div class="method">
  1435.       <div class="methodheader">
  1436. 	<table width="100%">
  1437. 	  <tr>
  1438. 	    <td class="meth_name">warnings</td>
  1439. 	    <td class="proto">
  1440. 	      <i>p4</i>.warnings -&gt; <i>anArray</i>
  1441. 	    </td>
  1442. 	  </tr>
  1443. 	</table>
  1444.       </div>
  1445.  
  1446.  
  1447.       Returns the array of warnings which arose during execution of the last
  1448.       command.
  1449.  
  1450.       <pre>
  1451.     p4 = P4.new
  1452.     begin
  1453.       p4.connect
  1454.       p4.exception_level( P4::RAISE_ALL ) # "File(s) up-to-date" is a warning
  1455.       files = p4.run_sync
  1456.     rescue P4Exception =&gt; ex
  1457.       p4.warnings.each { |w| puts( w ) }
  1458.     ensure
  1459.       p4.disconnect
  1460.     end
  1461.       </pre>
  1462.     </div>
  1463.   </div>
  1464.  
  1465.   <h3>See Also</h3>
  1466.  
  1467.   <div class="seealso">
  1468.     <a href="P4DepotFile.html">P4DepotFile</a>
  1469.     <a href="P4Exception.html">P4Exception</a>
  1470.     <a href="P4Integration.html">P4Integration</a>
  1471.     <a href="P4Revision.html">P4Revision</a>
  1472.     <a href="P4MergeData.html">P4::MergeData</a>
  1473.     <a href="P4Spec.html">P4::Spec</a>
  1474.   </div>
  1475.  
  1476. </body>
  1477. </html>
# Change User Description Committed
#21 5791 Tony Smith Add experimental support for passing a block to P4#run_resolve.
The
block is passed a P...4::MergeData object encapsulating the context of
each merge performed. The block should evaluate to a string indicating
the desired result of the merge: 'ay', 'at', 'am', 's', etc. The
P4::MergeData object contains information about the files involved
in the merge and can invoke an external merge tool.

This is still experimental at this stage so the interface may
change as it evolves. «		 18 years ago
#20 5311 Tony Smith Add new P4#api= method to allow users to lock scripts to a
particular API level. This hel...ps when upgrading to new servers
that extend support for tagged output to hitherto unsupported
commands (2005.2 did a lot of that).

See the C/C++ API Release Notes for the full details, but by way of
example, to lock scripts to the 2005.1 interface use:

    p4.api = 57 «		 19 years ago
#19 5222 Tony Smith Improve debug output in P4Ruby:

    p4.debug = 1    * Show commands... being executed
    p4.debug = 2    * Show function calls
    p4.debug = 3    * Show data
    p4.debug = 4    * Show ruby garbage collection calls.

Debug levels are cumulative as you'd expect. «		 19 years ago
#18 5169 Tony Smith Add missing parse_forms() call to example 19 years ago
#17 4942 Tony Smith Add support for Unicode servers to P4Ruby.
This change adds two
new interfaces, P4#chars...et= and P4#charset? to set and get the
charset respectively. «		 20 years ago
#16 4830 Tony Smith Add named constants for P4Ruby's exception levels.
The valid levels
are:
   ... P4::RAISE_NONE      -- No exceptions
    P4::RAISE_ERRORS    -- Exceptions on errors only
    P4::RAISE_ALL        -- Exceptions on errors and warnings

Also added P4#at_exception_level( level ) { ... } method to allow you
to run a block of code at a different exception level and revert to
the previous level when the block completes. Thanks to Johan Nilsson.

Some doc tidying along with the docs for the features above. «		 20 years ago
#15 4810 Tony Smith Fix the anchor names in the docs.
Correction to previous change. 		20 years ago
#14 4809 Tony Smith Add P4#maxresults= and P4#maxscanrows= methods to allow you to place
explicit limits on t...he execution of individual commands. These limits
remain in force for all subsequent commands until they are removed
by setting them to zero. Port of new functionality from P4Perl. «		 20 years ago
#13 4753 Tony Smith Add support for executing commands which prompt the user for input
more than once during... their execution. A perfect example is
'p4 password' which prompts the user three times. This works
by allowing P4#input() to take an array argument. Each time
Perforce prompts the user (by calling ClientUserRuby::Prompt()),
the array is shifted by one and the first value in the array
is passed to Perforce. Thus, to change your password a
three-element array is needed comprising of your old password, and
the new password twice.

To make this a little easier on the eye, this change also includes
a thin wrapper called P4#run_password() which takes simply the old
password and the new password and constructs a suitable input
array.

This change also includes docs for the above, and docs for
P4#run_filelog() which were found to be missing. «		 20 years ago
#12 4680 Tony Smith Make P4Ruby return new P4::Spec objects instead of plain old
hashes when parse_forms mode... is in use. A P4::Spec object is derived
from Hash so should be backwards compatible with previous code.

P4::Spec provides limited fieldname validation on forms and
accessor methods for quick and easy access to the fields in the
form. The accessor methods are all prefixed with '_' to avoid
colliding with methods from the Hash parent class. This is a little
ugly, but deriving from hash is a big win, so it's worth it.

This change also fixes a minor bug found along the way. Spec parsing
and formatting wouldn't work with labels, branches, depots and groups
unless you'd previously run a P4::fetch_label( <label> ),
P4::fetch_branch( <branch> ) etc. etc. This is because the spec
parsing code internally runs one of these commands in order to grab
the specdef from the server but it wasn't providing a spec name. i.e.
it was using 'p4 client -o' and assuming that this would work for
other types of spec too. It does, but not for all spec types. So,
now the spec parsing code will use a bogus name for the spec types
that require it. «		 20 years ago
#11 4653 Tony Smith More documentation tweaks.
Just makes the pages look more
like the reference pages in the... 'Pickaxe book' «		 20 years ago
#10 4652 Tony Smith Doc update for P4Ruby.
Rework the html and the CSS to make the
docs a little easier on t...he eye and easier to use too. «		 20 years ago
#9 4651 Tony Smith Add format_spec() method and format_* shortcuts to make it easy
to convert a spec in a ha...sh back to its string form without sending
it to the server. «		 20 years ago
#8 4593 Tony Smith Add support for 'p4 login' to P4Ruby per request from Robert
Cowham. New installer to fol...low. «		 20 years ago
#7 4589 Tony Smith Update P4Ruby to support the new SetProg() method in the 2004.2 API.
Whilst the new 'P4#p...rog=' method is always available, it's only
functional if P4Ruby is built with a 2004.2 or later API.

The build system got a bit of tidying up to support this change and
the API version is now detected automatically if possible. I've also
removed the --apilibdir and --apiincludedir flags as they complicate
matters and I never use them and I don't believe anyone else does
either.

There are also some minor doc formatting tweaks to go along with
the added documentation for prog=. «		 20 years ago
#6 4261 Tony Smith Add support for parsing arbitrary specs from strings in Ruby space.
Useful with spec depo...ts. You might obtain the spec by running a
"p4 print -q" against a file in a spec depot, but want to parse it
into a Ruby hash.

i.e.
    p4 = P4.new
    p4.parse_forms    # Required!
    p4.connect

    buf = p4.run_print( "-q", "//specs/client/myclient" )
    spec = p4.parse_client( buf )

    # Or equivalently
    spec = p4.parse_spec( "client", buf ) «		 21 years ago
#5 4255 Tony Smith P4Ruby doc reformatting.
Now uses CSS instead of 1x1 image and too
many tables. Could no... doubt be improved upon, but it's a start. «		 21 years ago
#4 2426 Tony Smith Doc beautifying for P4Ruby. 22 years ago
#3 2085 Tony Smith Get rid of specdef hack in the Ruby API.
No need to store it
in the hash, just grab it... from the RPC buffer when needed. «		 23 years ago
#2 1426 Tony Smith Cleaned up the debug output a little.
Introduced some debug levels
so you can decide (ro...ughly) what output you want to see. Level 1
shows command execution, connect and disconnect. Level 2 includes
Level 1 and also shows the RPC callbacks as they happen. Level 3
includes 1 and 2 and also shows when Ruby garbage collection takes
place.

Converted all the simple methods of the form P4#meth( arg ) to
       aliases for P4#meth=. Added P4#debug= to complete the scheme. The
P4#meth( arg ) forms are now deprecated. i.e. you should use:

    p4.user = "tony"

and not:

    p4.user( "tony" )

It's just more Ruby-like. «		 23 years ago
#1 1324 Tony Smith P4/Ruby documentation update.
Changed doc layout and added
in docs for newly added method...s and classes. «		 23 years ago
//guest/tony_smith/perforce/API/Ruby/main/P4.html
#3 1166 Tony Smith Followup to previous change.

Simplify the interface to getting results/errors and warnin...gs.
No need for the P4Result class anymore so that's gone (though
it's still there as a C++ class because it's useful) and so
is P4#result. Now you get your errors/warnings and results using
P4#errors, P4#warnings and P4#output all of which return arrays. «		 23 years ago
#2 1165 Tony Smith Minor reshuffle.
Added the ability to disable exceptions
completely if you don't like th...em or to have them raised only
for errors (and not for warnings). Removed P4#warnings
interface and replaced it with P4#exception_level.

Some minor doc tweaks to go with the above change «		 23 years ago
#1 1164 Tony Smith Reworked exception handling (hopefully for the last time) in
P4/Ruby. Now exceptions are... raised on completion of Perforce
commands if any errors or warnings were received as part of
executing the command.

This change also adds documentation, and indexes the Ruby
interface off my main page. Bad form to combine so many changes
in one changelist, but it's getting late and I want to get
them submitted! «		 23 years ago