P4Trigger (Class)

In: P4Triggers.rb
Parent: Object

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 P4Trigger and override/expand it as necessary.

You must override the validate() method if you want your trigger to work. The default implementation accepts everything so make sure you provide a method to reject bad changes or you will have accomplished nothing.

Methods

error_message   get_change   message   new   parse_change   validate  

Attributes

change  [R]  Direct access to the changelist in question. Returns a P4Change object
p4  [R]  Direct access to the P4 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.

Public Class methods

new()

Constructor.

[Source]

     # File P4Triggers.rb, line 159
159:     def initialize
160:         @change = nil
161:         @p4 = P4.new
162:         @p4.parse_forms
163:         begin
164:             @p4.connect
165:         rescue P4Exception
166:             error_message()
167:             raise
168:         end
169:     end

Public Instance methods

error_message()

Default message for when things go wrong

[Source]

     # File P4Triggers.rb, line 257
257:     def error_message()
258:         "\n"                                                           +
259:         "An error was encountered during trigger execution. Please\n"  +
260:         "contact your Perforce administrator and ask them to\n"        +
261:         "investigate the cause of this error\n\n"
262:     end
get_change( change_no )

The default implementation of get_change. 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.

[Source]

     # File P4Triggers.rb, line 236
236:     def get_change( change_no )
237:         @change = p4.run_describe( "-s", change_no )
238:     end
message( string )

Method to send a message to the user. Just writes to stdout, but it’s nice to encapsulate that here.

[Source]

     # File P4Triggers.rb, line 252
252:     def message( string )
253:         $stdout.print( string )
254:     end
parse_change( change_no )

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:

  1. Find out about the changelist
  2. Enforce the rules

We try to generalise this process so this class calls get_change() for step 1, and validate() for step 2. Subclasses may override these methods to tailor the trigger’s behaviour

parse_change() returns the correct exit status for the trigger so you would normally use it like this: 

   exit( trig.parse_change( change_no ) )

[Source]

     # File P4Triggers.rb, line 196
196:     def parse_change( change_no )
197:         begin
198:             if ( ! change_no )
199:                 raise(        "No changelist number supplied to trigger script.\n" +
200:                         "Please check your trigger configuration."
201:                      )
202:             end
203:             get_change( change_no )
204:             return ( validate() ? 0 : 1 )
205:         rescue 
206:             # Full error report to stderr, so they go into the Perforce server's
207:             # logfile 
208:             $stderr.puts( "\nError during trigger execution:\n\n" )
209:             if ( $!.kind_of?( P4Exception ) )
210:                 p4.warnings.each { |w| $stderr.puts( "WARNING: " + w ) }
211:                 p4.errors.each   { |e| $stderr.puts( "ERROR: "   + e ) }
212:             else
213:                 $stderr.puts( $!.to_s )
214:             end
215:             $stderr.puts( "\nStack Trace:\n" )
216:             $stderr.puts( $!.backtrace )
217: 
218:             #
219:             # Simpler error report (sans-stack backtrace) to stdout.
220:             #
221:             $stdout.puts( error_message() )
222:             p4.warnings.each { |w| $stdout.puts( "WARNING: " + w ) }
223:             p4.errors.each   { |e| $stdeoutrr.puts( "ERROR: "   + e ) }
224: 
225: 
226:             # Now we return false to the caller so they can return with 
227:             # the correct exit status
228:             return 1
229:         end
230:     end
validate()

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.

[Source]

     # File P4Triggers.rb, line 244
244:     def validate()
245:         true
246:     end

[Validate]