P4Ruby classes // APIs for Scripting

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 Perforce 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 Perforce 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 OS X) 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 OS X, 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 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.
`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.

APIs for Scripting (2014.2)

P4Ruby classes

P4