index.html #9

  • //
  • guest/
  • tony_smith/
  • perforce/
  • API/
  • Ruby/
  • main/
  • doc/
  • index.html
  • View
  • Commits
  • Open Download .zip Download (6 KB)
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
  <title>P4Ruby</title>
  <link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>
<body>
  <h2>P4Ruby - Programmers Guide</h2>

  <div>
    <a name="_toc"></a>
    <h3>Contents</h3>

    <div class="index">
      <a href="#intro">Introduction</a>
      <a href="#features">Features at a glance</a>
      <a href="#classes">Classes Defined</a>
      <a href="#support">Support</a>
      <a href="#requirements">Requirements</a>
    </div>
  </div>

  <div>
    <a name="intro"></a>
    <h3>Introduction</h3>

    <div class="indent">
      <p>
	P4Ruby is an extension to the <a href="http://www.ruby-lang.org">Ruby</a>
	programming language that allows you to run Perforce commands from 
	within Ruby scripts, and get the results in a Ruby-friendly format.
      </p>
      <p>
	P4Ruby is designed to work in a Ruby-like way as far as possible. It has
	support for Ruby exceptions to make error handling as easy as possible and
	even distinguishes between errors and warnings - allowing you to ignore
	warnings whilst still trapping errors. 
      </p>
      <p>
        If you're new to P4Ruby, the best place to start is with the 
	documentation for the 
	<a href="P4.html">P4 class</a>. This is the main Ruby class defined
	by P4Ruby.
      </p>
    </div>
  </div>

  <div>
    <a name="features"></a>
    <h3>Features at a glance</h3>

    <div>
      <ul>
	<li>
	  Connect once and run several commands.
	</li>
	<li>
	  The output of commands is returned as a Ruby array.
	</li>
	<li>
	  The elements of the array returned are strings or, where appropriate,
	  Ruby hashes.
	</li>
	<li>
	  Tagged mode output (i.e. 'p4 fstat' or 'p4 -Ztag changes') is 
	  returned as a Ruby hash. See 
	  <a href="P4.html#tagged">P4#tagged</a>.
	</li>
	<li>
	  Optionally converts all Perforce forms (changes/clients/labels etc.)
	  into Ruby hashes and back again. This allows you to fetch the 
	  existing definition of an object, alter one or more fields in the hash
	  and use the modified hash to update Perforce. See
	  <a href="P4.html#parse_forms">P4#parse_forms</a>.
	</li>
	<li>
	  Thread-safe and thread-friendly - have multiple instances of
	  the P4 class running in different threads.
	</li>
	<li>
	  Exception-based error handling. Trap P4Exceptions for complete,
	  high-level error handling.
	</li>
	<li>
	  Connect once and run several commands
	</li>
      </ul>
    </div>
  </div>

  <div>
    <a name="classes"></a>
    <h3>Classes Defined</h3>

    <div>
      <ul>
	<li>
	  <a href="P4.html">P4</a>
	  <div class="itemdesc">
	    The main class used for executing Perforce commands. Almost
	    everything you do with P4Ruby will involve this class. If you're
	    new to P4Ruby, start here.
	  </div>
	</li>
	<li>
	  <a href="P4DepotFile.html">P4DepotFile</a>
	  <div class="itemdesc">
	    Utility class allowing quick and easy access to the attributes
	    of a file in the depot. 
	    Returned by <span class="inlinecode">P4#run_filelog</span>.
	  </div>
	</li>
	<li>
	  <a href="P4Exception.html">P4Exception</a>
	  <div class="itemdesc">
	    Used as part of error reporting and is derived from the Ruby 
	    <b>RuntimeError</b> class. 
	  </div>
	</li>
	<li>
	  <a href="P4Integration.html">P4Integration</a>
	  <div class="itemdesc">
	    Utility class allowing quick and easy access to the attributes
	    of an integration record for a revision of a file in the depot.
	    Returned by <span class="inlinecode">P4#run_filelog</span>.
	  </div>
	</li>
	<li>
	  <a href="P4Revision.html">P4Revision</a>
	  <div class="itemdesc">
	    Utility class allowing quick and easy access to the attributes
	    of a revision of a file in the depot. 
	    Returned by <span class="inlinecode">P4#run_filelog</span>.
	  </div>
	</li>
	<li>
	  <a href="P4MergeData.html">P4::MergeData</a>
	  <div class="itemdesc">
	    Class encapsulating the context of an individual merge during
	    execution of a 'p4 resolve'. Passed as a parameter to the 
	    block passed to P4#run_resolve.
	  </div>
	</li>
	<li>
	  <a href="P4Spec.html">P4::Spec</a>
	  <div class="itemdesc">
	    Subclass of hash allowing quick and easy access to the fields
	    in a Perforce form (spec). Also checks that the fields that
	    are set are valid fields for the given type of spec.
	    Returned by 
	    <span class="inlinecode">P4#fetch_&lt;spec_type&gt;</span>.
	  </div>
	</li>
      </ul>
    </div>
  </div>

  <div>
    <a name="support"></a>
    <h3>Support</h3>

    <div class="indent">
      <p>
	Sign up to the 
	<a href="http://maillist.perforce.com/mailman/listinfo/p4ruby">p4ruby mailing list</a> 
	and post your question to the list. Alternatively, you can 
	contact the author <a href="mailto:tony@smee.org">Tony Smith</a> directly 
	for support. I'll respond as quickly as I'm able. All feedback and 
	suggestions are most welcome.
      </p>
    </div>
  </div>

  <div>
    <a name="requirements"></a>
    <h3>Requirements</h3>

    <div class="indent">
      <p>
	Building P4Ruby requires version 2001.1 or later of the Perforce API and
	a C++ compiler - ideally the same C++ compiler used to build the Perforce 
	API.
      </p>

      <p>
	Running P4Ruby requires a 99.2 or later Perforce server to be of any
	real use to you. Earlier servers did not support tagged output in the 
	same way.
      </p>
      <p>
	The more recent your server, the better as tagged output support is
	continually being improved.
      </p>
    </div>
  </div>
</body>
</html>
# Change User Description Committed
#9 5791 Tony Smith Add experimental support for passing a block to P4#run_resolve.
The
block is passed a P4::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.
#8 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.
#7 4675 Tony Smith A little doc tweaking.
The docs frontpage for P4Ruby now looks a
little more appealing and has an improved structure.
#6 4660 Tony Smith Some doc tidying.
#5 4653 Tony Smith More documentation tweaks.
Just makes the pages look more
like the reference pages in the 'Pickaxe book'
#4 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.
#3 2426 Tony Smith Doc beautifying for P4Ruby.
#2 1411 Tony Smith Document API version requirements for P4/Ruby
#1 1324 Tony Smith P4/Ruby documentation update.
Changed doc layout and added
in docs for newly added methods and classes.