NAME

P4 - OO interface to the Perforce SCM System.

SYNOPSIS

  use P4;
  my $p4 = new P4;

  $p4->SetClient( $clientname );
  $p4->SetPort ( $p4port );
  $p4->SetPassword( $p4password );
  $p4->Init() or die( "Failed to connect to Perforce Server" );
  
  my $info = $p4->Run( "info" );
  $p4->Edit( "file.txt" ) or die( "Failed to edit file.txt" );
  $p4->Final();

DESCRIPTION

This module provides an OO interface to the Perforce SCM system which is more intuitive to Perl users than the P4::Client/P4::UI modules but a little less capable as it represents but one way of using P4::Client and P4::UI.

Methods are divided into the base methods and shortcuts. The shortcuts are intended to make scripts using this module easier by providing easy interfaces to common actions. They're just wrappers around the base methods though.

BASE METHODS

new()

        Constructor. The only method of this class you call
        directly.

P4::Dropped()

Returns true if the TCP/IP connection between client and server has been dropped.

P4::Final()

Terminate the connection and clean up. Should be called before exiting to cleanly disconnect.

P4::GetClient()

Returns the current Perforce client name. This may have previously been set by SetClient(), or may be taken from the environment or P4CONFIG file if any. If all that fails, it will be your hostname.

P4::GetCwd()

Returns the current working directory as your Perforce client sees it.

P4::GetHost()

Returns the client hostname. Defaults to your hostname, but can be overridden with SetHost()

P4::GetPassword()

Returns your Perforce password - in plain text if that's how it's stored and currently on all except Windows platforms, that's the way it's done. Taken from a previous call to SetPassword() or extracted from the environment ( $ENV{P4PASSWD} ), or a P4CONFIG file.

Note that the password is not transmitted in clear text.

P4::GetPort()

Returns the current address for your Perforce server. Taken from a previous call to SetPort(), or from $ENV{P4PORT} or a P4CONFIG file.

P4::Init()

Initializes the Perforce client and connects to the server. Returns false on failure and true on success.

P4::Run( cmd, [$arg...] )

Run a Perforce command returning the results. Check for errors using P4::ErrorCount(). Results are returned in scalar or array context, whichever you're using. Through the magic of the AutoLoader, you can also treat the Perforce commands as methods, so

$p4->Edit( "filename.txt );

is equivalent to

$p4->Run( "edit", "filename.txt" );

Note that $var = $p4->Info() returns a string containing all of the lines of output from Perforce. Whilst @var = $p4->Info() returns an array with each line of output in a separate element.

P4::SetClient( $client )

Sets the name of your Perforce client. If you don't call this method, then the clientname will default according to the normal Perforce conventions. i.e.

1. Value from file specified by P4CONFIG

2. Value from $ENV{P4CLIENT}

3. Hostname

P4::SetCwd( $path )

Sets the current working directory for the client. This should be called after the Init() and before the Run().

P4::SetPassword( $password )

Set the password for the Perforce user, overriding all defaults.

P4::SetPort( [$host:]$port )

Set the port on which your Perforce server is listening. Defaults to:

1. Value from file specified by P4CONFIG

2. Value from $ENV{P4PORT}

3. perforce:1666

P4::SetProtocol( $protflag, $value )

Set protocol options for this session. The most common protocol option is the "tag" option which requests tagged output format for commands which would otherwise get formatted output.

For example:

$p4->SetProtocol(tag,''); $p4->Init(); my @f = $p4->Fstat( "filename" ); my $c = $f[ 0 ]->{ 'clientFile' };

P4::SetUser( $username )

Set your Perforce username. Defaults to:

1. Value from file specified by P4CONFIG

2. Value from $ENV{P4USER}

3. OS username

SHORTCUT METHODS

The following methods are simply wrappers around the base methods designed to make common actions easy to code.

P4::Tag()

Equivalent to SetProtocol( "tag", "" ). Responses from commands that support tagged output will be in the form of a hash ref rather than plain text. Must be called prior to calling Init().

P4::ParseForms()

Request that forms returned by commands such as $p4->GetChange(), or $p4->Client( "-o" ) be parsed and returned as a hash reference for easy manipulation. Equivalent to calling SetProtocol( "tag", "" ) and SetProtocol( "specstring", "" ). Must be called prior to calling Init().

P4::GetChange()

Returns a change specification formatted either as a plain string in a scalar variable, or as a hashref if P4::ParseForms() has been called.

API Versions

This extension has been built and tested on the Perforce 2001.1 API, but should work with any recent version, certainly any release later than and including 99.2.

LICENCE

Copyright (c) 1997-2001, Perforce Software, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

AUTHOR

Tony Smith, Perforce Software ( tony@perforce.com )

SEE ALSO

perl(1), P4::Client(3), P4::UI(3), Perforce API documentation.