/ 
VCS-Lite-Repository-0.12
River stage zero No dependents
/ VCS::Lite::Store

NAME

VCS::Lite::Store - Base class for repository persistence stores

SYNOPSIS

package mystore;
use base qw/VCS::Lite::Store/;
...

my $newstore = mystore->new( user => 'fred', password => 'bloggs'...);
my $rep = VCS::Lite::Repository->new( path => 'src/myfile.c',
                                      store => $newstore );

DESCRIPTION

The VCS::Lite::Repository version control system offers a choice of back end storage mechanisms. It is architected such that new back end stores can be written, that will plug in with the existing classes. The store is used as an object persistence mechanism for VCS::Lite::Repository and VCS::Lite::Element objects. The store can also potentially act as a proxy, giving access to repositories that live on another machine, or even in another type of version control system.

The store object is passed to the element and repository constructors VCS::Lite::Repository->new and VCS::Lite::Element->new as the optional parameter store. Note that this parameter can take a class name instead, see "In Situ Stores" below.

METHODS

new

The constructor takes a varying list of option value pairs. The exact list depends on which store class used. These may, for example, include a DBI connect string, username and password. Here are the ones inplemented in the base class for use by the YAML and Storable classes:

  • home

    This is the absolute path for the top level directory of the files being version controlled.

  • root

    This is for stores like VCS::Lite::Store::Storable and VCS::Lite::Store::YAML, which persist the elements and repositories into flat files. This is the top level directory of the store.

  • user

    All updating operations performed on this store take place on behalf of this username.

retrieve

$store->retrieve( $path);

This is the call which is made by the VCS::Lite::Element and VCS::Lite::Repository constructors, to retrieve an existing object from the store. return if the object does not exist.

create

$store->create( $proto);

This call writes an object to the store. If this object already exists, it is overwritten. $proto is a prototype object, with a path and a few other members populated, already blessed into the right class. The call returns a persisted, fully populated object.

retrieve_or_create

$store->retrieve_or_create( $proto);

Perform a retrieve based on the path attribute of the prototype, or create a persisted object if it does not already exist in the store.

save

$store->save($obj);

Apply updates to persist the object. This method is virtual, i.e. the subclass is expected to provide the save method.

load

$store->load($obj);

Load an object from a persistance store. This method is virtual, i.e. the subclass is expected to provide the load method.

store_path

This method is internal to flat file stores. It is used to convert between the path of a file or directory being version controlled, and the path for the corresponding store. store_path returns a list of two scalars, which are a directory and a file. There is an optional parameter of the file type used by VCS::Lite::Element::Binary; this is passed over to repos_name.

repos_name

Passed an element name or the empty string, this is a virtual method that turns this into the filename used to persist the element or repository.

There is also an optional file type parameter, which overrides the default one for the type of store.

In Situ Stores

As an alternative to an object as a store, VCS::Lite::Repository and VCS::Lite::Element can be passed a class name. These use a more limited type of store that lives in situ inside the directory tree of the files being versioned. The class name can be shortened by missing off the VCS::Lite::Store:: from the front.

The store lives under 'hidden' directories called .VCSLite or in the case of VMS _VCSLITE (dots are not permitted in the directory name syntax).

BUGS, PATCHES & FIXES

There are no known bugs at the time of this release. However, if you spot a bug or are experiencing difficulties that are not explained within the POD documentation, please send an email to barbie@cpan.org or submit a bug to the RT system (see link below). However, it would help greatly if you are able to pinpoint problems or even supply a patch.

http://rt.cpan.org/Public/Dist/Display.html?Name=VCS-Lite-Repository

Fixes are dependent upon their severity and my availability. Should a fix not be forthcoming, please feel free to (politely) remind me.

AUTHOR

Original Author: Ivor Williams (RIP)          2002-2009
Current Maintainer: Barbie <barbie@cpan.org>  2014-2015

COPYRIGHT

Copyright (c) Ivor Williams, 2002-2009
Copyright (c) Barbie,        2014-2015

LICENCE

This distribution is free software; you can redistribute it and/or modify it under the Artistic Licence v2.