/ 
VCP-0.9
/ VCP::Rev

NAME

VCP::Rev - VCP's concept of a revision

SYNOPSIS

use VCP::Rev;

use VCP::Rev qw( iso8601format );

my $r = VCP::Rev->new;

DESCRIPTION

A data structure that represents a revision to a file (but, technically, not a version of a file, though the two are often synonymous).

METHODS

new

Creates an instance, see subclasses for options.

my $rev = VCP::Rev->new(
   name => 'foo',
   time => $commit_time,
   ...
) ;
fields

Returns a list of field names, with "@" prepended to any array fields.

serialize

Converts the revision metadata to a set of "name=value" strings suitable for emitting to a flat file for later recovery. Names are included so that new revisions of VCP can rescuscitate revisions.

split_id
VCP::Rev->split_id( $id );

Splits an id in to chunks on punctuation and number/letter boundaries.

Id           Result
==           ======
1            ( 1 )
1a           ( 1, "a" )
1.2          ( 1, "", 2 )
1a.2         ( 1, "a", 2 )

This oddness is to facilitate manually named revisions that use a lettering scheme. Note that the sort algorithms make an assumption that "1.0a" is after "1.0". This prevents kind of naming like "1.2pre1".

cmp_id
VCP::Rev->cmp_id( $id1, $id2 );
VCP::Rev->cmp_id( \@id1, \@id2 );  # for presplit ids

splits $id1 and $id2 if necessary and compares them using <=> on even numbered elements and cmp on odd numbered elements.

is_base_rev

Returns TRUE if this is a base revision. This is the case if no action is defined. A base revision is a revision that is being transferred merely to check it's contents against the destination repository's contents. Base revisions contain no action and contain a <digest> but no <delta> or <content>.

When a VCP::Dest::* receives a base revision, the actual body of the revision is 'backfilled' from the destination repository and checked against the digest. This cuts down on transfer size, since the full body of the file never need be sent with incremental updates.

See "backfill" in VCP::Dest as well.

is_placeholder_rev

Returns TRUE if this is a placeholder revision. Placeholder revisions are used to record branch points for files that have not been altered on their branches.

This occurs when reading CVS repositories and finding files that have branch tags but no revisions on the branch.

A placeholder revision has an action of "placeholder".

Note that placeholders may have rev_id and change_id fields, but they may be malformed; they are present for sorting purposes only and should be ignored by the destination repository.

Placeholders may not be present for branches which have files on them.

is_branch_rev

Returns TRUE if this is a branch founding placeholder revision. These revisions are used to record branch points for files without modifying the files.

A branch revision has an action of "branch".

Note that branch placeholders may have rev_id and change_id fields, but they may be malformed; they are present for sorting purposes only and should be ignored by the destination repository.

Branch revisions may not be present for branches which have files on them but should be in order to cause the destination to create the branch before altering any files on it.

is_clone_rev

Returns TRUE if this is a cloning placeholder revision. These revisions are used to mirror files from one branch to another when a physical filebranch maps to more than one logical branch. This is not possible in p4, but is possible in both CVS and VSS. CVS generates these as of this writing, VSS may by the time you read this.

base_revify

Converts a "normal" rev in to a base rev.

id

Sets/gets the id. Returns "$name#$rev_id" by default, which should work for most systems.

get_source_file

Fetches the file from the source repository and returns a path to that file.

labels
$r->set_labels( \@labels ) ;  ## pass an array ref for speed
@labels = $r->labels ;

Sets/gets labels associated with a revision. If a label is applied multiple times, it will only be returned once. This feature means that the automatic label generation code for r_... revision and ch_... change labels won't add additional copies of labels that were already applied to this revision in the source repository.

Returns labels in an unpredictible order, which happens to be sorted for now. This sorting is purely for logging purposes and may disappear at any moment.

add_label
$r->add_label( $label ) ;
$r->add_label( @labels ) ;

Marks one or more labels as being associated with this revision of a file.

iso8601format
VCP::Rev::iso8601format( $time );

Takes a seconds-since-the-epoch time value and converts it to an ISO8601 formatted date. Exportable:

use VCP::Rev qw( iso8601format );
as_string

Prints out a string representation of the name, rev_id, change_id, type, time, and a bit of the comment. base revisions are flagged as such (and don't have fields like time and comment).

SUBCLASSING

This class uses the fields pragma, so you'll need to use base and possibly fields in any subclasses.

COPYRIGHT

Copyright 2000, Perforce Software, Inc. All Rights Reserved.

This module and the VCP package are licensed according to the terms given in the file LICENSE accompanying this distribution, a copy of which is included in vcp.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>