P4Ruby classes

The P4 module consists of several public classes:

P4
P4Exception
P4::DepotFile
P4::Revision
P4::Integration
P4::Map
P4::MergeData
P4::Message
P4::OutputHandler
P4::Progress
P4::Spec

The following tables provide brief details about each public class.

P4

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

Method	Description
`identify`	Return the version of P4Ruby in use (class method).
`new`	Construct a new `P4` object (class method).
`api_level=`	Set desired API compatibility level.
`api_level`	Return current API compatibility level.
`at_exception_level`	Execute the associated block under a specific exception level, returning to previous exception level when block returns.
`charset=`	Set character set when connecting to Unicode servers.
`charset`	Get character set when connecting to Unicode servers.
`client=`	Set client workspace (`P4CLIENT`).
`client`	Get current client workspace (`P4CLIENT`).
`connect`	Connect to the Helix Core Server, raise `P4Exception` on failure.
`connected?`	Test whether or not session has been connected and/or has been dropped.
`cwd=`	Set current working directory.
`cwd`	Get current working directory.
`delete_<spectype>`	Shortcut methods for deleting clients, labels, etc.
`disconnect`	Disconnect from the Helix Core Server.
`each_<spectype>`	Shortcut methods for iterating through clients, labels, etc.
`env`	Get the value of a Perforce environment variable, taking into account `P4CONFIG` files and (on Windows or macOS) the registry or user preferences.
`errors`	Return the array of errors that occurred during execution of previous command.
`exception_level=`	Control which types of events give rise to exceptions (`P4::RAISE_NONE`, `RAISE_ERRORS`, or `RAISE_ALL`).
`exception_level`	Return the current exception level.
`fetch_<spectype>`	Shortcut methods for retrieving the definitions of clients, labels, etc.
`format_spec`	Convert fields in a hash containing the elements of a Perforce form (spec) into the string representation familiar to users.
`format_<spectype>`	Shortcut method; equivalent to: p4.format_spec( "<spectype>", aHash )
`handler=`	Set output handler.
`handler`	Get output handler.
`host=`	Set the name of the current host (`P4HOST`).
`host`	Get the current hostname.
`input=`	Store input for next command.
`maxlocktime=`	Set MaxLockTime used for all following commands.
`maxlocktime`	Get MaxLockTime used for all following commands.
`maxresults=`	Set MaxResults used for all following commands.
`maxresults`	Get MaxResults used for all following commands.
`maxscanrows=`	Set MaxScanRows used for all following commands.
`maxscanrows`	Get MaxScanRows used for all following commands.
`messages`	Returns all messages from the server as `P4::Message` objects.
`p4config_file`	Get the location of the configuration file used (`P4CONFIG`).
`parse_<spectype>`	Shortcut method; equivalent to: p4.parse_spec( "<spectype>", aString )
`parse_spec`	Parses a Perforce form (spec) in text form into a Ruby hash using the spec definition obtained from the server.
`password=`	Set Perforce password (`P4PASSWD`).
`password`	Get the current password or ticket.
`port=`	Set host and port (`P4PORT`).
`port`	Get host and port (`P4PORT`) of the current Perforce server.
`prog=`	Set program name as shown by `p4 monitor show -e`.
`prog`	Get program name as shown by `p4 monitor show -e`.
`progress=`	Set progress indicator.
`progress`	Get progress indicator.
`run_cmd`	Shortcut method; equivalent to: p4.run( "cmd", arguments... )
`run`	Runs the specified Perforce command with the arguments supplied.
`run_filelog`	Runs a `p4 filelog` on the fileSpec provided, returns an array of `P4::DepotFile` objects.
`run_login`	Runs `p4 login` using a password or ticket set by the user.
`run_password`	A thin wrapper to make it easy to change your password.
`run_resolve`	Interface to `p4 resolve`.
`run_submit`	Submit a changelist to the server.
`run_tickets`	Get a list of tickets from the local tickets file.
`save_<spectype>`	Shortcut method; equivalent to: p4.input = hashOrString p4.run( "<spectype>", "-i" )
`server_case_sensitive?`	Detects whether or not the server is case sensitive.
`server_level`	Returns the current Perforce server level.
`server_unicode?`	Detects whether or not the server is in unicode mode.
`set_env`	On Windows or macOS, set a variable in the registry or user preferences.
`streams=`	Enable or disable support for streams.
`streams?`	Test whether or not the server supports streams
`tagged`	Toggles tagged output (true or false). By default, tagged output is on.
`tagged=`	Sets tagged output. By default, tagged output is on.
`tagged?`	Detects whether or not tagged output is enabled.
`ticketfile=`	Set the location of the `P4TICKETS` file.
`ticketfile`	Get the location of the `P4TICKETS` file.
`track=`	Activate or disable server performance tracking.
`track?`	Detect whether server performance tracking is active.
`track_output`	Returns server tracking output.
`user=`	Set the Perforce username (`P4USER`).
`user`	Get the Perforce username (`P4USER`).
`version=`	Set your script’s version as reported to the server.
`version`	Get your script’s version as reported by the server.
`warnings`	Returns the array of warnings that arose during execution of the last command.

P4Exception

Used as part of error reporting and is derived from the Ruby RuntimeError class.

P4::DepotFile

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

Method	Description
`depot_file`	Name of the depot file to which this object refers.
`each_revision`	Iterates over each revision of the depot file.
`revisions`	Returns an array of revision objects for the depot file.

P4::Revision

Utility class allowing access to the attributes of a revision P4::DepotFile object. Returned by P4#run_filelog().

Method	Description
`action`	Action that created the revision.
`change`	Changelist number.
`client`	Client workspace used to create this revision.
`depot_file`	Name of the file in the depot.
`desc`	Short changelist description.
`digest`	MD5 digest of this revision.
`filesize`	Returns the size of this revision.
`integrations`	Array of `P4::Integration` objects.
`rev`	Revision number.
`time`	Timestamp.
`type`	Perforce file type.
`user`	User that created this revision.

P4::Integration

Utility class allowing access to the attributes of an integration record for a P4::Revision object. Returned by P4#run_filelog().

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 Helix Core 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.
`empty?`	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.
`to_a`	Returns the map as an array.

P4::MergeData

Class encapsulating the context of an individual merge during execution of a p4 resolve command. Passed as a parameter to the block passed to P4#run_resolve().

Method	Description
`your_name`	Returns the name of "your" file in the merge. (file in workspace)
`their_name`	Returns the name of "their" file in the merge. (file in the depot)
`base_name`	Returns the name of "base" file in the merge. (file in the depot)
`your_path`	Returns the path of "your" file in the merge. (file in workspace)
`their_path`	Returns the path of "their" file in the merge. (temporary file on workstation into which `their_name` has been loaded)
`base_path`	Returns the path of the base file in the merge. (temporary file on workstation into which `base_name` has been loaded)
`result_path`	Returns the path to the merge result. (temporary file on workstation into which the automatic merge performed by the server has been loaded)
`merge_hint`	Returns hint from server as to how user might best resolve merge.
`run_merge`	If the environment variable `P4MERGE` is defined, run it and return a boolean based on the return value of that program.

P4::Message

Utility class allowing access to the attributes of a message object returned by P4#messages().

Method	Description
`severity`	Returns the severity of the message.
`generic`	Returns the generic class of the error.
`msgid`	Returns the unique ID of the error message.
`to_s`	Returns the error message as a string.
`inspect`	Converts the error object into a string for debugging purposes.

P4::OutputHandler

Handler class that provides access to streaming output from the server; set P4#handler() to an instance of a subclass 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; set P4#progress() to an instance of a subclass of P4::Progress with the following methods (even if the implementations are empty) 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::Spec

Subclass of hash allowing access to the fields in a Perforce specification form. Also checks that the fields that are set are valid fields for the given type of spec. Returned by P4#fetch__<spectype>_().

Method	Description
`spec._fieldname`	Return the value associated with the field named fieldname.
`spec._fieldname=`	Set the value associated with the field named fieldname.
`spec.permitted_fields`	Returns an array containing the names of fields that are valid in this spec object.