P4/Ruby - P4 class

Contents

Class |  |  | P4 | < Object

#### Description

Main interface to the Perforce client API.

#### See Also

P4Exception P4DepotFile P4Revision P4Integration

#### 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