P4Spec.html #1 

<html>
<head>
  <title>P4/Ruby - P4::Spec</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::Spec</span>
	  <span class="classparent">&lt; Hash</span>
	</td>
	<td id="righttext">
	  <span class="requiretag">require</span>
	  <span class="modulename">"P4"</span>
	</td>
      </tr>
    </table>
  </div>
  <div class="classhdr">
  </div>

  <h3>Description</h3>

  The P4::Spec class is a hash containing key/value pairs for all the
  fields in a Perforce form. It provides two things over and above its
  parent class (Hash):

  <ul>
    <li>
      Fieldname validation. Only valid field names may be set in a 
      P4::Spec object. Note that only the field name is validated, not
      the content.
    </li>
    <li>
      Accessor methods for easy access to the fields
    </li>
  </ul>


  <div class="classmethods">
    <h3>Class Methods</h3>


    <div class="index">
      <table border="0">
	<tr>
	  <td>
	    <a href="#new">new</a>
	  </td>
	</tr>
      </table>
    </div>


    <a name="new"></a>
    <div class="method">
      <div class="methodheader">
	<table width="100%">
	  <tr>
	    <td class="meth_name">new</td>
	    <td>&nbsp;</td>
	    <td class="proto">
	      P4::Spec.new( <i>anArray</i> ) -&gt; <i>aP4::Spec</i>
	    </td>
	  </tr>
	</table>
      </div>

      Constructs a new P4::Spec object given an array of valid fieldnames.

    </div>
  </div>

  <div class="instancemethods">

    <h3>Instance Methods</h3>

    <div class="index">
      <table border="0">
	<tr>
	  <td>
	    <a href="#getters">_&lt;fieldname&gt;</a>
	  </td>
	  <td>
	    <a href="#setters">_&lt;fieldname&gt;=</a>
	  </td>
	  <td>
	    <a href="#permitted_fields">permitted_fields</a>
	  </td>
	</tr>
      </table>
    </div>


    <a name="getters"></a>
    <div class="method">
      <div class="methodheader">
	<table width="100%">
	  <tr>
	    <td class="meth_name">_&lt;fieldname&gt;</td>
	    <td>&nbsp;</td>
	    <td class="proto">
	      <i>spec</i>._&lt;fieldname&gt; -&gt; <i>aValue</i>
	    </td>
	  </tr>
	</table>
      </div>

      Returns the value associated with the field named &lt;fieldname&gt;.
      This is equivalent to 
      <span class="inlinecode">spec[ "&lt;fieldname&gt;" ]</span> with the
      exception that when used as a method, the fieldnames may be in 
      lowercase regardless of the actual case of the fieldname.

      <pre>
    client = p4.fetch_client()
    root   = client._root
    desc   = client._description
      </pre>
    </div>

    <a name="setters"></a>
    <div class="method">
      <div class="methodheader">
	<table width="100%">
	  <tr>
	    <td class="meth_name">_&lt;fieldname&gt;=</td>
	    <td>&nbsp;</td>
	    <td class="proto">
	      <i>spec</i>._&lt;fieldname&gt;= aValue -&gt; <i>aValue</i>
	    </td>
	  </tr>
	</table>
      </div>

      Updates the value of the named field in the spec. Raises a P4Exception
      if the fieldname is not valid for specs of this type.

      <pre>
    client = p4.fetch_client()

    client._root         = "/home/tony/new-client"
    client._description  = "My new client spec"

    p4.save_client( client )
      </pre>
    </div>

    <a name="permitted_fields"></a>
    <div class="method">
      <div class="methodheader">
	<table width="100%">
	  <tr>
	    <td class="meth_name">permitted_fields</td>
	    <td>&nbsp;</td>
	    <td class="proto">
	      <i>spec</i>.permitted_fields -&gt; <i>anArray</i>
	    </td>
	  </tr>
	</table>
      </div>

      Returns an array containing the names of fields that are valid in 
      this spec object. This does not imply that values for all of these 
      fields are actually set in this object, merely that you may choose to 
      set values for any of these fields if you wish to.
    </div>

  <div class="seealso">
    <h3>See Also</h3>

    <a href="P4.html">P4</a>
    <a href="P4Exception.html">P4Exception</a>
    <a href="P4DepotFile.html">P4DepotFile</a>
    <a href="P4Integration.html">P4Integration</a>
    <a href="P4Revision.html">P4Revision</a>
  </div>

</body>
</html>
# Change User Description Committed
#1 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.
//guest/tony_smith/perforce/API/Ruby/main/doc/P4Revision.html
#5 4653 Tony Smith More documentation tweaks.
Just makes the pages look more
like the reference pages in the 'Pickaxe book'
#4 4652 Tony Smith Doc update for P4Ruby.
Rework the html and the CSS to make the
docs a little easier on the eye and easier to use too.
#3 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.
#2 2426 Tony Smith Doc beautifying for P4Ruby.
#1 2392 Tony Smith Add missing documentation file