P4/Ruby - P4 class

Class

< Object

Description

Main interface to the Perforce client API.

Class Methods

identify	P4.identify -> aString

Return the version of P4/Ruby you are using - for diagnostic purposes.

    ruby -rP4 -e 'puts( P4.identify )'

new
P4.new -> aP4

Constructs a new P4 object.

    p4 = P4.new()

Instance Methods

client=
p4.client = aString -> true

Set the name of the clientspec 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 you connect.

    p4 = P4.new
    p4.client = "www"
    p4.connect
    p4.run_sync
    p4.disconnect

client?
p4.client? -> aString

Get the name of the Perforce client currently in use

    p4 = P4.new
    puts( p4.client? )

cwd=
p4.cwd = aString -> true

Sets the current working directory. 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/tony"

cwd?
p4.cwd? -> aString

Get the current working directory

    p4 = P4.new
    puts( p4.cwd? )

debug=
p4.debug = aNumber -> true

Set debug level. Debug output is written to $stderr. Debug levels are:

      0. No debug output (default)
      1. Log connect/disconnect and command execution
      2. Log user interface RPC callbacks
      3. Log Ruby garbage collection

Note that levels are cumulative so level 3 includes levels 2 and 1.

    p4 = P4.new
    p4.debug = 1
    p4.connect
    p4.run_sync
    p4.disconnect

errors
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( 1 ) # to ignore "File(s) up-to-date"
      p4.run_sync
    rescue P4Exception 
      p4.errors.each { |e| puts( e ) }
    ensure
      files = p4.output
      p4.disconnect
    end

exception_level=
p4.exception_level = aNumber -> aNumber

Configures the events which give rise to exceptions.

Setting the exception level to zero disables all exception raising and makes the interface completely procedural.

Setting the exception level to 1 causes exceptions to be raised when errors are encountered.

Setting the exception level to 2 causes exceptions to be raised for both errors and warnings. This is the default.

    p4 = P4.new
    p4.exception_level = 1 	# or p4.exception_level( 1 )
    p4.connect			# P4Exception on failure
    p4.run_sync			# File(s) up-to-date is a warning so
    				# no exception is raised
    p4.disconnect

exception_level?
p4.exception_level? -> aNumber

Returns the current exception level.

host=
p4.host = aString -> true

Set the name of the current host. If not called, defaults to P4HOST taken from any P4CONFIG file in effect, then P4HOST in the environment and finally the operating system host name.

    p4 = P4.new
    p4.host = "perforce.smee.org"
    p4.connect
    ...
    p4.disconnect

host?
p4.host? -> aString

Get the current hostname

    p4 = P4.new
    puts( p4.host? )

input
p4.input( aString ) -> true or false
p4.input( aHash ) -> true or false

Call prior to running a command of the form "p4 cmd -i" to provide input to Perforce. You may pass a string, or a hash returned from a previous "p4 cmd -o" when using parse_forms mode.

    p4 = P4.new
    p4.parse_forms
    p4.connect

    change = p4.run_change( "-o" ).shift
    change[ "Description" ] = "Autosubmitted changelist"

    p4.input( change )
    p4.run_submit( "-i" )

    p4.disconnect

Note that P4#input may raise a P4Exception in exception levels 1 and 2 if errors are encountered parsing the supplied data. Otherwise, returns true if the input is acceptable.

output
p4.output -> anArray

Get the results of the previous command. Returns an array containing the output of the command. Useful in a rescue block when a command has partially worked, and you still need to look at the command output.

    p4 = P4.new
    begin
      p4.connect
      p4.exception_level( 1 ) # to ignore "File(s) up-to-date"
      files = p4.run_sync
    rescue P4Exception => ex
      files = p4.output
      if files.length
	puts( "Sync succeeded with errors" )
      else
        puts( "Sync failed!" )
      end
    ensure
      p4.disconnect
    end

parse_forms
p4.parse_forms -> true

Extends the capabilities of tagged output to include Perforce forms. Forms returned by Perforce in response to commands such as "p4 client -o" will be parsed and returned to the caller as a Ruby hash containing keys for each of the fields on the form. Where a form element may contain more than one value, the hash value is an array containing the form elements. parse_forms implies the use of tagged.

    p4 = P4.new
    p4.parse_forms
    p4.connect
    clientspec = p4.run_client( "-o" ).shift
    puts( clientspec[ "Options" ] )
    p4.disconnect

Such parsed forms are also acceptable as input to commands of the form "p4 XXXX -i". For example, to change the root of a clientspec you could use:

    p4 = P4.new
    p4.parse_forms
    p4.connect
    spec = p4.run_client( "-o" ).shift
    spec[ "Root" ] = "/home/my/new/root" 
    p4.input( spec )
    p4.run_client( "-i" )
    p4.disconnect

password=
p4.password = aString -> true

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.

    p4 = P4.new
    p4.password = "mypass"
    p4.connect

password?
p4.password? -> aString

Get the current password - in plain text.

    p4 = P4.new
    puts( p4.password? )

port=
p4.port = aString -> true

Set the host and port address 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

port?
p4.port? -> aString

Get the address of the current Perforce server.

    p4 = P4.new
    puts( p4.port? )

run
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 you like as long as it responds nicely to "to_s".

If the command succeeds without errors or warnings, then run returns an array of results. Whether the elements of the array are strings or hashes depends on (a) the command executed and (b) whether tagged() or parse_forms() have been called.

The array that is returned is equivalent to that returned by "p4.output".

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, then 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

Through the magic of Object#method_missing, you can save yourself some typing as

    p4.run_XXX( args )

is translated into

    p4.run( "XXX", args )

There are also some shortcuts for common commands such as editing Perforce forms and submitting. So this:

    p4 = P4.new
    p4.parse_forms
    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.parse_forms
    p4.connect
    clientspec = p4.fetch_client
    clientspec[ "Description" ] = "Build client"
    p4.save_client( clientspec )
    p4.disconnect

In fact, the following are equivalent:

p4.fetch_xxx p4.run_xxx( "-o ").shift

p4.save_xxx( spec ) p4.input( spec )
p4.run_xxx( "-i" ).shift

Note that the fetch_xxx methods do not return an array as typically there is only one result item from such commands. Accordingly, they return the first result element.

There is also a special shortcut for submitting

    p4 = P4.new
    p4.parse_forms
    p4.connect
    spec = p4.fetch_change
    spec[ "Description" ] = "Automated change"
    p4.submit_spec( spec )
    p4.disconnect

tagged
p4.tagged -> true

Enables tagged output. Responses to Perforce commands which support tagged output will be converted into Ruby hashes. Must be called before connecting to the server.

    p4 = P4.new
    p4.tagged
    p4.connect
    ...
    p4.disconnect

user=
p4.user = aString -> true

Set your Perforce username. If not set defaults to the value of P4USER taken from any P4CONFIG file in effect, then the value of P4USER in your environment and lastly your operating system user name.

    p4 = P4.new
    p4.user = "tony"
    p4.connect
    ...
    p4.disconnect

user?
p4.user? -> aString

Returns your current Perforce user name

    p4 = P4.new
    puts( p4.user? )

warnings
p4.warnings -> anArray

Returns the array of warnings which arose during execution of the last command.

    p4 = P4.new
    begin
      p4.connect
      p4.exception_level( 0 ) # "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

input	p4.input( aString ) -> true or false p4.input( aHash ) -> true or false

p4.fetch_xxx	p4.run_xxx( "-o ").shift
p4.save_xxx( spec )	p4.input( spec ) p4.run_xxx( "-i" ).shift

Description

See Also

Class Methods

identify

new

Instance Methods

client=

client?

cwd=

cwd?

debug=

errors

exception_level=

exception_level?

host=

host?

input

output

parse_forms

password=

password?

port=

port?

run

tagged

user=

user?

warnings