Class P4Trigger
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. 

# 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
Public Instance methods
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 ) )

# 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
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. 

# File P4Triggers.rb, line 229
    def get_change( change_no )
        @change = p4.run_describe( "-s", change_no )
    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. 

# File P4Triggers.rb, line 237
    def validate()
        true
    end
message( string )

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
error_message()

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