Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 API for Ruby Documentation | 2025.2

# P4 API for Ruby 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 P4 API for Ruby will involve this class.

Method | Description
--- | ---
`identify` | Return the version of P4 API for Ruby 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 P4 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 P4 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 P4 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.

Your search for returned results