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.
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.
|
# File P4Triggers.rb, line 159
def initialize
@change = nil
@p4 = P4.new
@p4.parse_forms
@p4.exception_level = 1
begin
@p4.connect
rescue P4Exception
error_message()
raise
end
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:
- Find out about the changelist
- 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 ) )
# File P4Triggers.rb, line 197
def parse_change( change_no )
begin
if ( ! change_no )
raise( "No changelist number supplied to trigger script.\n" +
"Please check your trigger configuration."
)
end
get_change( change_no )
return ( validate() ? 0 : 1 )
rescue
# Report errors to stderr, so they go into the Perforce server's
# logfile and report a simpler message to stdout
$stderr.puts( "\nError during trigger execution:\n\n" )
if ( $!.kind_of?( P4Exception ) )
p4.errors.each { |e| $stderr.puts( e ) }
else
$stderr.puts( $!.to_s )
end
$stderr.puts( "\nStack Trace:\n" )
$stderr.puts( $!.backtrace )
$stdout.puts( error_message() )
# Now we return false to the caller so they can return with
# the correct exit status
return 1
end
end
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.
# File P4Triggers.rb, line 229
def get_change( change_no )
@change = p4.run_describe( "-s", change_no )
end
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.
# File P4Triggers.rb, line 237
def validate()
true
end
Method to send a message to the user. Just writes to stdout, but it’s
nice to encapsulate that here.
# File P4Triggers.rb, line 245
def message( string )
$stdout.print( string )
end
Default message for when things go wrong
# File P4Triggers.rb, line 250
def error_message()
"An error was encountered during trigger execution. Please\n" +
"contact your Perforce administrator and ask them to\n" +
"investigate the cause of this error\n"
end