Class P4
Description
Main interface to the Helix Server client API.
This module provides an object-oriented interface to Helix Server, 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 Core Server, also called Helix Server, and
multiple commands may be executed (serially) over a single
connection.
The basic model is to:
- Instantiate your
P4
object. -
Specify your Helix Server client environment.
SetClient()
SetHost()
SetPassword()
SetPort()
SetUser()
-
Connect to the Perforce service.
The Helix Server 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.
- Run your Helix Server commands.
- Disconnect from the Perforce service.
Class methods
P4::new() -> P4
Construct a new P4
object. For example:
my $p4 = new P4;
P4::Identify() -> string
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.
P4::ClearHandler() -> undef
Clear any configured output handler.
P4::Connect() -> bool
Initializes the
Helix Server
client and connects to the server. Returns false
on failure
and true
on success.
P4::Disconnect() -> undef
Terminate the connection and clean up. Should be called before exiting.
P4::ErrorCount() -> integer
Returns the number of errors encountered during execution of the last command.
P4::Errors() -> list
Returns a list of the error strings received during execution of the last command.
P4::Fetch<Spectype>( [name] ) -> hashref
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 );
P4::Format<Spectype>( hash ) -> string
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 );
P4::FormatSpec( $spectype, $string ) -> string
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 );
P4::GetApiLevel() -> integer
Returns the current API compatibility level. Each iteration of the Helix Core Server is given a level number. As part of the initial communication, the client protocol level is passed between client application and the Helix Core Server. This value, defined in the Helix C/C++ API, determines the communication protocol level that the Helix Server client will understand. All subsequent responses from the Helix Core Server can be tailored to meet the requirements of that client protocol level.
For more information about the client protocol levels, see Protocol levels: server/client in the Helix Core Server Administrator Guide.
P4::GetCharset() -> string
Return the name of the current charset in use. Applicable only when used withHelix Servers running in unicode mode.
P4::GetClient() -> string
Returns the current
Helix Server
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.
P4::GetCwd() -> string
Returns the current working directory as your Helix Server client sees it.
P4::GetEnv( $var ) -> string
Returns the value of a
Helix Server
environment variable, taking into account the settings of
Helix Server
variables in P4CONFIG
files, and, on Windows or macOS, in the
registry or user preferences.
P4::GetHandler() -> Handler
Returns the output handler.
P4::GetHost() -> string
Returns the client hostname. Defaults to your hostname, but can be
overridden with P4::SetHost()
P4::GetMaxLockTime( $value ) -> integer
Get the current maxlocktime
setting.
P4::GetMaxResults( $value ) -> integer
Get the current maxresults
setting.
P4::GetMaxScanRows( $value ) -> integer
Get the current maxscanrows
setting.
P4::GetPassword() -> string
Returns your
Helix Server
password. Taken from a previous call to P4::SetPassword()
or
extracted from the environment ($ENV{P4PASSWD}
), or a
P4CONFIG
file.
P4::GetPort() -> string
Returns the current address for your
Helix Server
server. Taken from a previous call to P4::SetPort()
, or from
$ENV{P4PORT}
or a P4CONFIG
file.
P4::GetProg() -> string
Get the name of the program as reported to the Helix Core Server.
P4::GetProgress() -> Progress
Returns the progress indicator.
P4::GetTicketFile( [$string] ) -> string
Return the path of the current P4TICKETS
file.
P4::GetUser() -> String
Get the current user name. Taken from a previous call to
P4::SetUser()
, or from $ENV{P4USER}
or a
P4CONFIG
file.
P4::GetVersion( $string ) -> string
Get the version of your script, as reported to the Helix Core Server.
P4::IsConnected() -> bool
Returns true if the session has been connected, and has not been dropped.
P4::IsStreams() -> bool
Returns true if streams support is enabled on this server.
P4::IsTagged() -> bool
Returns true if Tagged mode is enabled on this client.
P4::IsTrack() -> bool
Returns true if server performance tracking is enabled for this connection.
P4::Iterate<Spectype>(arguments) -> object
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" );
}
P4::Messages() -> list
Returns an array of P4::Message()
objects, one for
each message (info, warning or error) sent by the server.
P4::P4ConfigFile() -> string
Get the path to the current P4CONFIG
file.
P4::Parse<Spectype>( $string ) -> hashref
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 string (equivalent to running 'p4 client -o' from the command-line)
$client = $p4->FormatClient( $client );
# Convert to a hashref
$client = $p4->ParseClient( $client );
# Convert back to string
$client = $p4->FormatClient( $client );
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'};
P4::ParseSpec( $spectype, $string ) -> hashref
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
.
P4::Run<Cmd>( [ $arg… ] ) -> list | arrayref
Shorthand for running:
$p4-Run( "cmd", arg, ...);
and returning the results.
P4::Run( "<cmd>", [ $arg… ] ) -> list | arrayref
Run a
Helix Server
command and return its results. Because
Helix Server
commands can partially succeed and partially fail, it is good practice to
check for errors using P4::ErrorCount()
.
Results are returned as follows:
- A list of results in array context
- An array reference in scalar context
The AutoLoader enables you to treat Helix Server 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 Server 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.
P4::RunFilelog( [$args …], $fileSpec … ) -> list | arrayref
Runs a p4 filelog
on the fileSpec
provided and returns an array of P4::DepotFile
objects when executed in tagged mode.
P4::RunLogin(…) -> list | arrayref
Runs p4 login
using a password or ticket set by the
user.
P4::RunPassword( $oldpass, $newpass ) -> list | arrayref
A thin wrapper for changing your password from $oldpass
to
$newpass
. Not to be confused with
P4::SetPassword()
.
P4::RunResolve( [$resolver], [$args …] ) -> string
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->MergeHint() eq "e" );
return $mergeData->MergeHint();
}
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" );
P4::RunSubmit( $arg | $hashref, …) -> list | arrayref
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/..." );
P4::RunTickets() -> list
Get a list of tickets from the local tickets file. Each ticket is a hash
object with fields for Host
, User
, and
Ticket
.
P4::Save<Spectype>() -> list | arrayref
Shorthand for running:
$p4->SetInput( $spectype );
$p4->Run( "<spectype>", "-i");
For example:
$p4->SaveLabel( $label );
$p4->SaveChange( $changeno );
$p4->SaveClient( $clientspec );
P4::ServerCaseSensitive() -> integer
Returns an integer specifying whether or not the server is case-sensitive.
P4::ServerLevel() -> integer
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 about the Helix Server version levels, see Protocol levels: server/client in the Helix Core Server Administrator Guide.
P4::ServerUnicode() -> integer
Returns an integer specifying whether or not the server is in Unicode mode.
P4::SetApiLevel( $integer ) -> undef
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.
P4::SetCharset( $charset ) -> undef
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.
P4::SetClient( $client ) -> undef
Sets the name of your Helix Server client workspace. If you don’t call this method, then the client workspace name will default according to the normal Helix Server conventions:
- Value from file specified by
P4CONFIG
- Value from
$ENV{P4CLIENT}
- Hostname
P4::SetCwd( $path ) -> undef
Sets the current working directory for the client.
P4::SetEnv( $var, $value ) -> undef
On Windows or macOS, 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", "");
P4::SetHandler( Handler ) -> Handler
Sets the output handler.
P4::SetHost( $hostname ) -> undef
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.
P4::SetInput( $string | $hashref | $arrayref ) -> undef
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 Server command being executed asks for user input.
P4::SetMaxLockTime( $integer ) -> undef
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.
P4::SetMaxResults( $integer ) -> undef
Limit the number of results for subsequent commands to the value specified. Helix Server 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.
P4::SetMaxScanRows( $integer ) -> undef
Limit the number of records Helix Server will scan when processing subsequent commands to the value specified. Helix Server 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.
P4::SetPassword( $password ) -> undef
Specify the password to use when authenticating this user against the
Helix Core Server
- overrides all defaults. Not to be confused with
P4::Password()
.
P4::SetPort( $port ) -> undef
Set the port on which your Helix Server is listening. Defaults to:
- Value from file specified by
P4CONFIG
- Value from
$ENV{P4PORT}
perforce:1666
P4::SetProg( $program_name ) -> undef
Set the name of your script. This value is displayed in the server log on 2004.2 or later servers.
P4::SetProgress( Progress ) -> Progress
Sets the progress indicator.
P4::SetStreams( 0 | 1 ) -> undef
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.
P4::SetTicketFile( [$string] ) -> string
Set the path to the current P4TICKETS
file (and return
it).
P4::SetTrack( 0 | 1 ) -> undef
Enable (1) or disable (0) server performance tracking for this connection. By default, performance tracking is disabled.
P4::SetUser( $username ) -> undef
Set your Helix Server username. Defaults to:
- Value from file specified by
P4CONFIG
- Value from
C<$ENV{P4USER}>
- OS username
P4::SetVersion( $version ) -> undef
Specify the version of your script, as recorded in the Helix Server log file.
P4::Tagged( 0 | 1 | $coderef ) -> undef
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).
P4::TrackOutput() -> list
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.
P4::WarningCount() -> integer
Returns the number of warnings issued by the last command.
$p4->WarningCount();
P4::Warnings() -> list
Returns a list of warning strings from the last command
$p4->Warnings();