Main interface to the Helix Core client API.
This module provides an object-oriented interface to Helix Core, the Perforce version control 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
Helix Versioning Engine, also called Helix server, and
multiple commands may be executed (serially) over a single
connection.
The basic model is to:
P4
object.Specify your Helix Core client environment.
SetClient()
SetHost()
SetPassword()
SetPort()
SetUser()
Connect to the Perforce service.
The Helix Core protocol is not designed to support multiple concurrent queries over the same connection. Multithreaded applications that use the C++ API or derived APIs (including P4Perl) should ensure that a separate connection is used for each thread, or that only one thread may use a shared connection at a time.
Construct a new P4
object. For example:
my $p4 = new P4;
Print build information including P4Perl version and Helix C/C++ API version.
print P4::Identify();
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
Helix C/C++ API
with which
P4Perl
was built.
Clear any configured output handler.
Initializes the
Helix Core
client and connects to the server. Returns false
on failure
and true
on success.
Terminate the connection and clean up. Should be called before exiting.
Returns the number of errors encountered during execution of the last command.
Returns a list of the error strings received during execution of the last command.
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
Helix server
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:
my $client = $p4->FormatSpec( "client", $hash );
my $client = $p4->FormatClient( $hash );
Returns the current API compatibility level. Each iteration of the Helix Versioning Engine is given a level number. As part of the initial communication, the client protocol level is passed between client application and the Helix Versioning Engine. This value, defined in the Helix C/C++ API, determines the communication protocol level that the Helix Core client will understand. All subsequent responses from the Helix Versioning Engine can be tailored to meet the requirements of that client protocol level.
For more information, see:
http://kb.perforce.com/article/512
Return the name of the current charset in use. Applicable only when used withHelix servers running in unicode mode.
Returns the current
Helix Core
client name. This may have previously been set by
P4::SetClient()
, or may be taken from the environment or
P4CONFIG
file if any. If all that fails, it will be your
hostname.
Returns the current working directory as your Helix Core client sees it.
Returns the value of a
Helix Core
environment variable, taking into account the settings of
Helix Core
variables in P4CONFIG
files, and, on Windows or OS X, in the
registry or user preferences.
Returns the output handler.
Returns the client hostname. Defaults to your hostname, but can be
overridden with P4::SetHost()
Get the current maxlocktime
setting.
Get the current maxresults
setting.
Get the current maxscanrows
setting.
Returns your
Helix Core
password. Taken from a previous call to P4::SetPassword()
or
extracted from the environment ($ENV{P4PASSWD}
), or a
P4CONFIG
file.
Returns the current address for your
Helix Core
server. Taken from a previous call to P4::SetPort()
, or from
$ENV{P4PORT}
or a P4CONFIG
file.
Get the name of the program as reported to the Helix Versioning Engine.
Returns the progress indicator.
Return the path of the current P4TICKETS
file.
Get the current user name. Taken from a previous call to
P4::SetUser()
, or from $ENV{P4USER}
or a
P4CONFIG
file.
Get the version of your script, as reported to the Helix Versioning Engine.
Returns true if the session has been connected, and has not been dropped.
Returns true if streams support is enabled on this server.
Returns true if Tagged mode is enabled on this client.
Returns true if server performance tracking is enabled for this connection.
Iterate over spec results. Returns an iterable object with
next()
and hasNext()
methods.
Valid <spectype>s are clients
,
labels
, branches
, changes
,
streams
, jobs
, users
,
groups
, depots
and servers
. Valid
arguments are any arguments that would be valid for the corresponding
P4::RunCmd()
command.
Arguments can be passed to the iterator to filter the results, for example, to iterate over only the first two client workspace specifications:
$p4->IterateClients( "-m2" );
You can also pass the spec type as an argument:
$p4->Iterate( "changes" );
For example, to iterate through client specs:
use P4;
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.
Get the path to the current 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
Comments in forms are preserved. Comments are stored as a
comment
key in the spec hash and are accessible. For
example:
my $spec = $pc->ParseGroup( 'my_group' );
print $spec->{'comment'};
Converts a Helix server 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:
my $hash = $p4->ParseSpec( "client", $clientspec );
my $hash = $p4->ParseClient( $clientspec );
Custom specifications require that you call Fetch
first so that the specDefs
can be determined by the API and later used by ParseSpec
.
Shorthand for running:
$p4-Run( "cmd", arg, ...);
and returning the results.
Run a
Helix Core
command and return its results. Because
Helix Core
commands can partially succeed and partially fail, it is good practice to
check for errors using P4::ErrorCount()
.
Results are returned as follows:
The AutoLoader enables you to treat Helix Core commands as methods:
p4->RunEdit( "filename.txt" );
is equivalent to:
$p4->Run( "edit", "filename.txt" );
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 Helix server version.
Tagged mode and form parsing mode are turned on by default; each result element is a hashref, but this is dependent on the command you ran and your server version.
In non-tagged mode, each result element is a string. In this case, because the Helix server sometimes asks the client to write a blank line between result elements, some of these result elements can be empty.
Note that the return values of individual Helix Core commands are not documented because they may vary between server releases.
To correlate the results returned by the P4 interface with those sent to the command line client, try running your command with RPC tracing enabled. For example:
Tagged mode: p4 -Ztag -vrpc=1 describe -s 4321
Non-Tagged mode: p4 -vrpc=1 describe -s 4321
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
P4::Resolve()
method of this class is called to handle the
resolve. For example:
$resolver = new MyResolver;
$p4->RunResolve( $resolver );
To perform an automated merge that skips whenever conflicts are detected:
use P4;
package MyResolver;
our @ISA = qw( P4::Resolver );
sub Resolve( $ ) {
my $self = shift;
my $mergeData = shift;
# "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;
package main;
$p4 = new P4;
$resolver = new MyResolver;
$p4->Connect() or die( "Failed to connect to Perforce" );
$p4->RunResolve( $resolver, ... );
In non-interactive resolves, no P4::Resolver
object
is required. For example:
$p4->RunResolve( "at" );
Submit a changelist to the server. To submit a changelist, set the fields of the changelist as required and supply any flags:
$change = $p4->FetchChange();
$change->{ 'Description' } = "Some description";
$p4->RunSubmit( "-r", $change );
You can also submit a changelist by supplying the arguments as you would on the command line:
$p4->RunSubmit( "-d", "Some description", "somedir/..." );
Get a list of tickets from the local tickets file. Each ticket is a hash
object with fields for Host
, User
, and
Ticket
.
Shorthand for running:
$p4->SetInput( $spectype );
$p4->Run( "<spectype>", "-i");
For example:
$p4->SaveLabel( $label );
$p4->SaveChange( $changeno );
$p4->SaveClient( $clientspec );
Returns an integer specifying whether or not the server is case-sensitive.
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:
http://kb.perforce.com/article/571
Returns an integer specifying whether or not the server is in Unicode mode.
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.
Must be called before calling P4::Connect()
. For
example:
$p4->SetApiLevel( 67 ); # Lock to 2010.1 format
$p4->Connect() or die( "Failed to connect to Perforce" );
# etc.
Specify the character set to use for local files when used with aHelix server running in unicode mode. Do not use unless yourHelix serveris in unicode mode. Must be called before calling
P4::Connect()
. For example:
$p4->SetCharset( "winansi" );
$p4->SetCharset( "iso8859-1" );
$p4->SetCharset( "utf8" );
# etc.
Sets the name of your Helix Core client workspace. If you don’t call this method, then the client workspace name will default according to the normal Helix Core conventions:
P4CONFIG
$ENV{P4CLIENT}
Sets the current working directory for the client.
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.
$p4->SetEnv( "P4CLIENT", "my_workspace" );
$P4->SetEnv( "P4CLIENT", "");
Sets the output handler.
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 Helix Core 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. Helix Core 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 Helix Core will scan when processing subsequent commands to the value specified. Helix Core 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.
Specify the password to use when authenticating this user against the
Helix Versioning Engine
- overrides all defaults. Not to be confused with
P4::Password()
.
Set the port on which your Helix server is listening. Defaults to:
P4CONFIG
$ENV{P4PORT}
perforce:1666
Set the name of your script. This value is displayed in the server log on 2004.2 or later servers.
Sets the progress indicator.
Enable or disable support for streams. By default, streams support is
enabled at 2011.1 or higher (P4::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).
Enable (1) or disable (0) server performance tracking for this connection. By default, performance tracking is disabled.
Set your Helix Core username. Defaults to:
P4CONFIG
C<$ENV{P4USER}>
Specify the version of your script, as recorded in the Helix server log file.
Enable (1) or disable (0) tagged output from the server, or temporarily toggle 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:
my $GetChangeCounter = sub{ $p4->RunCounter('change')->[ 0 ] );
my $changeno = $p4->Tagged( 0, $GetChangeCounter );
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 the number of warnings issued by the last command.
$p4->WarningCount();
Returns a list of warning strings from the last command
$p4->Warnings();