<html> <head> <title>P4/Ruby - P4 class</title> <link rel="stylesheet" type="text/css" href="docstyle.css"> </head> <body> <p align="right"> <a href="index.html">Contents</a> </p> <div class="classhdr"> <table border=0> <tr> <td> <span class="classtag">Class</span> <span class="classname">P4</span> <span class="classparent">< Object</span> </td> <td id="righttext"> <span class="requiretag">require</span> <span class="modulename">"P4"</span> </td> </tr> </table> </div> <h3>Description</h3> Main interface to the Perforce client API. Each P4 object provides you with a thread-safe API level interface to Perforce. The basic model is to: <ol> <li> <a href="#new">Instantiate</a> your P4 object </li> <li> Specify your Perforce client environment <ul> <li><a href="#client-eq">client</a></li> <li><a href="#host-eq">host</a></li> <li><a href="#password-eq">password</a></li> <li><a href="#port-eq">port</a></li> <li><a href="#user-eq">user</a></li> </ul> </li> <li> Set any options to control output or error handling <ul> <li><a href="#exception-level-eq">exception_level</a></li> <li><a href="#parse_forms">parse_forms</a></li> <li><a href="#tagged">tagged</a></li> </ul> </li> <li><a href="#connect">Connect</a> to the Perforce Server</li> <li><a href="#run">Run</a> your Perforce commands</li> <li><a href="#disconnect">Disconnect</a> from the Perforce Server</li> </ol> <div class="classmethods"> <a name="classmethods"></a> <h3>Class Methods</h3> <div class="index"> <a href="#identify">P4.identify</a> <a href="#new">P4.new</a> </div> <a name="identify"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">identify</td> <td class="proto"><i>P4</i>.identify -> <i>aString</i></td> </tr> </table> </div> <br> Return the version of P4/Ruby you are using - for diagnostic purposes. <pre> ruby -rP4 -e 'puts( P4.identify )' </pre> </div> <a name="new"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">new</td> <td class="proto"><i>P4</i>.new -> <i>aP4</i></td> </tr> </table> </div> Constructs a new P4 object. <pre> p4 = P4.new() </pre> </div> </div> <div class="instancemethods"> <h3>Instance Methods</h3> <div class="index"> <table border="0"> <tr> <td> <a href="#at_exception_level">at_exception_level</a> <a href="#api-eq">api=</a> <a href="#charset-eq">charset=</a> <a href="#charset-q">charset?</a> <a href="#client-eq">client=</a> <a href="#client-q">client?</a> <a href="#connect">connect</a> <a href="#cwd-eq">cwd=</a> <a href="#cwd-q">cwd?</a> <a href="#debug-eq">debug=</a> <a href="#delete_">delete_<spec type></a> <a href="#disconnect">disconnect</a> <a href="#errors">errors</a> </td> <td> <a href="#exception_level-eq">exception_level=</a> <a href="#exception_level-q">exception_level?</a> <a href="#fetch_">fetch_<spec type></a> <a href="#format_spec">format_spec</a> <a href="#host-eq">host=</a> <a href="#host-q">host?</a> <a href="#input">input</a> <a href="#maxresults-eq">maxresults=</a> <a href="#maxscanrows-eq">maxscanrows=</a> <a href="#output">output</a> <a href="#parse_forms">parse_forms</a> <a href="#parse_spec">parse_spec</a> <a href="#password-eq">password=</a> </td> <td> <a href="#password-q">password?</a> <a href="#prog-eq">prog=</a> <a href="#port-eq">port=</a> <a href="#port-q">port?</a> <a href="#run">run</a> <a href="#run_filelog">run_filelog</a> <a href="#run_password">run_password</a> <a href="#run_resolve">run_resolve</a> <a href="#save_">save_<spec type></a> <a href="#tagged">tagged</a> <a href="#user-eq">user=</a> <a href="#user-q">user?</a> <a href="#warnings">warnings</a> </td> </tr> </table> </div> <a name="at_exception_level"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">at_exception_level</td> <td class="proto"> <i>p4</i>.at_exception_level( lev ) { ... } -> <i>self</i> </td> </tr> </table> </div> Executes the associated block under a specific exception level. Returns to the previous exception level when the block returns. <pre> p4 = P4.new p4.client = "www" p4.connect p4.at_exception_level( P4::RAISE_ERRORS ) do p4.run_sync end p4.disconnect </pre> </div> <a name="api-eq"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">api=</td> <td class="proto"> <i>p4</i>.api=<i>integer</i> -> <i>self</i> </td> </tr> </table> </div> <p> Sets the API compatibility level desired. This is useful when writing scripts using Perforce commands that do not yet support tagged output. In these cases, upgrading to a later server that supports tagged output for the commands in question can break your script. Using this method allows you to lock your script to the output format of an older Perforce release and facilitate seamless upgrades. Note that this method <b>must</b> be called prior to calling <span class="inlinecode">P4#connect</span>. </p> <p> See the Perforce <a href="http://www.perforce.com/perforce/technical.html#releasenotes">C/C++ API Release Notes</a> for the API integer levels that correspond to each Perforce release. </p> <pre> p4 = P4.new p4.api = 57 # Lock to 2005.1 format p4.connect ... </pre> </div> <a name="charset-eq"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">charset=</td> <td class="proto"> <i>p4</i>.charset = <i>aString</i> -> <i>aBool</i> </td> </tr> </table> </div> Sets the character set to use when connected to a Unicode enabled server. Should not be used when working with non-Unicode-enabled servers. Returns true if the charset was valid and returns false or raises a P4Exception (at exception level P4::RAISE_ERRORS or higher) if the charset is invalid. [Note: some versions of Ruby seem not to honour the boolean return value and return the charset string instead. This appears to be a bug in Ruby] <pre> p4 = P4.new p4.client = "www" p4.charset = "iso8859-1" p4.connect p4.run_sync p4.disconnect </pre> </div> <a name="charset-q"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">charset?</td> <td class="proto"> <i>p4</i>.charset? -> <i>aString</i> </td> </tr> </table> </div> Get the name of the character set in use when working with Unicode-enabled servers. <pre> p4 = P4.new p4.charset = "utf8" p4.charset? </pre> </div> <a name="client-eq"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">client=</td> <td class="proto"> <i>p4</i>.client = <i>aString</i> -> true </td> </tr> </table> </div> Set the name of the clientspec you wish to use. If not called, defaults to the value of P4CLIENT taken from any P4CONFIG file present, or from the environment as per the usual Perforce convention. Must be called before you connect. <pre> p4 = P4.new p4.client = "www" p4.connect p4.run_sync p4.disconnect </pre> </div> <a name="client-q"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">client?</td> <td class="proto"> <i>p4</i>.client? -> <i>aString</i> </td> </tr> </table> </div> Get the name of the Perforce client currently in use <pre> p4 = P4.new puts( p4.client? ) </pre> </div> <a name="connect"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">connect</td> <td class="proto"> <i>p4</i>.connect -> <i>aBool</i> </td> </tr> </table> </div> Connect to the Perforce Server. You must connect before you can execute commands. Raises a P4Exception if the connection attempt fails. <pre> p4 = P4.new p4.connect </pre> </div> <a name="cwd-eq"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">cwd=</td> <td class="proto"> <i>p4</i>.cwd = <i>aString</i> -> true </td> </tr> </table> </div> Sets the current working directory. Can be called prior to executing any Perforce command. Sometimes necessary if your script executes a chdir() as part of its processing. <pre> p4 = P4.new p4.cwd = "/home/tony" </pre> </div> <a name="cwd-q"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">cwd?</td> <td class="proto"> <i>p4</i>.cwd? -> <i>aString</i> </td> </tr> </table> </div> Get the current working directory <pre> p4 = P4.new puts( p4.cwd? ) </pre> </div> <a name="debug-eq"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">debug=</td> <td class="proto"> <i>p4</i>.debug = <i>aNumber</i> -> true </td> </tr> </table> </div> Set debug level. Debug output is written to $stderr. Debug levels are: <div class="itemdesc"> <div>0: No debug output (default)</div> <div>1: Log connect/disconnect and command execution</div> <div>2: Log user interface function callbacks</div> <div>3: Log data</div> <div>4: Log Ruby garbage collection</div> </div> Note that levels are cumulative so level 3 includes levels 2 and 1. <pre> p4 = P4.new p4.debug = 1 p4.connect p4.run_sync p4.disconnect </pre> </div> <a name="delete_"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">delete_<spec type></td> <td class="proto"> <i>p4</i>.delete_<spec type>( [options], name ) -> <i>anArray</i> </td> </tr> </table> </div> The delete_* methods are simply shortcut methods that allow you to quickly delete the definitions of clients, labels, branches, etc. They're equivalent to <span class="inlinecode"> p4.run( <spec type>, '-d', [options], <spec name> ).shift </span> <pre> require "P4" require "parsedate" include ParseDate now = Time.now p4 = P4.new begin p4.connect p4.run_clients.each do |client| atime = parsedate( client[ "AccessDate" ] ) if( (atime + 24 * 3600 * 365 ) < now ) p4.delete_client( '-f', client[ "Client" ] ) end end rescue P4Exception p4.errors.each { |e| puts( e ) } ensure p4.disconnect end </pre> </div> <a name="disconnect"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">disconnect</td> <td class="proto"> <i>p4</i>.disconnect -> true </td> </tr> </table> </div> Disconnect from the Perforce Server. <pre> p4 = P4.new p4.connect p4.disconnect </pre> </div> <a name="errors"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">errors</td> <td class="proto"> <i>p4</i>.errors -> <i>anArray</i> </td> </tr> </table> </div> Returns the array of errors which occurred during execution of the previous command. <pre> p4 = P4.new begin p4.connect p4.exception_level( P4::RAISE_ERRORS ) # to ignore "File(s) up-to-date" p4.run_sync rescue P4Exception p4.errors.each { |e| puts( e ) } ensure files = p4.output p4.disconnect end </pre> </div> <a name="exception_level-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">exception_level=</td> <td class="proto"> <i>p4</i>.exception_level = <i>aLevel</i> -> <i>aNumber</i> </td> </tr> </table> </div> Configures the events which give rise to exceptions. <ul> <li>P4::RAISE_NONE -- disables all exception raising and makes the interface completely procedural. </li> <li>P4::RAISE_ERRORS -- causes exceptions to be raised only when errors are encountered. </li> <li>P4::RAISE_ALL -- causes exceptions to be raised for both errors and warnings. This is the default. </li> </ul> <pre> p4 = P4.new p4.exception_level = P4::RAISE_ERRORS p4.connect # P4Exception on failure p4.run_sync # File(s) up-to-date is a warning so # no exception is raised p4.disconnect </pre> </div> <a name="exception_level-q"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">exception_level?</td> <td class="proto"> <i>p4</i>.exception_level? -> <i>aNumber</i> </td> </tr> </table> </div> Returns the current exception level. </div> <a name="fetch_"></a> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">fetch_<spec type></td> <td class="proto"> <i>p4</i>.fetch_<spec type>( [name] ) -> <i>aHash</i> </td> </tr> </table> </div> The fetch_* methods are simply shortcut methods that allow you to quickly fetch the definitions of clients, labels, branches, etc. They're equivalent to <span class="inlinecode"> p4.run( <spec type>, '-o', ... ).shift </span> <pre> p4 = P4.new begin p4.connect client = p4.fetch_client() other_client = p4.fetch_client( "other" ) label = p4.fetch_label( "somelabel" ) rescue P4Exception p4.errors.each { |e| puts( e ) } ensure p4.disconnect end </pre> </div> <a name="format_spec"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">format_spec</td> <td class="proto"> <i>p4</i>.format_spec( <spec type>, aHash )-> aString </td> </tr> </table> </div> Converts the fields in a hash containing the elements of a Perforce form (spec) into the familiar string reprepresentation that users know and love. <p> Requires <i>parse_forms()</i> mode. <p> The first argument is the type of spec to format: 'client', 'branch', 'label' etc. The second is the hash to parse. <p> Note that there are shortcuts available for this method. <pre> p4.format_<spec type>( hash ) </pre> instead of <pre> p4.format_spec( <spec type>, hash ) </pre> Where <spec type> is 'client'/'branch'/'label' etc. etc. </div> <a name="host-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">host=</td> <td class="proto"> <i>p4</i>.host = <i>aString</i> -> true </td> </tr> </table> </div> Set the name of the current host. If not called, defaults to P4HOST taken from any P4CONFIG file in effect, then P4HOST in the environment and finally the operating system host name. <pre> p4 = P4.new p4.host = "perforce.smee.org" p4.connect ... p4.disconnect </pre> </div> <a name="host-q"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">host?</td> <td class="proto"> <i>p4</i>.host? -> <i>aString</i> </td> </tr> </table> </div> Get the current hostname <pre> p4 = P4.new puts( p4.host? ) </pre> </div> <a name="input"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">input</td> <td class="proto"> <i>p4</i>.input( aString ) -> true or false<br> <i>p4</i>.input( aHash ) -> true or false<br> <i>p4</i>.input( anArray ) -> true or false </td> </tr> </table> </div> Call prior to running a command requiring input from the user. When the command requests input, it's the data supplied here that will be returned. This applies most commonly to commands of the form <span class="inlinecode">"p4 cmd -i"</span>. Note that typically commands of that form are invoked using the <span class="inlinecode"><a href="#save_">P4#save_*</a></span> methods which call <span class="inlinecode">P4#input()</span> internally. So there is no need to call this method when using the <span class="inlinecode">save_*</span> shortcuts. <br><br> You may pass a string, a hash or (for commands that take multiple inputs from the user) an array of strings/hashes. You may only pass hashes when working in <span class="inlinecode">parse_forms</span> mode. If you pass an array, note that the array will be 'shifted' each time Perforce asks the user for input. <pre> p4 = P4.new p4.parse_forms p4.connect change = p4.run_change( "-o" ).shift change[ "Description" ] = "Autosubmitted changelist" p4.input( change ) p4.run_submit( "-i" ) p4.disconnect </pre> Note that <span class="inlinecode">P4#input</span> cannot predict whether or not the supplied input will be acceptable to the next command the user runs so it always returns true - regardless of the validity of the input. </div> <a name="maxresults-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">maxresults=</td> <td class="proto"> <i>p4</i>.maxresults = <i>aNumber</i> -> <i>aNumber</i> </td> </tr> </table> </div> Limit the number of results Perforce will permit for subsequent commands. Commands that produce more than this number of results will be aborted. The limit remains in force until you disable it by setting it to zero. See <span class="inlinecode">p4 help maxresults</span> for information on the commands that support this limit. <pre> p4 = P4.new begin p4.connect p4.maxresults = 100 files = p4.run_sync rescue P4Exception => ex p4.errors.each { |e| $stderr.puts( e ) } ensure p4.disconnect end </pre> </div> <a name="maxscanrows-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">maxscanrows=</td> <td class="proto"> <i>p4</i>.maxscanrows = <i>aNumber</i> -> <i>aNumber</i> </td> </tr> </table> </div> Limit the number of database records Perforce will scan for subsequent commands. Commands that attempt to scan more than this number of records will be aborted. The limit remains in force until you disable it by setting it to zero. See <span class="inlinecode">p4 help maxresults</span> for information on the commands that support this limit. <pre> p4 = P4.new begin p4.connect p4.maxscanrows = 100 files = p4.run_sync rescue P4Exception => ex p4.errors.each { |e| $stderr.puts( e ) } ensure p4.disconnect end </pre> </div> <a name="output"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">output</td> <td class="proto"> <i>p4</i>.output -> <i>anArray</i> </td> </tr> </table> </div> Get the results of the previous command. Returns an array containing the output of the command. Useful in a rescue block when a command has partially worked, and you still need to look at the command output. <pre> p4 = P4.new begin p4.connect p4.exception_level( P4::RAISE_ERRORS ) # to ignore "File(s) up-to-date" files = p4.run_sync rescue P4Exception => ex files = p4.output if files.length puts( "Sync succeeded with errors" ) else puts( "Sync failed!" ) end ensure p4.disconnect end </pre> </div> <a name="parse_forms"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">parse_forms</td> <td class="proto"> <i>p4</i>.parse_forms -> true </td> </tr> </table> </div> Extends the capabilities of tagged output to include Perforce forms. Forms returned by Perforce in response to commands such as "p4 client -o" will be parsed and returned to the caller as a Ruby hash containing keys for each of the fields on the form. Where a form element may contain more than one value, the hash value is an array containing the form elements. <span class="inlinecode">parse_forms</span> implies the use of <span class="inlinecode">tagged</span>. <pre> p4 = P4.new p4.parse_forms p4.connect clientspec = p4.run_client( "-o" ).shift puts( clientspec[ "Options" ] ) p4.disconnect </pre> Such parsed forms are also acceptable as input to commands of the form <span class="inlinecode">"p4 XXXX -i"</span>. For example, to change the root of a clientspec you could use: <pre> p4 = P4.new p4.parse_forms p4.connect spec = p4.run_client( "-o" ).shift spec[ "Root" ] = "/home/my/new/root" p4.input( spec ) p4.run_client( "-i" ) p4.disconnect </pre> </div> <a name="parse_spec"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">parse_spec</td> <td class="proto"> <i>p4</i>.parse_spec( <spec type>, aString )-> aHash </td> </tr> </table> </div> Parses a Perforce form (spec) in text form into a Ruby hash using the spec definition obtained from the server. Requires <i>parse_forms()</i> mode. <p> The first argument is the type of spec to parse: "client", "branch", "label" etc. The second is the raw buffer to parse. <p> Note that there are shortcuts available for this method. <pre> p4.parse_<spec type>( buf ) </pre> instead of <pre> p4.parse_spec( <spec type>, buf ) </pre> Where <spec type> is 'client'/'branch'/'label' etc. etc. </div> <a name="password-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">password=</td> <td class="proto"> <i>p4</i>.password = <i>aString</i> -> true </td> </tr> </table> </div> Set your Perforce password, in plain text. If not used, takes the value of P4PASSWD from any P4CONFIG file in effect, or from the environment according to the normal Perforce conventions. This password will also be used if you later call <span class="inlinecode">p4.run_login</span> to login using the 2003.2 and later ticket system. <pre> p4 = P4.new p4.password = "mypass" p4.connect p4.run_login </pre> </div> <a name="password-q"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">password?</td> <td class="proto"> <i>p4</i>.password? -> <i>aString</i> </td> </tr> </table> </div> Get the current password. This may be the password in plain text, or if you've used <span class="inlinecode">p4.run_login</span>, it'll be the value of the ticket you've been allocated by the server. <pre> p4 = P4.new puts( p4.password? ) </pre> </div> <a name="prog-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">prog=</td> <td class="proto"> <i>p4</i>.prog = <i>aString</i> -> true </td> </tr> </table> </div> Set the name of your 'program'. This value is visible to Perforce system administrators running <span class="inlinecode">'p4 monitor show -e'</span> in Perforce 2004.2 or later releases. <pre> p4 = P4.new p4.prog = "sync-script" p4.connect ... p4.disconnect </pre> </div> <a name="port-eq"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">port=</td> <td class="proto"> <i>p4</i>.port = <i>aString</i> -> true </td> </tr> </table> </div> Set the host and port address of the Perforce server you want to connect to. If not called, defaults to the value of P4PORT in any P4CONFIG file in effect and then to the value of P4PORT taken from the environment. <pre> p4 = P4.new p4.port = "localhost:1666" p4.connect ... p4.disconnect </pre> </div> <a name="port-q"></a> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">port?</td> <td class="proto"> <i>p4</i>.port? -> <i>aString</i> </td> </tr> </table> </div> Get the address of the current Perforce server. <pre> p4 = P4.new puts( p4.port? ) </pre> </div> <a name="run"> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">run</td> <td class="proto"> <i>p4</i>.run( <i>aCommand</i>, <i>arguments...</i> ) -> <i>anArray</i> </td> </tr> </table> </div> Base interface to all the run methods in this API. Runs the specified Perforce command with the arguments supplied. Arguments may be in any form you like as long as it responds nicely to <span class="inlinecode">to_s</span>. <p> If the command succeeds without errors or warnings, then run returns an array of results. Whether the elements of the array are strings or hashes depends on (a) the command executed and (b) whether <span class="inlinecode">tagged()</span> or <span class="inlinecode">parse_forms()</span> have been called. <p> The array that is returned is equivalent to that returned by <span class="inlinecode">p4.output</span>. <p> In the event of errors or warnings, and depending on the exception level in force at the time, run will raise a P4Exception. If the current exception level is below the threshold for the error/warning, then run returns the output as normal and the caller must explicitly review <span class="inlinecode">p4.errors</span> and <span class="inlinecode">p4.warnings</span> to check for errors or warnings. <pre> p4 = P4.new p4.connect spec = p4.run( "client", "-o" ).shift p4.disconnect </pre> Through the magic of Object#method_missing, you can save yourself some typing as <pre> p4.run_XXX( args ) </pre> is translated into <pre> p4.run( "XXX", args ) </pre> There are also some shortcuts for common commands such as editing Perforce forms and submitting. So this: <pre> p4 = P4.new p4.parse_forms p4.connect <b>clientspec = p4.run_client( "-o" ).shift</b> clientspec[ "Description" ] = "Build client" <b>p4.input( clientspec ) p4.run_client( "-i" )</b> p4.disconnect </pre> May be shortened to <pre> p4 = P4.new p4.parse_forms p4.connect <b>clientspec = p4.fetch_client</b> clientspec[ "Description" ] = "Build client" <b>p4.save_client( clientspec )</b> p4.disconnect </pre> In fact, the following are equivalent: <p> <table border=1 cellpadding="10"> <tr> <td>p4.delete_xxx</td> <td>p4.run_xxx( "-d ").shift</td> </tr> <tr> <td>p4.fetch_xxx</td> <td>p4.run_xxx( "-o ").shift</td> </tr> <tr> <td>p4.save_xxx( spec )</td> <td>p4.input( spec )<br> p4.run_xxx( "-i" ).shift </td> </tr> </table> <p> Note that the fetch_xxx methods do not return an array as typically there is only one result item from such commands. Accordingly, they return the first result element. <p> There is also a special shortcut for submitting <pre> p4 = P4.new p4.parse_forms p4.connect spec = p4.fetch_change spec[ "Description" ] = "Automated change" <b>p4.submit_spec( spec )</b> p4.disconnect </pre> </div> <a name="run_filelog"> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">run_filelog</td> <td class="proto"> <i>p4</i>.run_filelog(<i>fileSpec</i>) -> <i>anArray</i> </td> </tr> </table> </div> Runs a <span class="inlinecode">p4 filelog</span> on the fileSpec provided and returns an array of <a href="P4DepotFile.html">P4DepotFile</a> results when executed in tagged mode. The raw output of <span class="inlinecode">p4 filelog</span> in tagged mode is difficult to work with so this method restructures the output into a more user-friendly (and object-oriented) form. <pre> p4 = P4.new p4.parse_forms begin p4.connect p4.run_filelog( "index.html" ).shift.each_revision do |r| r.each_integration do |i| # Do something end end rescue P4Exception p4.errors.each { |e| puts( e ) } ensure p4.disconnect end </pre> </div> <a name="run_password"> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">run_password</td> <td class="proto"> <i>p4</i>.run_password(<i>oldpass</i>, <i>newpass</i>) -> <i>anArray</i> </td> </tr> </table> </div> A thin wrapper to make it easy to change your password. This method is (literally) equivalent to the following code: <pre> p4.input( [ <i>oldpass</i>, <i>newpass</i>, <i>newpass</i> ] ) p4.run( "password" ) </pre> For example: <pre> p4 = P4.new p4.password = "myoldpass" begin p4.connect p4.run_password( "myoldpass", "mynewpass" ) rescue P4Exception p4.errors.each { |e| puts( e ) } ensure p4.disconnect end </pre> </div> <a name="run_resolve"> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">run_resolve</td> <td class="proto"> <i>p4</i>.run_resolve( <i>args</i> ) [ <i>block</i> ] -> <i>anArray</i> </td> </tr> </table> </div> Interface to 'p4 resolve'. Without a block, simply runs a non-interactive resolve - typically an automatic resolve. <pre> p4.run_resolve( "-at" ) </pre> <p> When a block is supplied, the block is invoked once for each merge scheduled by Perforce. For each merge, a <a href="P4MergeData.html">P4::MergeData</a> object is passed to the block. This object contains the context of the merge. </p> <p><b> Note that this interface is evolving and is subject to change in future versions of P4Ruby. </b></p> <p> The block decides the outcome of the merge by evaluating to one of the following strings </p> <ul> <li>"ay" - Accept Yours</li> <li>"at" - Accept Theirs</li> <li>"am" - Accept Merge result</li> <li>"ae" - Accept Edited result</li> <li>"s" - Skip this merge</li> <li>"q" - Abort the merge</li> </ul> <pre> p4.run_resolve() do |md| puts( "Merging..." ) puts( "Yours: #{md.your_name}" ) puts( "Theirs: #{md.their_name}" ) puts( "Base: #{md.base_name}" ) puts( "Yours file: #{md.your_path}" ) puts( "Theirs file: #{md.their_path}" ) puts( "Base file: #{md.base_path}" ) puts( "Result file: #{md.result_path}" ) puts( "Merge Hint: #{md.merge_hint}" ) result = md.merge_hint if( result == "e" && ENV.has_key?( "P4MERGE" ) ) puts( "Invoking external merge application" ) result = "s" # If the merge doesn't work, we'll skip result = "am" if md.run_merge() end result end </pre> </div> <a name="save_"> <div class="method"> <div class="methodheader"> <table> <tr> <td class="meth_name">save_<spec type></td> <td class="proto"> <i>p4</i>.save_<spec type>( [options], <i>hashOrString</i> ) -> <i>anArray</i> </td> </tr> </table> </div> The save_* methods are simply shortcut methods that allow you to quickly update the definitions of clients, labels, branches, etc. They're equivalent to <span class="inlinecode"> p4.run( <spec type>, '-i', [options,] <i>hashOrString</i> ).shift </span> <pre> p4 = P4.new begin p4.connect client = p4.fetch_client() client[ "Owner" ] = p4.user? p4.save_client( client ) rescue P4Exception p4.errors.each { |e| puts( e ) } ensure p4.disconnect end </pre> </div> <a name="tagged"> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">tagged</td> <td class="proto"> <i>p4</i>.tagged -> true </td> </tr> </table> </div> Enables tagged output. Responses to Perforce commands which support tagged output will be converted into Ruby hashes. Must be called before connecting to the server. <pre> p4 = P4.new p4.tagged p4.connect ... p4.disconnect </pre> </div> <a name="user-eq"> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">user=</td> <td class="proto"> <i>p4</i>.user = <i>aString</i> -> true </td> </tr> </table> </div> Set your Perforce username. If not set defaults to the value of P4USER taken from any P4CONFIG file in effect, then the value of P4USER in your environment and lastly your operating system user name. <pre> p4 = P4.new p4.user = "tony" p4.connect ... p4.disconnect </pre> </div> <a name="user-q"> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">user?</td> <td class="proto"> <i>p4</i>.user? -> <i>aString</i> </td> </tr> </table> </div> Returns your current Perforce user name <pre> p4 = P4.new puts( p4.user? ) </pre> </div> <a name="warnings"> <div class="method"> <div class="methodheader"> <table width="100%"> <tr> <td class="meth_name">warnings</td> <td class="proto"> <i>p4</i>.warnings -> <i>anArray</i> </td> </tr> </table> </div> Returns the array of warnings which arose during execution of the last command. <pre> p4 = P4.new begin p4.connect p4.exception_level( P4::RAISE_ALL ) # "File(s) up-to-date" is a warning files = p4.run_sync rescue P4Exception => ex p4.warnings.each { |w| puts( w ) } ensure p4.disconnect end </pre> </div> </div> <h3>See Also</h3> <div class="seealso"> <a href="P4DepotFile.html">P4DepotFile</a> <a href="P4Exception.html">P4Exception</a> <a href="P4Integration.html">P4Integration</a> <a href="P4Revision.html">P4Revision</a> <a href="P4MergeData.html">P4::MergeData</a> <a href="P4Spec.html">P4::Spec</a> </div> </body> </html>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#2 | 14520 | tony |
Replace old P4Ruby documentation with a RELNOTES file, (and ultimately, Doug's new manual), and update the MANIFEST to match (and include the new tests) I've also removed the old installer files as our new installer won't use them. |
||
#1 | 14480 | tony |
Add P4Ruby 1.5944 to main as start-point for the first productized release of P4Ruby |