Helix Core P4Ruby Developer Guide (2020.1)

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