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.
|
•
|
make (or nmake on Windows)
|
require "P4"template = "my-client-template" client_root = 'c:\p4-work' p4 = P4.new p4.connect
# 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
|
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.
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.
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:
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:
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.
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:
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.newp4.api_level = 67 # Lock to 2010.1 format p4.connect ...
|
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.
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.newp4.client = "www" p4.charset = "iso8859-1" p4.connect p4.run_sync p4.disconnect
|
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.newp4.client = "www" p4.connect p4.run_sync p4.disconnect
|
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
|
The each_spectype methods are shortcut methods that allow you to quickly iterate through clients, labels, branches, etc. Valid
spectypes 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.
clients = p4.run_clientsclients.each do |c| client = p4.fetch_client( c['client'] ) # work with the retrieved client spec end
|
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.newbegin 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::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.newp4.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
|
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
p4 = P4.newbegin 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
|
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.
where spectype is the name of a Perforce spec, such as
client,
label, etc.
The format_spectype methods are shortcut methods that allow you to quickly fetch the definitions of clients, labels, branches, etc. They're equivalent to:
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.newp4.host = "workstation123.perforce.com" p4.connect ... p4.disconnect
|
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.
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.newbegin p4.connect p4.maxlocktime = 10000 # 10 seconds files = p4.run_sync rescue P4Exception => ex p4.errors.each { |e| $stderr.puts( e ) } ensure p4.disconnect end
|
Get the current maxlocktime setting
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.newbegin p4.connect p4.maxresults = 100 files = p4.run_sync rescue P4Exception => ex p4.errors.each { |e| $stderr.puts( e ) } ensure p4.disconnect end
|
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.newbegin p4.connect p4.maxscanrows = 100 files = p4.run_sync rescue P4Exception => ex p4.errors.each { |e| $stderr.puts( e ) } ensure p4.disconnect end
|
p4 = P4.newp4.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 )
|
This is equivalent to parse_spec(spectype, aString).
Where spectype is one of
client,
branch,
label, and so on.
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.newp4.password = "mypass" p4.connect p4.run_login
|
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.
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.newp4.port = "localhost:1666" p4.connect ... p4.disconnect
|
p4 = P4.newp4.prog = "sync-script" p4.connect ... p4.disconnect
|
This is equivalent to p4.run (cmd, arguments... ).
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,
run will raise a
P4Exception. If the current exception level is below the threshold for the error/warning,
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.newp4.connect spec = p4.run( "client", "-o" ).shift p4.disconnect
|
p4 = P4.newp4.connect clientspec = p4.run_client( "-o" ).shift clientspec[ "Description" ] = "Build client" p4.input = clientspec p4.run_client( "-i" ) p4.disconnect
|
p4 = P4.newp4.connect clientspec = p4.fetch_client clientspec[ "Description" ] = "Build client" p4.save_client( clientspec ) p4.disconnect
|
As the commands associated with fetch_spectype typically return only one item, these methods do not return an array, but instead return the first result element.
p4 = P4.newp4.connect spec = p4.fetch_change spec[ "Description" ] = "Automated change" p4.run_submit( spec ) p4.disconnect
|
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.newbegin 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
|
Runs p4 login using a password or ticket set by the user.
p4 = P4.newp4.password = "myoldpass" begin p4.connect p4.run_password( "myoldpass", "mynewpass" ) rescue P4Exception p4.errors.each { |e| puts( e ) } ensure p4.disconnect end
|
Interface to p4 resolve. Without a block, simply runs a non-interactive resolve (typically an automatic resolve).
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.
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
|
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 = P4.newbegin 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
|
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.
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.newp4.set_env = ( "P4CLIENT", "my_workspace" ) p4.set_env = ( "P4CLIENT", "" )
|
Enable or disable support for streams. By default, streams support is enabled at 2011.1 or higher (
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.newputs ( p4.streams? ) p4.tagged = false puts ( p4.tagged? )
|
p4 = P4.newputs ( p4.tagged? ) p4.tagged = false puts ( p4.tagged? )
|
p4 = P4.newputs( p4.ticketfile ) p4.ticketfile = "/home/tony/tickets"
|
p4 = P4.newp4.track = true puts ( p4.track? ) p4.track = false puts ( p4.track? )
|
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.newp4.track = true p4.run_info puts ( p4.track_output[0].slice(0,3) ) # should be "rpc"
|
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.newbegin 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
|
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.
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.
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
run_filelog.
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.
The P4::Map class allows users to create and work with Perforce mappings, without requiring a connection to a Perforce server.
Constructs a new P4::Map object.
Join two P4::Map objects and create a third.
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.
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.
Return a new P4::Map object with the left and right sides of the mapping swapped. The original object is unchanged.
p4.run_resolve() do |md| their_name = md.their_name their_file = File.open( md.their_path ) md.merge_hint # merge result end
|
p4.run_resolve() do |md| base_name = md.base_name base_file = File.open( md.base_path ) md.merge_hint # merge result end
|
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 result end
|
If the environment variable P4MERGE is defined,
run_merge() invokes the specified program and returns a boolean based on the return value of that program.
P4::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).
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
REPORT for all output methods. The different return options are:
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.
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):
Constructs a new P4::Spec object given an array of valid fieldnames.
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.
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/tony/new-client" client._description = "My new client spec" p4.save_client( client )
|
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.
Copyright 2008-2014 Perforce Software.
