<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>Class: P4Trigger</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <link rel=StyleSheet href=".././rdoc-style.css" type="text/css" media="screen" /> <script type="text/javascript" language="JavaScript"> <!-- function popCode(url) { window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400") } //--> </script> </head> <body bgcolor="white"> <table summary="Information on class" width="100%" border="0" cellspacing="0"> <tr class="title-row"> <td class="big-title-font"> <sup><font color="aqua">Class</font></sup> P4Trigger </td> <td align="right"> <table summary="layout" cellspacing="0" cellpadding="2"> <tr valign="top"> <td class="small-title-font">In:</td> <td class="small-title-font"> <a href="../files/P4Triggers_rb.html" class="aqua"> P4Triggers.rb </a> <br /> </td> </tr> <tr> <td class="small-title-font">Parent:</td> <td class="small-title-font"> Object </td> </tr> </table> </td> </tr> </table> <!-- banner header --> <div class="description"><p> A class providing a generic framework for all triggers. It provides rudimentary error handling so all errors get logged to stderr, and we also have a method for reporting a more friendly message to the user. It is intended that all trigger scripts will derive their own subclass of <a href="P4Trigger.html">P4Trigger</a> and override/expand it as necessary. </p> <p> You must override the validate() method if you want your trigger to work. The default implementation accepts <b>everything</b> so make sure you provide a method to reject bad changes or you will have accomplished nothing. </p> </div> <table summary="Methods" cellpadding="5" width="100%"> <tr><td class="tablesubtitle">Methods</td></tr> </table> <div class="name-list"> <a href="#M000025">error_message</a> <a href="#M000022">get_change</a> <a href="#M000024">message</a> <a href="#M000020">new</a> <a href="#M000021">parse_change</a> <a href="#M000023">validate</a> </div> <table summary="Attributes" cellpadding="5" width="100%"> <tr><td class="tablesubtitle">Attributes</td></tr> </table> <table summary="Attribute details" cellspacing="5"> <tr valign="top"> <td class="attr-name">change</td> <td align="center" class="attr-rw"> [R] </td> <td><p> Direct access to the changelist in question. Returns a <a href="P4Change.html">P4Change</a> object </p> </td> </tr> <tr valign="top"> <td class="attr-name">p4</td> <td align="center" class="attr-rw"> [R] </td> <td><p> Direct access to the <a href="P4.html">P4</a> object. You can use this for interrogating the Perforce server. It’s in parse_forms() mode and has an exception_level of 1 so exceptions will only be raised on errors, not warnings. </p> </td> </tr> </table> <table summary="Method list" cellpadding="5" width="100%"> <tr><td class="tablesubtitle">Public Class methods</td></tr> </table> <table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0"> <tr><td class="methodtitle"> <a name="M000020"></a> <b>new</b>() </td></tr> </table> <div class="description"> <p> Constructor. </p> </div> <pre class="source"> <span class="cmt"># File P4Triggers.rb, line 159</span> <span class="kw">def</span> initialize @change = <span class="kw">nil</span> @p4 = P4.new @p4.parse_forms @p4.exception_level = 1 <span class="kw">begin</span> @p4.connect <span class="kw">rescue</span> P4Exception error_message() raise <span class="kw">end</span> <span class="kw">end</span> </pre> <table summary="Method list" cellpadding="5" width="100%"> <tr><td class="tablesubtitle">Public Instance methods</td></tr> </table> <table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0"> <tr><td class="methodtitle"> <a name="M000021"></a> <b>parse_change</b>( change_no ) </td></tr> </table> <div class="description"> <p> The main execution phase of the trigger. We assume since this is a pre-submit trigger that there will be a changelist involved. The steps for most triggers are common: </p> <ol> <li>Find out about the changelist </li> <li>Enforce the rules </li> </ol> <p> We try to generalise this process so this class calls <a href="P4Trigger.html#M000022">get_change</a>() for step 1, and validate() for step 2. Subclasses may override these methods to tailor the trigger’s behaviour </p> <p> <a href="P4Trigger.html#M000021">parse_change</a>() returns the correct exit status for the trigger so you would normally use it like this: </p> <pre> exit( trig.parse_change( change_no ) ) </pre> </div> <pre class="source"> <span class="cmt"># File P4Triggers.rb, line 197</span> <span class="kw">def</span> parse_change( change_no ) <span class="kw">begin</span> <span class="kw">if</span> ( ! change_no ) raise( <span class="str">"No changelist number supplied to trigger script.\n"</span> + <span class="str">"Please check your trigger configuration."</span> ) <span class="kw">end</span> get_change( change_no ) <span class="kw">return</span> ( validate() ? 0 : 1 ) <span class="kw">rescue</span> <span class="cmt"># Report errors to stderr, so they go into the Perforce server's</span> <span class="cmt"># logfile and report a simpler message to stdout</span> $stderr.puts( <span class="str">"\nError during trigger execution:\n\n"</span> ) <span class="kw">if</span> ( $!.kind_of?( P4Exception ) ) p4.errors.each { |e| $stderr.puts( e ) } <span class="kw">else</span> $stderr.puts( $!.to_s ) <span class="kw">end</span> $stderr.puts( <span class="str">"\nStack Trace:\n"</span> ) $stderr.puts( $!.backtrace ) $stdout.puts( error_message() ) <span class="cmt"># Now we return false to the caller so they can return with </span> <span class="cmt"># the correct exit status</span> <span class="kw">return</span> 1 <span class="kw">end</span> <span class="kw">end</span> </pre> <table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0"> <tr><td class="methodtitle"> <a name="M000022"></a> <b>get_change</b>( change_no ) </td></tr> </table> <div class="description"> <p> The default implementation of <a href="P4Trigger.html#M000022">get_change</a>. Returns a hash describing the change based on an execution of "p4 describe -s". The hash is also saved in the @change member which subclasses may access in their validate() method. For most triggers this will be sufficient. </p> </div> <pre class="source"> <span class="cmt"># File P4Triggers.rb, line 229</span> <span class="kw">def</span> get_change( change_no ) @change = p4.run_describe( <span class="str">"-s"</span>, change_no ) <span class="kw">end</span> </pre> <table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0"> <tr><td class="methodtitle"> <a name="M000023"></a> <b>validate</b>() </td></tr> </table> <div class="description"> <p> The default implementation of validate(). Very simple, it accepts everything. You are expected to override this method with one of your own. When you do so, you can use the @change member to get at the details of the change you’re validating. </p> </div> <pre class="source"> <span class="cmt"># File P4Triggers.rb, line 237</span> <span class="kw">def</span> validate() <span class="kw">true</span> <span class="kw">end</span> </pre> <table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0"> <tr><td class="methodtitle"> <a name="M000024"></a> <b>message</b>( string ) </td></tr> </table> <div class="description"> <p> Method to send a message to the user. Just writes to stdout, but it’s nice to encapsulate that here. </p> </div> <pre class="source"> <span class="cmt"># File P4Triggers.rb, line 245</span> <span class="kw">def</span> message( string ) $stdout.print( string ) <span class="kw">end</span> </pre> <table summary="method" width="100%" cellspacing="0" cellpadding="5" border="0"> <tr><td class="methodtitle"> <a name="M000025"></a> <b>error_message</b>() </td></tr> </table> <div class="description"> <p> Default message for when things go wrong </p> </div> <pre class="source"> <span class="cmt"># File P4Triggers.rb, line 250</span> <span class="kw">def</span> error_message() <span class="str">"An error was encountered during trigger execution. Please\n"</span> + <span class="str">"contact your Perforce administrator and ask them to\n"</span> + <span class="str">"investigate the cause of this error\n"</span> <span class="kw">end</span> </pre> </body> </html>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#3 | 4654 | Tony Smith |
Add an example spec trigger to show how you might restrict the default view for all new clients to a pre-defined set of mappings. |
||
#2 | 4640 | Tony Smith |
Add a sample post-commit trigger that can be used to keep a master and slave branch in sync. |
||
#1 | 3637 | Tony Smith | Add RDoc documentation to the sample triggers. |