P4Ruby

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.

P4Ruby is designed to work in a Ruby-like way as far as possible. It has support for Ruby exceptions to make error handling as easy as possible and even distinguishes between errors and warnings - allowing you to ignore warnings whilst still trapping errors.

If you're new to P4Ruby, the best place to start is with the documentation for the P4 class. This is the main Ruby class defined by P4Ruby.

Features at a glance

Connect once and run several commands.
The output of commands is returned as a Ruby array.
The elements of the array returned are strings or, where appropriate, Ruby hashes.
Tagged mode output (i.e. 'p4 fstat' or 'p4 -Ztag changes') is returned as a Ruby hash. See P4#tagged.
Optionally converts all Perforce forms (changes/clients/labels etc.) into Ruby hashes and back again. This allows you to fetch the existing definition of an object, alter one or more fields in the hash and use the modified hash to update Perforce. See P4#parse_forms.
Thread-safe and thread-friendly - have multiple instances of the P4 class running in different threads.
Exception-based error handling. Trap P4Exceptions for complete, high-level error handling.
Connect once and run several commands

Classes Defined

P4
The main class used for executing Perforce commands. Almost everything you do with P4Ruby will involve this class. If you're new to P4Ruby, start here.
P4DepotFile
Utility class allowing quick and easy access to the attributes of a file in the depot. Returned by P4#run_filelog.
P4Exception
Used as part of error reporting and is derived from the Ruby RuntimeError class.
P4Integration
Utility class allowing quick and easy access to the attributes of an integration record for a revision of a file in the depot. Returned by P4#run_filelog.
P4Revision
Utility class allowing quick and easy access to the attributes of a revision of a file in the depot. Returned by P4#run_filelog.
P4::MergeData
Class encapsulating the context of an individual merge during execution of a 'p4 resolve'. Passed as a parameter to the block passed to P4#run_resolve.
P4::Spec
Subclass of hash allowing quick and easy access to the fields in a Perforce form (spec). Also checks that the fields that are set are valid fields for the given type of spec. Returned by P4#fetch_<spec_type>.

Support

Sign up to the p4ruby mailing list and post your question to the list. Alternatively, you can contact the author Tony Smith directly for support. I'll respond as quickly as I'm able. All feedback and suggestions are most welcome.

Requirements

Building P4Ruby requires version 2001.1 or later of the Perforce API and a C++ compiler - ideally the same C++ compiler used to build the Perforce API.

Running P4Ruby requires a 99.2 or later Perforce server to be of any real use to you. Earlier servers did not support tagged output in the same way.

The more recent your server, the better as tagged output support is continually being improved.

P4Ruby - Programmers Guide

Contents

Introduction

Features at a glance

Classes Defined

Support

Requirements