P4Ruby: Ruby interface to the Perforce API

Contents

1. Introduction
2. License
3. Support
4. Documentation
5. Building P4Ruby
6. Downloads
7. Sample Code
8. P4Ruby Script Library
9. Porting
10. Credits

Introduction

So, what's it all about? Well in a nutshell P4Ruby allows you to write beautiful Ruby code that interacts with a Perforce server. The main features are:

• Get Perforce data and forms in hashes and arrays
• Edit Perforce forms by modifying hashes
• Exception based error handling
• Ignore warnings (like "File(s) up-to-date." on a sync)
• Run as many commands on a connection as you want to

Writing Ruby code is a joy for all programmers, and P4Ruby makes that experience available to Perforce users. Enjoy it!

Licence

This extension is distributed under the terms of this license, which is a BSD-like license. You use it at your own risk.

Support

Documentation

• P4Ruby Programmers Guide
• Programming Ruby (online edition)

Building P4Ruby

1. Download and install Ruby

FreeBSD users can just use pkg_add to install ruby as there's a FreeBSD port for it.

Windows users can download a Windows installer for Ruby from http://rubyinstaller.rubyforge.org/wiki/wiki.pl They can also grab a P4Ruby installer from the links below - useful if you don't have Visual Studio installed. If you do this, then obviously you don't need to do any of the other build steps.

Otherwise you can download the source for Ruby from http://www.ruby-lang.org which is the main Ruby home page.

2. Download P4Ruby

If you chose to use the Windows installer then the process ends here. You're ready to start using P4Ruby. What follows is only applicable to those building P4Ruby from source.

3. Get the Perforce API

See the Porting section below to help you find the right Perforce API build for your platform.

Then go to the Perforce download site and grab the p4api.tar file for your platform. Try to get the latest available release, but certainly no older than 2001.1.

Extract the files in the p4api.tar tarfile (WinZip can handle it for Windows users) into a new empty directory and remember its location.

4. Build and install P4Ruby

Follow the build instructions in P4Ruby's README file.

Downloads

Current Builds

Older Stable Builds

To find out what's changed, read the change log.

Sample code

  require "P4"

  template 	= "my-client-template"
  client_root	= "c:\\p4-work"

  p4 = P4.new
  p4.parse_forms
  p4.connect

  begin
    # Run a "p4 client -t template -o" and convert it into a Ruby hash
    spec = p4.fetch_client( "-t", template )

    # Now edit the fields in the form
    spec[ "Root" ] 	= client_root
    spec[ "Options" ]	= spec[ "Options" ].sub( "normdir", "rmdir" )

    # Now save the udpated spec
    p4.save_client( spec )

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

P4Ruby Script Library

Credits

Thanks to Dave Thomas and Andy Hunt at The Pragmatic Programmers for their superb book and kindly giving me permission to use the funky Ruby image at the top of this page.

And of course, thanks to Matz for Ruby.