P4Perl Classes

The P4 module consists of several public classes:

The following tables provide brief details about each public class.

P4

The main class used for executing Perforce commands. Almost everything you do with P4Perl will involve this class.

Method

Description

new()

Construct a new P4 object.

Identify()

Print build information including P4Perl version and Perforce API version.

ClearHandler()

Clear the output handler.

Connect()

Initialize the Perforce client and connect to the Server.

Disconnect()

Disconnect from the Perforce Server.

ErrorCount()

Returns the number of errors encountered during execution of the last command.

Errors()

Returns a list of the error strings received during execution of the last command.

Fetch<Spectype>()

Shorthand for running:

$p4->Run( "<spectype>", "-o" );

Format<Spectype>()

Shorthand for running:

$p4->FormatSpec( "<spectype>", hash );

FormatSpec()

Converts a Perforce form of the specified type (client/label etc.) held in the supplied hash into its string representation.

GetApiLevel()

Get current API compatibility level.

GetCharset()

Get character set when connecting to Unicode servers.

GetClient()

Get current client workspace (P4CLIENT).

GetCwd()

Get current working directory.

GetEnv()

Get the value of a Perforce environment variable, taking into account P4CONFIG files and (on Windows or OS X) the registry or user preferences.

GetHandler()

Get the output handler.

GetHost()

Get the current hostname.

GetMaxLockTime()

Get MaxLockTime used for all following commands.

GetMaxResults()

Get MaxResults used for all following commands.

GetMaxScanRows()

Get MaxScanRows used for all following commands.

GetPassword()

Get the current password or ticket.

GetPort()

Get host and port (P4PORT).

GetProg()

Get the program name as shown by the p4 monitor show -e command.

GetProgress()

Get the progress indicator.

GetTicketFile()

Get the location of the P4TICKETS file.

GetUser()

Get the current username (P4USER).

GetVersion()

Get the version of your script, as reported to the Perforce Server.

IsConnected()

Test whether or not session has been connected and/or has been dropped.

IsStreams()

Test whether or not streams are enabled.

IsTagged()

Test whether or not tagged output is enabled.

IsTrack()

Test whether or not server performance tracking is enabled.

Iterate<Spectype>()

Iterate through spec results.

Messages()

Return an array of P4::Message objects, one for each message sent by the server.

P4ConfigFile()

Get the location of the configuration file used (P4CONFIG).

Parse<Spectype>()

Shorthand for running:

$p4-ParseSpec( "<spectype>", buffer );

ParseSpec()

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.

RunCmd()

Shorthand for running:

$p4-Run( "cmd", arg, ... );

Run()

Run a Perforce command and return its results. Check for errors with P4::ErrorCount().

RunFilelog()

Runs a p4 filelog on the fileSpec provided and returns an array of P4::DepotFile objects.

RunLogin()

Runs p4 login using a password or ticket set by the user.

RunPassword()

A thin wrapper for changing your password.

RunResolve()

Interface to p4 resolve.

RunSubmit()

Submit a changelist to the server.

RunTickets()

Get a list of tickets from the local tickets file.

Save<Spectype>()

Shorthand for running:

$p4->SetInput( $spectype );
$p4->Run( "<spectype>", "-i" );

ServerCaseSensitive()

Returns an integer specifying whether or not the server is case-sensitive.

ServerLevel()

Returns an integer specifying the server protocol level.

ServerUnicode()

Returns an integer specifying whether or not the server is in Unicode mode.

SetApiLevel()

Specify the API compatibility level to use for this script.

SetCharset()

Set character set when connecting to Unicode servers.

SetClient()

Set current client workspace (P4CLIENT).

SetCwd()

Set current working directory.

SetEnv()

On Windows or OS X, set an environment variable in the registry or user preferences.

SetHandler()

Set the output handler.

SetHost()

Set the name of the current host (P4HOST).

SetInput()

Save the supplied argument as input to be supplied to a subsequent command.

SetMaxLockTime()

Set MaxLockTime used for all following commands.

SetMaxResults()

Set MaxResults used for all following commands.

SetMaxScanRows()

Set MaxScanRows used for all following commands.

SetPassword()

Set Perforce password (P4PASSWD).

SetPort()

Set host and port (P4PORT).

SetProg()

Set the program name as shown by the p4 monitor show -e command.

SetProgress()

Set the progress indicator.

SetStreams()

Enable or disable streams support.

SetTicketFile()

Set the location of the P4TICKETS file.

SetTrack()

Activate or deactivate server performance tracking. By default, tracking is off (0).

SetUser()

Set the Perforce username (P4USER).

SetVersion()

Set the version of your script, as reported to the Perforce Server.

Tagged()

Toggles tagged output (1 or 0). By default, tagged output is on (1).

TrackOutput()

If performance tracking is enabled with SetTrack() returns an array of strings with tracking output.

WarningCount()

Returns the number of warnings issued by the last command.

Warnings()

Returns a list of the warning strings received during execution of the last command.

P4::DepotFile

Utility class allowing access to the attributes of a file in the depot. Returned by P4::RunFilelog().

Method

Description

DepotFile()

Name of the depot file to which this object refers.

Revisions()

Returns an array of revision objects for the depot file.

P4::Revision

Utility class allowing access to the attributes of a revision of a file in the depot. Returned by P4::RunFilelog().

Method

Description

Action()

Returns the action that created the revision.

Change()

Returns the changelist number that gave rise to this revision of the file.

Client()

Returns the name of the client from which this revision was submitted.

DepotFile()

Returns the name of the depot file to which this object refers.

Desc()

Returns the description of the change which created this revision.

Digest()

Returns the MD5 digest for this revision.

FileSize()

Returns the size of this revision.

Integrations()

Returns an array of P4::Integration objects representing all integration records for this revision.

Rev()

Returns the number of this revision.

Time()

Returns date/time this revision was created.

Type()

Returns the Perforce filetype of this revision.

User()

Returns the name of the user who created this revision.

P4::Integration

Utility class allowing access to the attributes of an integration record for a revision of a file in the depot. Returned by P4::RunFilelog().

Method

Description

How()

Integration method (merge/branch/copy/ignored).

File()

Integrated file.

SRev()

Start revision.

ERev()

End revision.

P4::Map

A class that allows users to create and work with Perforce mappings without requiring a connection to the Perforce Server.

Method

Description

New()

Construct a new Map object (class method).

Join()

Joins two maps to create a third (class method).

Clear()

Empties a map.

Count()

Returns the number of entries in a map.

IsEmpty()

Tests whether or not a map object is empty.

Insert()

Inserts an entry into the map.

Translate()

Translate a string through a map.

Includes()

Tests whether a path is mapped.

Reverse()

Returns a new mapping with the left and right sides reversed.

Lhs()

Returns the left side as an array.

Rhs()

Returns the right side as an array.

AsArray()

Returns the map as an array.

P4::MergeData

Class encapsulating the context of an individual merge during execution of a p4 resolve command. Passed to P4::RunResolve.

Method

Description

YourName()

Returns the name of "your" file in the merge. (file in workspace)

TheirName()

Returns the name of "their" file in the merge. (file in the depot)

BaseName()

Returns the name of "base" file in the merge. (file in the depot)

YourPath()

Returns the path of "your" file in the merge. (file in workspace)

TheirPath()

Returns the path of "their" file in the merge. (temporary file on workstation into which TheirName() has been loaded)

BasePath()

Returns the path of the base file in the merge. (temporary file on workstation into which BaseName() has been loaded)

ResultPath()

Returns the path to the merge result. (temporary file on workstation into which the automatic merge performed by the server has been loaded)

MergeHint()

Returns hint from server as to how user might best resolve merge.

RunMergeTool()

If the environment variable P4MERGE is defined, run it and indicate whether or not the merge tool successfully executed.

P4::Message

Class encapsulating the context of an individual error during execution of Perforce commands. Passed to P4::Messages().

Method

Description

GetSeverity()

Returns the severity class of the error.

GetGeneric()

Returns the generic class of the error message.

GetId()

Returns the unique ID of the error message.

GetText()

Get the text of the error message.

P4::OutputHandler

Handler class that provides access to streaming output from the server; call P4::SetHandler() with an implementation of P4::OutputHandler to enable callbacks:

Method

Description

OutputBinary()

Process binary data.

OutputInfo()

Process tabular data.

OutputMessage()

Process information or errors.

OutputStat()

Process tagged output.

OutputText()

Process text data.

P4::Progress

Handler class that provides access to progress indicators from the server; call P4::SetProgress() with an implementation of P4::Progress to enable callbacks:

Method

Description

Init()

Initialize progress indicator as designated type.

Total()

Total number of units (if known).

Description()

Description and type of units to be used for progress reporting.

Update()

If non-zero, user has requested a cancellation of the operation.

Done()

If non-zero, operation has failed.

P4::Resolver

Class for handling resolves in Perforce.

Method

Description

Resolve()

Perform a resolve and return the resolve decision as a string.

P4::Spec

Utility class allowing access to the attributes of the fields in a Perforce form.

Method

Description

_fieldname()

Return the value associated with the field named fieldname.

_fieldname()

Set the value associated with the field named fieldname.

PermittedFields()

Lists the fields that are permitted for specs of this type.