p4.cc #14

# Change User Description Committed
#14 1750 Tony Smith Build environment tweaks.
#13 1529 Tony Smith Remove useless initialize method from the P4 class.
Previously it
did nothing, and it's not required, so there's no functional change
#12 1426 Tony Smith Cleaned up the debug output a little.
Introduced some debug levels
so you can decide (roughly) what output you want to see. Level 1
shows command execution, connect and disconnect. Level 2 includes
Level 1 and also shows the RPC callbacks as they happen. Level 3
includes 1 and 2 and also shows when Ruby garbage collection takes
place.

Converted all the simple methods of the form P4#meth( arg ) to
       aliases for P4#meth=. Added P4#debug= to complete the scheme. The
P4#meth( arg ) forms are now deprecated. i.e. you should use:

    p4.user = "tony"

and not:

    p4.user( "tony" )

It's just more Ruby-like.
#11 1423 Tony Smith Refine the argument handling in P4#run.
Now take args as a Ruby
array rather than a C array which makes dealing with arguments
which are themselves arrays easier.

P4#run just calls Array#flatten() to sort out any nested arrays
and then Array#length gives us the true argument count which is
used to construct the C array for passing to the Perforce API.
Much simpler.
#10 1275 Tony Smith Added synonym methods for:

   p4.cwd     / p4.cwd=
   p4.client     / p4.client=
   p4.host     / p4.host=
   p4.password    / p4.password=
   p4.port    / p4.port=
   p4.user    / p4.user=

And for exceptions:

   p4.exception_level / p4.exception_level=

   and p4.exception_level? so you can test the current exception
   level

       p4.exception_level and p4.exception_level=  now return the
exception level rather than true.
#9 1168 Tony Smith Bug fix.
P4#run was not handling arrays passed as arguments -
which is what P4#method_missing does. It was just calling to_s
on all its args, and Array#to_s joins all the elements of the
array so if you passed more than one argument to a run_xxx method,
it was joining them together.

This change involves flattening an array of Ruby objects (some of
which could be arrays themselves) into a single C++ array before
executing the command.
#8 1166 Tony Smith Followup to previous change.

Simplify the interface to getting results/errors and warnings.
No need for the P4Result class anymore so that's gone (though
it's still there as a C++ class because it's useful) and so
is P4#result. Now you get your errors/warnings and results using
P4#errors, P4#warnings and P4#output all of which return arrays.
#7 1165 Tony Smith Minor reshuffle.
Added the ability to disable exceptions
completely if you don't like them or to have them raised only
for errors (and not for warnings). Removed P4#warnings
interface and replaced it with P4#exception_level.

Some minor doc tweaks to go with the above change
#6 1164 Tony Smith Reworked exception handling (hopefully for the last time) in
P4/Ruby. Now exceptions are raised on completion of Perforce
commands if any errors or warnings were received as part of
executing the command.

This change also adds documentation, and indexes the Ruby
interface off my main page. Bad form to combine so many changes
in one changelist, but it's getting late and I want to get
them submitted!
#5 1083 Tony Smith Sweeping change to exception handling and garbage collection.

Exceptions are no longer raised for errors encoutered during
execution of Perforce commands as that was causing processing
to abort at the first error when several success messages may
have been close behind.

Now exceptions are raised for events which are fatal to the
execution of commands - such as failure to connect to the
Perforce server for example. For other errors, the user must
call "p4.errors? " to determine whether or not errors occured
and "p4.errors" to get an array of error messages. You can
of course then raise exceptions yourself if you want to:

begin
    client = p4.fetch_client
    if p4.errors?
    raise P4Exception, "p4 client -o failed"
    end
rescue P4Exception => m
    puts( m  )
    p4.errors.each { |e| puts( e ) }
end

version.h got renamed because it conflicts with ruby's own
version.h file. We may need to look in there at some point
for ruby's version so I'm getting it out of the way now.

       Added gc_hack.h to make sure that GC works properly on all
platforms now so Ruby shouldn't nuke any objects we're holding now.
#4 1081 Tony Smith Debugging and identification support.
Adds two new methods:

P4#identify()
P4#debug( int )
#3 1027 Tony Smith Rework structure slightly.
What was P4.so is now called
P4api.so and a new P4.rb module is added. P4api.so
contains the raw bridge to the Perforce API whilst P4.rb
contains extensions to it written purely in Ruby. Both
define and extend the P4 class and P4.rb requires P4api.so
so user code is unaffected.

The intent is to give me a place to write Ruby code rather
than having to work solely in C++.

The first method added using this new structure is
P4#method_missing, so now Perforce commands all appear as
methods on the P4 object (prefixed by "run_" ). e.g

    p4 = P4.new
    p4.run_info()
    p4.run_users()
    p4.run_protect( "-o" )

This change also adds support for shortcut methods for
form editing. fetch* and save* methods have been added as
shortcuts for "p4 <cmd> -o" and "p4 <cmd> -i" respectively.
For example:

    p4 = P4.new
    p4.parse_forms()

    client_spec = p4.fetch_client()
    client_spec[ "Owner" ] = tony
    p4.save_client( client_spec )

Note that unlike the run* methods, these accessor methods
do not return an array, but return a single result - a string
normally, or a hash in parse_forms mode.

Ruby's arcane build/install system means that you have to
install the P4.rb file yourself. "make install" doesn't
take care of it.
#2 1019 Tony Smith Some porting work to get it to compile on NT.
mkmf stuff is still
rubbish on NT (<smug>as I told ruby-talk it would be</smug>) and
the generated makefile doesn't work at all. Had to figure it out
and build by hand - yuk.
#1 1015 Tony Smith First cut of Perforce bindings for the Ruby scripting language.
Similar functionality to the Perl API stuff, but "rubyfied".
Supports error reporting via exceptions, and presents tagged
output and parsed forms as hash structures, with nested arrays
where required.

Still early days so the docs are thin on the ground. See the
example.pl for a brief guide.

Built with Ruby 1.6.4 on Linux.  May still be some memory
management issues as the Ruby Garbage Collection API has
changed a little since the docs I've got and I've just
dodged garbage collection for now.

Not indexing this just yet.