P4Perl is a Perl module that provides an object-oriented API to the Perforce version management 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)
|
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();
|
Scripts written with P4Perl use any existing P4TRUST file present in their operating environment (by default,
.p4trust in the home directory of the user that runs the script).
If the fingerprint returned by the server fails to match the one installed in the P4TRUST file associated with the script's run-time environment, your script will (and should!) fail to connect to the server.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns an array of P4::Integration objects representing all integration records for this revision.
|
|
|
|
|
|
|
|
|
|
|
|
|
This module provides an object-oriented interface to the Perforce version management system. Data is returned in Perl arrays and hashes and input can also be supplied in these formats.
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:
The constants OS,
PATCHLEVEL and
VERSION are also available to test an installation of P4Perl without having to parse the output of
P4::Identify(). Also reports the version of the OpenSSL library used for building the underlying Perforce C++ API with which P4Perl was built.
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.
Returns the value of a Perforce environment variable, taking into account the settings of Perforce variables in
P4CONFIG files, and, on Windows or OS X, in the registry or user preferences.
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.
Valid spectypes are
clients,
labels,
branches,
changes,
streams,
jobs,
users,
groups,
depots and
servers. Valid arguments are any arguments that would be valid for the corresponding
run_cmd command.
my $p4 = P4->new;$p4->Connect or die "Couldn't connect"; my $i = $p4->IterateClients(); while($i->hasNext) { my $spec = $i->next; print( "Client: " . ($spec->{Client} or "<undef>") . "\n" ); }
|
Returns an array of P4::Message() objects, one for each message (info, warning or error) sent by the server.
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 ticket 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:
On Windows or OS X, set a variable in the registry or user preferences. To unset a variable, pass an empty string as the second argument. On other platforms, an exception is raised.
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.
Enable or disable support for streams. By default, streams support is enabled at 2011.1 or higher (
GetApiLevel() >= 70). Streams support requires a server at 2011.1 or higher. You can enable or disable support for streams both before and after connecting to the server.
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).
If performance tracking is enabled with P4::SetTrack(), returns a list of strings corresponding to the performance tracking output of the most recently-executed command.
Returns a list of warning strings from the last command
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::Message objects contain error or other diagnostic messages from the Perforce Server; they are returned by
P4::Messages().
Script writers can test the severity of the messages in order to determine if the server message consisted of command output (
E_INFO), warnings, (
E_WARN), or errors (
E_FAILED/
E_FATAL).
The P4::OutputHandler class provides access to streaming output from the server. After defining the output handler, call
SetHandler() with your implementation of
P4::OutputHandler.
Because P4Perl does not provide a template or superclass, your output handler must implement all five of the following methods:
OutputMessage(),
OutputText(),
OutputInfo(),
OutputBinary(), and
OutputStat(), even if the implementation consists of trivially returning
0 (report only: don't handle output, don't cancel operation).
The P4::Progress provides access to progress indicators from the server. After defining the progress class, call
SetProgress() with your implementation of
P4::Progress.
Because P4Perl does not provide a template or superclass, you must implement all five of the following methods:
Init(),
Description(),
Update(),
Total(), and
Done(), even if the implementation consists of trivially returning
0.
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 provide easy access to the attributes of the fields in a Perforce form.
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-2014 Perforce Software.
