P4Perl is a Perl module that provides an object-oriented API to the Perforce SCM system. Using P4Perl is faster than using the command-line interface in scripts, because multiple command can be executed on a single connection, and because it returns the Perforce Server's responses as Perl hashes and arrays.
|
•
|
make (or nmake on Windows)
|
Download P4Perl from the Perforce web site downloads page. After downloading, you can either run the installer or build the interface from source, as described in the release notes.
use P4;my $p4 = new P4; $p4->SetClient( $clientname ); $p4->SetPort ( $p4port ); $p4->SetPassword( $p4password ); $p4->Connect() or die( "Failed to connect to Perforce Server" ); my $info = $p4->Run( "info" ); $p4->RunEdit( "file.txt" ); die( "Failed to edit file.txt" ) if $p4->ErrorCount() || $p4->WarningCount; $p4->Disconnect();
|
Each P4 object represents a connection to the Perforce Server, and multiple commands may be executed (serially) over a single connection.
Construct a new P4 object. For example:
Shorthand for running $p4->Run( "spectype", "-o" ) and returning the first element of the result array. For example:
$label = $p4->FetchLabel( $labelname ); $change = $p4->FetchChange( $changeno ); $clientspec = $p4->FetchClient( $clientname );
|
Shorthand for running $p4->FormatSpec( <spectype>, hash ) and returning the results. For example:
$change = $p4->FetchChange(); $change->{ 'Description' } = 'Some description'; $form = $p4->FormatChange( $change ); printf( "Submitting this change:\n\n%s\n", $form ); $p4->RunSubmit( $change );
|
Converts a Perforce form of the specified type (client/label etc.) held in the supplied hash into its string representation. Shortcut methods are available that obviate the need to supply the type argument. The following two examples are equivalent:
Returns the current API compatibility level. Each iteration of the Perforce Server is given a level number. As part of the initial communication, the client protocol level is passed between client application and the Perforce Server. This value, defined in the Perforce API, determines the communication protocol level that the Perforce client will understand. All subsequent responses from the Perforce Server can be tailored to meet the requirements of that client protocol level.
Returns the current Perforce client name. This may have previously been set by SetClient(), or may be taken from the environment or
P4CONFIG file if any. If all that fails, it will be your hostname.
Get the current maxlocktime setting.
Get the current maxresults setting.
Get the current maxscanrows setting.
Returns your Perforce password. Taken from a previous call to SetPassword() or extracted from the environment (
$ENV{P4PASSWD}), or a
P4CONFIG file.
Shorthand for running $p4-ParseSpec( <spectype>, buffer ) and returning the results. For example:
$p4 = new P4;$p4->Connect() or die( "Failed to connect to server" ); $client = $p4->FetchClient(); # Returns a hashref $client = $p4->FormatClient( $client ); # Convert to string $client = $p4->ParseClient( $client ); # Convert back to hashref
|
Converts a Perforce form of the specified type (client/label etc.) held in the supplied string into a hash and returns a reference to that hash. Shortcut methods are available to avoid the need to supply the type argument. The following two examples are equivalent:
Shorthand for running $p4-Run (cmd, arg, ...) and returning the results.
Run a Perforce command and return its results. Because Perforce commands can partially succeed and partially fail, it is good practice to check for errors using
P4::ErrorCount().
Note that the content of the array of results you get depends on (a) whether you're using tagged mode, (b) the command you've executed, (c) the arguments you supplied, and (d) your Perforce server version.
In non-tagged mode, each result element is a string. In this case, because the Perforce server sometimes asks the client to write a blank line between result elements, some of these result elements can be empty.
Pay attention to the calls to client-FstatInfo(),
client-OutputText(),
client-OutputData() and
client-HandleError(). Each call to one of these functions results in either a result element, or an error element.
Runs a p4 filelog on the
fileSpec provided and returns an array of
P4::DepotFile objects when executed in tagged mode.
Runs p4 login using a password (or other arguments) set by the user.
A thin wrapper for changing your password from $oldpass to
$newpass. Not to be confused with
P4::SetPassword.
Run a p4 resolve command. Interactive resolves require the
$resolver parameter to be an object of a class derived from
P4::Resolver. In these cases, the
Resolve() method of this class is called to handle the resolve. For example:
# "s"kip if server-recommended hint is to "e"dit the file, # because such a recommendation implies the existence of a conflict return "s" if( $mergeData->Hint() eq "e" ); return $mergeData->Hint(); } 1;
|
In non-interactive resolves, no P4::Resolver object is required. For example:
Returns an integer specifying the server protocol level. This is not the same as, but is closely aligned to, the server version. To find out your server's protocol level, run
p4 -vrpc=5 info and look for the
server2 protocol variable in the output. For more information, see:
Specify the API compatibility level to use for this script. This is useful when you want your script to continue to work on newer server versions, even if the new server adds tagged output to previously unsupported commands.
The additional tagged output support can change the server's output, and confound your scripts. Setting the API level to a specific value allows you to lock the output to an older format, thus increasing the compatibility of your script.
Specify the character set to use for local files when used with a Perforce server running in unicode mode. Do not use unless your Perforce server is in unicode mode. Must be called before calling
P4::Connect(). For example:
Sets the name of the client host, overriding the actual hostname. This is equivalent to p4 -H hostname, and only useful when you want to run commands as if you were on another machine.
Save the supplied argument as input to be supplied to a subsequent command. The input may be a hashref, a scalar string, or an array of hashrefs or scalar strings. If you pass an array, the array will be shifted once each time the Perforce command being executed asks for user input.
Limit the amount of time (in milliseconds) spent during data scans to prevent the server from locking tables for too long. Commands that take longer than the limit will be aborted. The limit remains in force until you disable it by setting it to zero. See
p4 help maxresults for information on the commands that support this limit.
Limit the number of results for subsequent commands to the value specified. Perforce will abort the command if continuing would produce more than this number of results. Once set, this limit remains in force unless you remove the restriction by setting it to a value of 0.
Limit the number of records Perforce will scan when processing subsequent commands to the value specified. Perforce will abort the command once this number of records has been scanned. Once set, this limit remains in force unless you remove the restriction by setting it to a value of 0.
Set the path to the current P4TICKETS file (and return it).
By default, tagged output is enabled, but can be disabled (or re-enabled) by calling this method. If you provide a code reference, you can run a subroutine with the tagged status toggled for the duration of that reference. For example:
When running in tagged mode, responses from commands that support tagged output will be returned in the form of a hashref. When running in non-tagged mode, responses from commands are returned in the form of strings (that is, in plain text).
P4::DepotFile objects are used to present information about files in the Perforce repository. They are returned by
P4::RunFilelog.
Returns an array of P4::Revision objects, one for each revision of the depot file
P4::Revision objects are represent individual revisions of files in the Perforce repository. They are returned as part of the output of
P4::RunFilelog.
Returns an array of P4::Integration objects representing all integration records for this revision.
Returns the description of the change which created this revision. Note that only the first 31 characters are returned unless you use
p4 filelog -L for the first 250 characters, or
p4 filelog -l for the full text.
P4::Integration objects represent Perforce integration records. They are returned as part of the output of
P4::RunFilelog.
The P4::Map class allows users to create and work with Perforce mappings, without requiring a connection to a Perforce server.
Constructs a new P4::Map object.
Join two P4::Map objects and create a third.
May be called with one or two arguments. If called with one argument, the string is assumed to be a string containing either a half-map, or a string containing both halves of the mapping. In this form, mappings with embedded spaces must be quoted. If called with two arguments, each argument is assumed to be half of the mapping, and quotes are optional.
Translate a string through a map, and return the result. If the optional second argument is 1, translate forward, and if it is 0, translate in the reverse direction. By default, translation is in the forward direction.
Return a new P4::Map object with the left and right sides of the mapping swapped. The original object is unchanged.
Class containing the context for an individual merge during execution of a p4 resolve. Users may not create objects of this class; they are created internally during
P4::RunResolve(), and passed down to the
Resolve() method of a
P4::Resolver subclass.
Returns the path to the merge result. This is typically a path to a temporary file on your local machine in which the contents of the automatic merge performed by the server have been loaded.
If the environment variable P4MERGE is defined,
RunMergeTool() invokes the specified program and returns true if the merge tool was successfully executed, otherwise returns false.
P4::Resolver is a class for handling resolves in Perforce. It is intended to be subclassed, and for subclasses to override the
Resolve() method. When
P4::RunResolve() is called with a P4::Resolver object, it calls the
Resolve() method of the object once for each scheduled resolve.
By default, all automatic merges are accepted, and all merges with conflicts are skipped. The
Resolve() method is called with a single parameter, which is a reference to a
P4::MergeData object.
P4::Spec objects are used to present information about files in the Perforce repository.
The P4::Spec class uses Perl's AutoLoader to simplify form manipulation. Form fields can be accessed by calling a method with the same name as the field prefixed by an underscore (
_).
Constructs a new P4::Spec object for a form containing the specified fields. (The object also contains a
_fields_ member that stores a list of field names that are valid in forms of this type.)
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 want to.
Copyright 2008-2009 Perforce Software.
