P4Ruby 2014.2December 2014Perforce2014Perforce Software.Introduction
P4Ruby is an extension to the Ruby programming language that allows you to
run Perforce commands from within Ruby scripts, and get the results in a
Ruby-friendly format.
The main features are:
Get Perforce data and forms in hashes and arrays.
Edit Perforce forms by modifying hashes.
Exception based error handling.
Controllable handling of warnings such as "File(s) up-to-date." on a
sync.
Run as many commands on a connection as required.
The output of a command is returned as a Ruby array. For non-tagged
output, the elements of the array are strings. For tagged output, the
elements of the array are Ruby hashes. For forms, the output is an
array of P4::Spec objects.
Thread-safe and thread-friendly; you can have multiple instances of
the P4 class running in different threads.
Exception-based error handling. Trap
P4Exceptions for complete, high-level
error handling.
The most recent release of P4Ruby is 2014.2.
System Requirements
P4Ruby is supported on Windows, Linux, and OS X for Ruby MRI distributions
versions 2.0 and greater.
System Requirements to Build P4Ruby Source Distributions
To build P4Ruby, your development machine must also have:
The Ruby MRI distribution version that is the same major and minor
version of your runtime Ruby VM.
The appropriate compiler toolchain. On Linux is typically the gcc
distribution installed with your system tools. On OS X, you will
need the XCode command line tools. On Windows, you should download
one of the DevKit distributions from
rubyinstaller.org.
The same C++ compiler used to build the Perforce C++ API on your
target platform.
(If you get "unresolved symbol" errors when building or running
P4Ruby, you probably used the wrong compiler or the wrong Perforce API
build.)
The 2014.2 Perforce C/C++ API for your target platform. Older releases
might work, but are not supported. (For Windows, you will need the
MinGW-w64 platform.)
Installing P4Ruby
P4Ruby can be installed via gem install p4ruby. This
should attempt to install a precompiled binary distribution for your
platform.
If no precompiled binary gem is available, this will attempt to download
a prebuilt version of the C++ P4API, then compile P4Ruby. If no binary
C++ distribution of the P4API is available, gem install
will fail.
If you have a version of the C++ P4API you would like to use, you can
specify this using the --with-p4api-dir=[path]
option to the gem install p4ruby command.
You can also download source distributions of P4Ruby from the Perforce
web site:
http://www.perforce.com/product/components/apis
After downloading, you can build the interface from source, as described
in the release notes.
Programming with P4Ruby
The following example shows how to create a new client workspace based on
an existing template:
require "P4"
template = "my-client-template"
client_root = 'c:\p4-work'
p4 = P4.new
p4.connect
begin
# Run a "p4 client -t template -o" and convert it into a Ruby hash
spec = p4.fetch_client( "-t", template, "my-new-client")
# Now edit the fields in the form
spec[ "Root" ] = client_root
spec[ "Options" ] = spec[ "Options" ].sub( "normdir", "rmdir" )
# Now save the updated spec
p4.save_client( spec )
# Point to the newly-created client
p4.client="my-new-client"
# And sync it.
p4.run_sync
rescue P4Exception
# If any errors occur, we'll jump in here. Just log them
# and raise the exception up to the higher level
p4.errors.each { |e| $stderr.puts( e ) }
raise
end
Connecting to SSL-enabled servers
Scripts written with P4Ruby use any existing P4TRUST file
present in their operating environment (by default,
.p4trust in the home directory of the user that
runs the script).
If the fingerprint returned by the server fails to match the one
installed in the P4TRUST file associated with the
script's run-time environment, your script will (and should!) fail to
connect to the server.
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 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.
Class P4Description
Main interface to the Perforce client API. Each
P4 object provides you with a thread-safe API
level interface to Perforce. The basic model is to:
Instantiate your P4 object.
Specify your Perforce client environment.
clienthostpasswordportuser
Set any options to control output or error handling:
exception_level
Connect to the Perforce service.
The Perforce protocol is not designed to support multiple concurrent
queries over the same connection. Multithreaded applications that
use the C++ API or derived APIs (including P4Ruby) should ensure
that a separate connection is used for each thread, or that only one
thread may use a shared connection at a time.
Run your Perforce commands.
Disconnect from the Perforce service.
Class MethodsP4.identify -> aString
Return the version of P4Ruby that you are using. Also reports the
version of the OpenSSL library used for building the underlying
Perforce C++ API with which P4Ruby was built.
ruby -rP4 -e 'puts( P4.identify )'
Some of this information is already made available through the
predefined constants P4::VERSION,
P4::OS, and P4::PATCHLEVEL.
P4.new -> aP4
Constructs a new P4 object.
p4 = P4.new()
Instance Methodsp4.api_level= anInteger -> anInteger
Sets the API compatibility level desired. This is useful when writing
scripts using Perforce commands that do not yet support tagged output.
In these cases, upgrading to a later server that supports tagged
output for the commands in question can break your script. Using this
method allows you to lock your script to the output format of an older
Perforce release and facilitate seamless upgrades. This method
must be called prior to calling
P4#connect().
p4 = P4.new
p4.api_level = 67 # Lock to 2010.1 format
p4.connect
...
For the API integer levels that correspond to each Perforce release,
see:
http://kb.perforce.com/article/512
p4.api_level -> anInteger
Returns the current Perforce API compatibility level. Each iteration
of the Perforce Server is given a level number. As part of the initial
communication, the client protocol level is passed between client
application and the Perforce Server. This value, defined in the
Perforce API, determines the communication protocol level that the
Perforce client will understand. All subsequent responses from the
Perforce Server can be tailored to meet the requirements of that
client protocol level.
For more information, see:
http://kb.perforce.com/article/512
p4.at_exception_level( lev ) { ... } -> self
Executes the associated block under a specific exception level.
Returns to the previous exception level when the block returns.
p4 = P4.new
p4.client = "www"
p4.connect
p4.at_exception_level( P4::RAISE_ERRORS ) do
p4.run_sync
end
p4.disconnect
p4.charset= aString -> aString
Sets the character set to use when connect to a Unicode enabled
server. Do not use when working with non-Unicode-enabled servers. By
default, the character set is the value of the
P4CHARSET environment variable. If the character set is
invalid, this method raises a
P4Exception.
p4 = P4.new
p4.client = "www"
p4.charset = "iso8859-1"
p4.connect
p4.run_sync
p4.disconnect
p4.charset -> aString
Get the name of the character set in use when working with
Unicode-enabled servers.
p4 = P4.new
p4.charset = "utf8"
puts( p4.charset )
p4.client= aString -> aString
Set the name of the client workspace you wish to use. If not called,
defaults to the value of P4CLIENT taken from any
P4CONFIG file present, or from the environment as per
the usual Perforce convention. Must be called before connecting to the
Perforce server.
p4 = P4.new
p4.client = "www"
p4.connect
p4.run_sync
p4.disconnect
p4.client -> aString
Get the name of the Perforce client currently in use.
p4 = P4.new
puts( p4.client )
p4.connect -> aBool
Connect to the Perforce Server. You must connect before you can
execute commands. Raises a P4Exception
if the connection attempt fails.
p4 = P4.new
p4.connect
p4.connected? -> aBool
Test whether or not the session has been connected, and if the
connection has not been dropped.
p4 = P4.newp4.connected?
p4.cwd= aString -> aString
Sets the current working directly. Can be called prior to executing
any Perforce command. Sometimes necessary if your script executes a
chdir() as part of its processing.
p4 = P4.new
p4.cwd = "/home/bruno"
p4.cwd -> aString
Get the current working directory.
p4 = P4.new
puts( p4.cwd )
p4.delete_<spectype>( [options], name ) -> anArray
The delete methods are simply shortcut methods that allow you to
quickly delete the definitions of clients, labels, branches, etc.
These methods are equivalent to:
p4.run( "<spectype>", '-d', [options], "spec name" )
For example:
require "P4"
require "parsedate"
include ParseDate
now = Time.now
p4 = P4.new
begin
p4.connect
p4.run_clients.each do
|client|
atime = parsedate( client[ "Access" ] )
if( (atime + 24 * 3600 * 365 ) < now )
p4.delete_client( '-f', client[ "client" ] )
end
end
rescue P4Exception
p4.errors.each { |e| puts( e ) }
ensure
p4.disconnect
end
p4.disconnect -> true
Disconnect from the Perforce Server.
p4 = P4.new
p4.connect
p4.disconnect
p4.each_<spectype<( arguments ) -> anArray
The each_<spectype>
methods are shortcut methods that allow you to quickly iterate through
clients, labels, branches, etc. Valid
<spectype>s are clients,
labels, branches,
changes, streams,
jobs, users,
groups, depots and
servers. Valid arguments are any arguments that
would be valid for the corresponding
run_<spectype>
command.
For example, to iterate through clients:
p4.each_clients do
|c|
# work with the retrieved client spec
end
is equivalent to:
clients = p4.run_clients
clients.each do
|c|
client = p4.fetch_client( c['client'] )
# work with the retrieved client spec
end
p4.env -> string
Get the value of a Perforce environment variable, taking into account
P4CONFIG files and (on Windows and OS X) the registry
or user preferences.
p4 = P4.new
puts p4.env( "P4PORT" )
p4.errors -> anArray
Returns the array of errors which occurred during execution of the
previous command.
p4 = P4.new
begin
p4.connect
p4.exception_level( P4::RAISE_ERRORS ) # ignore "File(s) up-to-date"
files = p4.run_sync
rescue P4Exception
p4.errors.each { |e| puts( e ) }
ensure
p4.disconnect
end
p4.exception_level= anInteger -> anInteger
Configures the events which give rise to exceptions. The following
three levels are supported:
P4::RAISE_NONE disables all exception raising
and makes the interface completely procedural.
P4::RAISE_ERRORS causes exceptions to be raised
only when errors are encountered.
P4::RAISE_ALL causes exceptions to be raised
for both errors and warnings. This is the default.
p4 = P4.new
p4.exception_level = P4::RAISE_ERRORS
p4.connect # P4Exception on failure
p4.run_sync # File(s) up-to-date is a warning so no exception is raised
p4.disconnect
p4.exception_level -> aNumber
Returns the current exception level.
p4.fetch_<spectype>( [name] ) -> aP4::Spec
The fetch_<spectype>
methods are shortcut methods that allow you to quickly fetch the
definitions of clients, labels, branches, etc. They're equivalent to:
p4.run( "<spectype>", '-o', ... ).shift
For example:
p4 = P4.new
begin
p4.connect
client = p4.fetch_client()
other_client = p4.fetch_client( "other" )
label = p4.fetch_label( "somelabel" )
rescue P4Exception
p4.errors.each { |e| puts( e ) }
ensure
p4.disconnect
end
p4.format_spec( "<spectype>", aHash )-> aString
Converts the fields in a hash containing the elements of a Perforce
form (spec) into the string representation familiar to users.
The first argument is the type of spec to format: for example,
client, branch,
label, and so on. The second argument is the hash
to parse.
There are shortcuts available for this method. You can use:
p4.format_<spectype>( hash )
instead of:
p4.format_spec( "<spectype>", hash )
where <spectype> is the name of a Perforce
spec, such as client, label,
etc.
p4.format_<spectype> aHash -> aHash
The
format_<spectype>
methods are shortcut methods that allow you to quickly fetch the
definitions of clients, labels, branches, etc. They're equivalent to:
p4.format_spec( "<spectype>", aHash )
p4.handler= aHandler -> aHandler
Set the current output handler. This should be a subclass of
P4::OutputHandler.
p4.handler -> aHandler
Get the current output handler.
p4.host= aString -> aString
Set the name of the current host. If not called, defaults to the value
of P4HOST taken from any P4CONFIG file
present, or from the environment as per the usual Perforce convention.
Must be called before connecting to the Perforce server.
p4 = P4.new
p4.host = "workstation123.perforce.com"
p4.connect
...
p4.disconnect
p4.host -> aString
Get the current hostname.
p4 = P4.new
puts( p4.host )
p4.input= ( aString|aHash|anArray ) -> aString|aHash|anArray
Store input for the next command.
Call this method prior to running a command requiring input from the
user. When the command requests input, the specified data will be
supplied to the command. Typically, commands of the form p4
cmd -i are invoked using the
P4#save_<spectype>()
methods, which call P4#input() internally;
there is no need to call P4#input() when
using the
P4#save_<spectype>()
shortcuts.
You may pass a string, a hash, or (for commands that take multiple
inputs from the user) an array of strings or hashes. If you pass an
array, note that the array will be shifted each time Perforce asks the
user for input.
p4 = P4.new
p4.connect
change = p4.run_change( "-o" ).shift
change[ "Description" ] = "Autosubmitted changelist"
p4.input = change
p4.run_submit( "-i" )
p4.disconnect
p4.maxlocktime= anInteger -> anInteger
Limit the amount of time (in milliseconds) spent during data scans to
prevent the server from locking tables for too long. Commands that
take longer than the limit will be aborted. The limit remains in force
until you disable it by setting it to zero. See p4 help
maxlocktime for information on the commands that support
this limit.
p4 = P4.new
begin
p4.connect
p4.maxlocktime = 10000 # 10 seconds
files = p4.run_sync
rescue P4Exception => ex
p4.errors.each { |e| $stderr.puts( e ) }
ensure
p4.disconnectend
p4.maxlocktime -> anInteger
Get the current maxlocktime setting.
p4 = P4.new
puts( p4.maxlocktime )
p4.maxresults= anInteger -> anInteger
Limit the number of results Perforce permits for subsequent commands.
Commands that produce more than this number of results will be
aborted. The limit remains in force until you disable it by setting it
to zero. See p4 help maxresults for information on
the commands that support this limit.
p4 = P4.new
begin
p4.connect
p4.maxresults = 100
files = p4.run_sync
rescue P4Exception => ex
p4.errors.each { |e| $stderr.puts( e ) }
ensure
p4.disconnect
end
p4.maxresults -> anInteger
Get the current maxresults setting.
p4 = P4.new
puts( p4.maxresults )
p4.maxscanrows= anInteger -> anInteger
Limit the number of database records Perforce will scan for subsequent
commands. Commands that attempt to scan more than this number of
records will be aborted. The limit remains in force until you disable
it by setting it to zero. See p4 help maxscanrows
for information on the commands that support this limit.
p4 = P4.new
begin
p4.connect
p4.maxscanrows = 100
files = p4.run_sync
rescue P4Exception => ex
p4.errors.each { |e| $stderr.puts( e ) }
ensure
p4.disconnectend
p4.maxscanrows -> anInteger
Get the current maxscanrows setting.
p4 = P4.new
puts( p4.maxscanrows )
p4.messages -> aP4::Message
Returns a message from the Perforce Server in the form of a
P4::Message object.
p4 = P4.new
p4.exception_level = P4::RAISE_NONE
p4.run_sync
p4.run_sync # this second sync should return "File(s) up-to-date."
w = p4.messages[0]
puts ( w.to_s )
p4.p4config_file -> aString
Get the path to the current P4CONFIG file.
p4 = P4.new
puts( p4.p4config_file )
p4.parse_<spectype>( aString ) -> aP4::Spec
This is equivalent to:
p4.parse_spec( "<spectype>", aString )
p4.parse_spec( "<spectype>", aString ) -> aP4::Spec
Parses a Perforce form (spec) in text form into a Ruby hash using the
spec definition obtained from the server.
The first argument is the type of spec to parse:
client, branch,
label, and so on. The second argument is the string
buffer to parse.
Note that there are shortcuts available for this method. You can use:
p4.parse_<spectype>( buf )
instead of:
p4.parse_spec( "<spectype>", buf )
Where <spectype> is one of
client, branch,
label, and so on.
p4.password= aString -> aString
Set your Perforce password, in plain text. If not used, takes the
value of P4PASSWD from any P4CONFIG file
in effect, or from the environment according to the normal Perforce
conventions. This password will also be used if you later call
p4.run_login to login using the 2003.2 and later
ticket system.
p4 = P4.new
p4.password = "mypass"
p4.connect
p4.run_login
p4.password -> aString
Get the current password or ticket. This may be the password in plain
text, or if you've used P4#run_login(), it'll
be the value of the ticket you've been allocated by the server.
p4 = P4.new
puts( p4.password )
p4.port= aString -> aString
Set the host and port of the Perforce server you want to connect to.
If not called, defaults to the value of P4PORT in any
P4CONFIG file in effect, and then to the value of
P4PORT taken from the environment.
p4 = P4.new
p4.port = "localhost:1666"
p4.connect
...
p4.disconnect
p4.port -> aString
Get the host and port of the current Perforce server.
p4 = P4.new
puts( p4.port )
p4.prog= aString -> aString
Set the name of the program, as reported to Perforce system
administrators running p4 monitor show -e in
Perforce 2004.2 or later releases.
p4 = P4.new
p4.prog = "sync-script"
p4.connect
...
p4.disconnect
p4.prog -> aString
Get the name of the program as reported to the Perforce Server.
p4 = P4.new
p4.prog = "sync-script"
puts( p4.prog )
p4.progress= aProgress -> aProgress
Set the current progress indicator. This should be a subclass of
P4::Progress.
p4.progress -> aProgress
Get the current progress indicator.
p4.run_<cmd>( arguments ) -> anArray
This is equivalent to:
p4.run( "cmd", arguments... )
p4.run( aCommand, arguments... ) -> anArray
Base interface to all the run methods in this API. Runs the specified
Perforce command with the arguments supplied. Arguments may be in any
form as long as they can be converted to strings by
to_s.
The P4#run() method returns an array of
results whether the command succeeds or fails; the array may, however,
be empty. Whether the elements of the array are strings or hashes
depends on (a) server support for tagged output for the command, and
(b) whether tagged output was disabled by calling p4.tagged =
false.
In the event of errors or warnings, and depending on the exception
level in force at the time, P4#run() will
raise a P4Exception. If the current
exception level is below the threshold for the error/warning,
P4#run() returns the output as normal and the
caller must explicitly review P4#errors() and
P4#warnings() to check for errors or
warnings.
p4 = P4.new
p4.connect
spec = p4.run( "client", "-o" ).shift
p4.disconnect
Shortcuts are available for P4#run(). For
example:
p4.run_command( args )
is equivalent to:
p4.run( "command", args )
There are also some shortcuts for common commands such as editing
Perforce forms and submitting. Consequently, this:
p4 = P4.new
p4.connect
clientspec = p4.run_client( "-o" ).shift
clientspec[ "Description" ] = "Build client"
p4.input = clientspec
p4.run_client( "-i" )
p4.disconnect
may be shortened to:
p4 = P4.new
p4.connect
clientspec = p4.fetch_client
clientspec[ "Description" ] = "Build client"
p4.save_client( clientspec )
p4.disconnect
The following are equivalent:
p4.delete_<spectype>()p4.run( "<spectype>", "-d" )p4.fetch_<spectype>()p4.run( "<spectype>", "-o" ).shiftp4.save_<spectype>( spec )p4.input = specp4.run( "<spectype>", "-i" )
As the commands associated with
P4#fetch_<spectype>()
typically return only one item, these methods do not return an array,
but instead return the first result element.
For convenience in submitting changelists, changes returned by
P4#fetch_change() can be passed to
P4#run_submit. For example:
p4 = P4.new
p4.connect
spec = p4.fetch_changespec[ "Description" ] = "Automated change"
p4.run_submit( spec )
p4.disconnect
p4.run_filelog( fileSpec ) -> anArray
Runs a p4 filelog on the
fileSpec provided and returns an array of
P4::DepotFile results when executed in tagged
mode, and an array of strings when executed in non-tagged mode. By
default, the raw output of p4 filelog is tagged;
this method restructures the output into a more user-friendly (and
object-oriented) form.
p4 = P4.new
begin
p4.connect
p4.run_filelog( "index.html" ).shift.each_revision do
|r|
r.each_integration do
|i|
# Do something
end
end
rescue P4Exception
p4.errors.each { |e| puts( e ) }
ensure
p4.disconnect
end
p4.run_login( arg... ) -> anArray
Runs p4 login using a password or ticket set by the
user.
p4.run_password( oldpass, newpass ) -> anArray
A thin wrapper to make it easy to change your password. This method is
(literally) equivalent to the following code:
p4.input( [ oldpass, newpass, newpass ] )
p4.run( "password" )
For example:
p4 = P4.new
p4.password = "myoldpass"
begin
p4.connect
p4.run_password( "myoldpass", "mynewpass" )
rescue P4Exception
p4.errors.each { |e| puts( e ) }
ensure
p4.disconnect
end
p4.run_resolve( args ) [ block ] -> anArray
Interface to p4 resolve. Without a block, simply
runs a non-interactive resolve (typically an automatic resolve).
p4.run_resolve( "-at" )
When a block is supplied, the block is invoked once for each merge
scheduled by Perforce. For each merge, a
P4::MergeData object is passed to the block.
This object contains the context of the merge.
The block determines the outcome of the merge by evaluating to one of
the following strings:
Block string
Meaning
ay
Accept Yours.
at
Accept Theirs.
am
Accept Merge result.
ae
Accept Edited result.
s
Skip this merge.
q
Abort the merge.
For example:
p4.run_resolve() do
|md|
puts( "Merging..." )
puts( "Yours: #{md.your_name}" )
puts( "Theirs: #{md.their_name}" )
puts( "Base: #{md.base_name}" )
puts( "Yours file: #{md.your_path}" )
puts( "Theirs file: #{md.their_path}" )
puts( "Base file: #{md.base_path}" )
puts( "Result file: #{md.result_path}" )
puts( "Merge Hint: #{md.merge_hint}" )
result = md.merge_hint
if( result == "e" )
puts( "Invoking external merge application" )
result = "s" # If the merge doesn't work, we'll skip
result = "am" if md.run_merge()
end
result
end
p4.run_submit( [aHash], [arg...] ) -> anArray
Submit a changelist to the server. To submit a changelist, set the
fields of the changelist as required and supply any flags:.
change = p4.fetch_change
change._description = "Some description"
p4.run_submit( "-r", change )
You can also submit a changelist by supplying the arguments as you
would on the command line:
p4.run_submit( "-d", "Some description", "somedir/..." )
p4.run_tickets( ) -> anArray
Get a list of tickets from the local tickets file. Each ticket is a
hash object with fields for Host,
User, and Ticket.
p4.save_<spectype>( hashOrString, [options] ) -> anArray
The save_<spectype>
methods are shortcut methods that allow you to quickly update the
definitions of clients, labels, branches, etc. They are equivalent to:
p4.input = hashOrStringp4.run( "<spectype>", "-i" )
For example:
p4 = P4.new
begin
p4.connect
client = p4.fetch_client()
client[ "Owner" ] = p4.user
p4.save_client( client )
rescue P4Exception
p4.errors.each { |e| puts( e ) }
ensure
p4.disconnect
end
p4.server_case_sensitive? -> aBool
Detects whether or not the server is case-sensitive.
p4.server_level -> anInteger
Returns the current Perforce server level. Each iteration of the
Perforce Server is given a level number. As part of the initial
communication this value is passed between the client application and
the Perforce Server. This value is used to determine the communication
that the Perforce Server will understand. All subsequent requests can
therefore be tailored to meet the requirements of this Server level.
For more information, see:
http://kb.perforce.com/article/571
p4.server_unicode? -> aBool
Detects whether or not the server is in unicode mode.
p4.set_env= ( aString, aString ) -> aBool
On Windows or OS X, set a variable in the registry or user
preferences. To unset a variable, pass an empty string as the second
argument. On other platforms, an exception is raised.
p4 = P4.new
p4.set_env = ( "P4CLIENT", "my_workspace" )
p4.set_env = ( "P4CLIENT", "" )
p4.streams= -> aBool
Enable or disable support for streams. By default, streams support is
enabled at 2011.1 or higher (P4#api_level()
>= 70). Raises a P4Exception if you
attempt to enable streams on a pre-2011.1 server. You can enable or
disable support for streams both before and after connecting to the
server.
p4 = P4.new
p4.streams = false
p4.streams? -> aBool
Detects whether or not support for Perforce Streams is enabled.
p4 = P4.new
puts ( p4.streams? )
p4.tagged = false
puts ( p4.streams? )
p4.tagged( aBool ) { block }
Temporarily toggles the use of tagged output for the duration of the
block, and then resets it when the block terminates.
p4.tagged= aBool -> aBool
Sets tagged output. By default, tagged output is on.
p4 = P4.new
p4.tagged = false
p4.tagged? -> aBool
Detects whether or not you are in tagged mode.
p4 = P4.new
puts ( p4.tagged? )
p4.tagged = false
puts ( p4.tagged? )
p4.ticketfile= aString -> aString
Sets the location of the P4TICKETS file.
p4 = P4.new
p4.ticketfile = "/home/bruno/tickets"
p4.ticketfile -> aString
Get the path to the current P4TICKETS file.
p4 = P4.new
puts( p4.ticketfile )
p4.track= -> aBool
Instruct the server to return messages containing performance tracking
information. By default, server tracking is disabled.
p4 = P4.new
p4.track = true
p4.track? -> aBool
Detects whether or not performance tracking is enabled.
p4 = P4.new
p4.track = true
puts ( p4.track? )
p4.track = false
puts ( p4.track? )
p4.track_output -> anArray
If performance tracking is enabled with p4.track=,
returns a list of strings corresponding to the performance tracking
output for the most recently-executed command.
p4 = P4.new
p4.track = true
p4.run_info
puts ( p4.track_output[0].slice(0,3) ) # should be "rpc"
p4.user= aString -> aString
Set the Perforce username. If not called, defaults to the value of
P4USER taken from any P4CONFIG file
present, or from the environment as per the usual Perforce convention.
Must be called before connecting to the Perforce server.
p4 = P4.new
p4.user = "bruno"
p4.connect
...
p4.disconnect
p4.user -> aString
Returns the current Perforce username.
p4 = P4.new
puts( p4.user )
p4.version= aString -> aString
Set the version of your script, as reported to the Perforce Server.
p4.version -> aString
Get the version of your script, as reported to the Perforce Server.
p4.warnings -> anArray
Returns the array of warnings that arose during execution of the last
command.
p4 = P4.new
begin
p4.connect
p4.exception_level( P4::RAISE_ALL ) # File(s) up-to-date is a warning
files = p4.run_sync
rescue P4Exception => ex
p4.warnings.each { |w| puts( w ) }
ensure
p4.disconnect
end
Class P4Exception
Shallow subclass of RuntimeError to be used
for catching Perforce-specific errors. Doesn't contain any extra
information. See P4#errors() and
P4#warnings for details of the errors giving rise
to the exception.
Class Methods
None.
Instance Methods
None.
Class P4::DepotFileDescription
Utility class providing easy access to the attributes of a file in a
Perforce depot. Each P4::DepotFile object contains
summary information about the file, and a list of revisions
(P4::Revision objects) of that file. Currently,
only the P4#run_filelog() method returns an
array of P4::DepotFile objects.
Class Methods
None.
Instance Methodsdf.depot_file -> aString
Returns the name of the depot file to which this object refers.
df.each_revision { |rev| block } -> revArray
Iterates over each revision of the depot file.
df.revisions -> aArray
Returns an array of revisions of the depot file.
Class P4::RevisionDescription
Utility class providing easy access to the revisions of a file in a
Perforce depot. P4::Revision objects can store basic
information about revisions and a list of the integrations for that
revision. Created by P4#run_filelog().
Class Methods
None.
Instance Methodsrev.action -> aString
Returns the name of the action which gave rise to this revision of the
file.
rev.change -> aNumber
Returns the change number that gave rise to this revision of the file.
rev.client -> aString
Returns the name of the client from which this revision was submitted.
rev.depot_file -> aString
Returns the name of the depot file to which this object refers.
rev.desc -> aString
Returns the description of the change which created this revision.
Note that only the first 31 characters are returned unless you use
p4 filelog -L for the first 250 characters, or
p4 filelog -l for the full text.
rev.digest -> aString
Returns the MD5 digest for this revision of the file.
rev.each_integration { |integ| block } -> integArray
Iterates over each the integration records for this revision of the
depot file.
rev.filesize -> aNumber
Returns size of this revision.
rev.integrations -> integArray
Returns the list of integrations for this revision.
rev.rev -> aNumber
Returns the number of this revision of the file.
rev.time -> aTime
Returns the date/time that this revision was created.
rev.type -> aString
Returns this revision's Perforce filetype.
rev.user -> aString
Returns the name of the user who created this revision.
Class P4::IntegrationDescription
Utility class providing easy access to the details of an integration
record. Created by P4#run_filelog().
Class Methods
None.
Instance Methodsinteg.how -> aString
Returns the type of the integration record - how that record was
created.
integ.file -> aPath
Returns the path to the file being integrated to/from.
integ.srev -> aNumber
Returns the start revision number used for this integration.
integ.erev -> aNumber
Returns the end revision number used for this integration.
Class P4::MapDescription
The P4::Map class allows users to create and work
with Perforce mappings, without requiring a connection to a Perforce
server.
Class MethodsMap.new ( [ anArray ] ) -> aMap
Constructs a new P4::Map object.
Map.join ( map1, map2 ) -> aMap
Join two P4::Map objects and create a third.
The new map is composed of the left-hand side of the first mapping, as
joined to the right-hand side of the second mapping. For example:
# Map depot syntax to client syntax
client_map = P4::Map.new
client_map.insert( "//depot/main/...", "//client/..." )
# Map client syntax to local syntax
client_root = P4::Map.new
client_root.insert( "//client/...", "/home/bruno/workspace/..." )
# Join the previous mappings to map depot syntax to local syntax
local_map = P4::Map.join( client_map, client_root )
local_path = local_map.translate( "//depot/main/www/index.html" )
# local_path is now /home/bruno/workspace/www/index.html
Instance Methodsmap.clear -> true
Empty a map.
map.count -> anInteger
Return the number of entries in a map.
map.empty? -> aBool
Test whether a map object is empty.
map.insert( aString, [ aString ] ) -> aMap
Inserts an entry into the map.
May be called with one or two arguments. If called with one argument,
the string is assumed to be a string containing either a half-map, or
a string containing both halves of the mapping. In this form, mappings
with embedded spaces must be quoted. If called with two arguments,
each argument is assumed to be half of the mapping, and quotes are
optional.
# called with two arguments:
map.insert( "//depot/main/...", "//client/..." )
# called with one argument containing both halves of the mapping:
map.insert( "//depot/live/... //client/live/..." )
# called with one argument containing a half-map:
# This call produces the mapping "depot/... depot/..."
map.insert( "depot/..." )
map.translate ( aString, [ aBool ] )-> aString
Translate a string through a map, and return the result. If the
optional second argument is true, translate forward, and if it is
false, translate in the reverse direction. By default, translation is
in the forward direction.
map.includes? ( aString ) -> aBool
Tests whether a path is mapped or not.
if( map.includes?( "//depot/main/..." ) )
...
end
map.reverse -> aMap
Return a new P4::Map object with the left and
right sides of the mapping swapped. The original object is unchanged.
map.lhs -> anArray
Returns the left side of a mapping as an array.
map.rhs -> anArray
Returns the right side of a mapping as an array.
map.to_a -> anArray
Returns the map as an array.
Class P4::MergeDataDescription
Class containing the context for an individual merge during execution of
a p4 resolve.
Class Methods
None.
Instance Methodsmd.your_name() -> aString
Returns the name of "your" file in the merge. This is typically a path
to a file in the workspace.
p4.run_resolve() do
|md|
yours = md.your_name
md.merge_hint # merge result
end
md.their_name() -> aString
Returns the name of "their" file in the merge. This is typically a
path to a file in the depot.
p4.run_resolve() do
|md|
theirs = md.their_name
md.merge_hint # merge result
end
md.base_name() -> aString
Returns the name of the "base" file in the merge. This is typically a
path to a file in the depot.
p4.run_resolve() do
|md|
base = md.base_name
md.merge_hint # merge result
end
md.your_path() -> aString
Returns the path of "your" file in the merge. This is typically a path
to a file in the workspace.
p4.run_resolve() do
|md|
your_path = md.your_path
md.merge_hint # merge result
end
md.their_path() -> aString
Returns the path of "their" file in the merge. This is typically a
path to a temporary file on your local machine in which the contents
of P4::MergeData#their_name() have been
loaded.
p4.run_resolve() do
|md|
their_name = md.their_name
their_file = File.open( md.their_path )
md.merge_hint # merge result
end
md.base_path() -> aString
Returns the path of the base file in the merge. This is typically a
path to a temporary file on your local machine in which the contents
of P4::MergeData#base_name() have been
loaded.
p4.run_resolve() do
|md|
base_name = md.base_name
base_file = File.open( md.base_path )
md.merge_hint # merge result
end
md.result_path() -> aString
Returns the path to the merge result. This is typically a path to a
temporary file on your local machine in which the contents of the
automatic merge performed by the server have been loaded.
p4.run_resolve() do
|md|
result_file = File.open( md.result_path )
md.merge_hint # merge resultend
md.merge_hint() -> aString
Returns the hint from the server as to how it thinks you might best
resolve this merge.
p4.run_resolve() do
|md|
puts ( md.merge_hint ) # merge result
end
md.run_merge() -> aBool
If the environment variable P4MERGE is defined,
P4::MergeData#run_merge() invokes the
specified program and returns a boolean based on the return value of
that program.
p4.run_resolve() do
|md|
if ( md.run_merge() )
"am"
else
"s"
end
end
Class P4::MessageDescriptionP4::Message objects contain error or other
diagnostic messages from the Perforce Server; retrieve them by using the
P4#messages() method.
Script writers can test the severity of the messages in order to
determine if the server message consisted of command output
(E_INFO), warnings, (E_WARN), or
errors (E_FAILED/E_FATAL).
Class methods
None.
Instance methodsmessage.severity() -> anInteger
Severity of the message, which is one of the following values:
Value
Meaning
E_EMPTY
No error
E_INFO
Informational message only
E_WARN
Warning message only
E_FAILED
Command failed
E_FATAL
Severe error; cannot continue.
message.generic() -> anInteger
Returns the generic class of the error.
message.msgid() -> anInteger
Returns the unique ID of the message.
message.to_s() -> aString
Converts the message into a string.
message.inspect() -> aString
To facilitate debugging, returns a string that holds a formatted
representation of the entire P4::Message
object.
Class P4::OutputHandlerDescription
The P4::OutputHandler class is a handler class
that provides access to streaming output from the server. After defining
the output handler, set P4#handler() to an
instance of a subclass of P4::OutputHandler (or
use a p4.with_handler( handler ) block) to enable
callbacks.
By default, P4::OutputHandler returns
P4::REPORT for all output methods. The different
return options are:
Value
Meaning
P4::REPORT
Messages added to output.
P4::HANDLED
Output is handled by class (don't add message to output).
P4::CANCEL
Operation is marked for cancel, message is added to output.
Class Methodsnew P4::MyHandler.new -> aP4::OutputHandler
Constructs a new subclass of P4::OutputHandler.
Instance MethodsoutputBinary -> int
Process binary data.
outputInfo -> int
Process tabular data.
outputMessage -> int
Process informational or error messages.
outputStat -> int
Process tagged data.
outputText -> int
Process text data.
Class P4::ProgressDescription
The P4::Progress class is a handler class that
provides access to progress indicators from the server. After defining
the output handler, set P4#progress() to an
instance of a subclass of P4::Progress (or use a
p4.with_progress( progress ) block) to enable
callbacks.
You must implement all five of the following methods:
init(), description(),
update(), total(), and
done(), even if the implementation consists of
trivially returning 0.
Class Methodsnew P4::MyProgress.new -> aP4::Progress
Constructs a new subclass of P4::Progress.
Instance Methodsinit -> int
Initialize progress indicator.
description -> int
Description and type of units to be used for progress reporting.
update -> int
If non-zero, user has requested a cancellation of the operation.
total -> int
Total number of units expected (if known).
done -> int
If non-zero, operation has failed.
Class P4::SpecDescription
The P4::Spec class is a hash containing key/value
pairs for all the fields in a Perforce form. It provides two things over
and above its parent class (Hash):
Fieldname validation. Only valid field names may be set in a
P4::Spec object. Note that only the field
name is validated, not the content.
Accessor methods for easy access to the fields.
Class Methodsnew P4::Spec.new( anArray ) -> aP4::Spec
Constructs a new P4::Spec object given an array
of valid fieldnames.
Instance Methodsspec._<fieldname> -> aValue
Returns the value associated with the field named
<fieldname>. This is equivalent to
spec[ "<fieldname>" ]
with the exception that when used as a method, the fieldnames may be
in lowercase regardless of the actual case of the fieldname.
client = p4.fetch_client()
root = client._root
desc = client._description
spec._<fieldname>= aValue -> aValue
Updates the value of the named field in the spec. Raises a
P4Exception if the fieldname is not
valid for specs of this type.
client = p4.fetch_client()
client._root = "/home/bruno/new-client"
client._description = "My new client spec"
p4.save_client( client )
spec.permitted_fields -> anArray
Returns an array containing the names of fields that are valid in this
spec object. This does not imply that values for all of these fields
are actually set in this object, merely that you may choose to set
values for any of these fields if you want to.
client = p4.fetch_client()
spec.permitted_fields.each do
| field |
printf ( "%14s = %s\n", field, client[ field ] )
end