APIs for Scripting (2015.1)

Construct a new P4 object. For example:

my $p4 = new P4;

Print build information including P4Perl version and Perforce 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 Perforce C++ API with which P4Perl was built.

Clear any configured output handler.

Initializes the Perforce 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 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:

my $client = $p4->FormatSpec( "client", $hash );

my $client = $p4->FormatClient( $hash );

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.

For more information, see:

http://kb.perforce.com/article/512

Return the name of the current charset in use. Applicable only when used with Perforce servers running in unicode mode.

Returns the current Perforce 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 Perforce client sees it.

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.

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 Perforce 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 Perforce 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 Perforce Server.

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 Perforce Server.

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
FIXME

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 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:

my $hash = $p4->ParseSpec( "client", $clientspec );

my $hash = $p4->ParseClient( $clientspec );

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

Results are returned as follows:

The AutoLoader enables you to treat Perforce 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 Perforce 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 Perforce 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 Perforce 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

FIXME 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 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:

$p4->SetCharset( "winansi" );
$p4->SetCharset( "iso8859-1" );
$p4->SetCharset( "utf8" );
# etc.

Sets the name of your Perforce client workspace. If you don't call this method, then the client workspace name will default according to the normal Perforce conventions:

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

Specify the password to use when authenticating this user against the Perforce Server - overrides all defaults. Not to be confused with P4::Password().

Set the port on which your Perforce server is listening. Defaults to:

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 Perforce username. Defaults to:

Specify the version of your script, as recorded in the Perforce 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();