VCP::Driver - A base class for sources and destinations

   use VCP::Driver;
   @ISA = qw( VCP::Driver );
   ...

A VPC::Driver is a VCP::Plugin and is the base class for VCP::Source and VCP::Dest.

Options global to all sources and destinations (unless otherwise documented:

--case-sensitive

Whether or not to compare filenames in a case sensitive manner. This defaults to true on Win32 and false elsewhere. It also may not affect all operations because VCP shells out to subcommands that have their own opinions about such matters.

--db-dir

The directory to store VCP's state information in. VCP store state information for each transfer that describes what revisions were read from the source repository and how they were written to the destination repository. Typically this is kept in a subdirectory of the CWvcp_state directory, where the subdirectory is based on the CWrepo_id value (which may be set by the CW--repo-id option). This allows you to set the directory name.

--repo-id

The globally unique identifier for a repository. This is normally set to the repo_server field value from the repository specification but may need to be specified manually if the repository has been moved or is accessed using different server specifications. This is only used when a source or destination needs to create a transfer state database, and is ignored by those that don't. It is allowed globally (unless otherwise documented) so that users may be consistent in setting it so that if a source or dests suddenly grows a need to use it, it will be there (if the user has been consistent).

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

revs

Sets/gets the revs container. This is used by most sources to accumulate the set of revisions to be copied. This member should be set by the child in copy_revs(). It should then be passed to the destination

parse_options

   $self->parse_options( \@options, @spec );

Parses out all options according to CW@spec. The --repo-id option is always parsed and VCP::Source.pm and VCP::Dest.pm offer common options as well.

options_spec

Returns a list of Getopt::Long::GetOptions() options specifications with the limitation that CODE refs (sub { ... }) are not allowed. This is called by parse_options() and dot_vcp_file_options_string(). Specified option global to all sources and destinations. See above. Note that only a few of the myriad syntaxes that Getopt::Long allows are provided for here so that we can reliably reguritate the values when writing .vcp files. To wit, these are the !, : and = flag characters (the type after the flag character is ignored). Storage locations must be a SCALAR or CODE reference for now, and the code references must be written like:

    '...' => sub { shift; $self->accessor( @_ ) },

so that they may be used as an getter by the options printing code. Overloading methods should be of the form:

    sub options_spec {
       my $self = shift;
       return (
          $self->SUPER::options_spec,
          "my-option1-long-name|short-name1..." => \$self->{FOO},
          "my-option2-long-name|short-name2..." => sub {
             shift;
             $self->setter_getter( @_ );
          },
          ...
       );
    }

options_as_strings

Returns a list of options as strings. Each string will be a single option and, if it has a value, it's value suitable for passing on the command line or emitting to a .vcp file. Options that are not set (are undefined) are returned with a leading # character. These should be grepped out if the options are not going to be on a single line each in a .vcp file. String options that are " internally are not returned with a leading " character.

repo_spec_as_string

Returns a string that represents a Source: or Dest: specification equivalent to the one that was parsed (usually by new() calling parse_repo_spec()).

config_file_section_as_string

Returns a string that may be emitted to dump a filter's settings to a .vcp file.

compile_path_re

Compiles a filespec in to a regular expression, treating '*', '?', '...', and '{}' (brace pairs) as wildcards. () and ** are not treated as capture and ..., respectively.

parse_repo_spec

   my $spec = $self->split_repo_spec( $spec ) ;

This splits a repository spec in one of the following formats:

   scheme:user:passwd@server:filespec
   scheme:user@server:filespec
   scheme::passwd@server:filespec
   scheme:server:filespec
   scheme:filespec

into the indicated fields, which are stored in CW$self and may be accessed and altered using repo_scheme, repo_user, repo_password, repo_server, and repo_filespec. Some sources and destinations may add additional fields. The p4 drivers create an repo_client in VCP::Utils::p4, for instance, and parse the repo_user field to fill it in. See parse_p4_repo_spec in VCP::Utils::p4 for details. The spec is parsed from the ends towards the middle in this order:

   1. SCHEME (up to first ':')
   2. FILESPEC  (after last ':')
   3. USER, PASSWORD (before first '@')
   4. SERVER (everything left).

This approach allows the FILESPEC string to contain '@', and the SERVER string to contain ':' and '@'. USER can contain ':'. Funky, but this works well, at least for cvs and p4. If a section of the repo spec is not present, the corresponding entry in CW$hash will not exist. The attributes repo_user, repo_password and repo_server are set automatically by this method. It does not store the SCHEME anyware since the SCHEME is ignored by the plugin (the plugin is selected using the scheme, so it knows the scheme implicitly), and the FILES setting often needs extra manipulation, so there's no point in storing it.

work_path

   $full_path = $self->work_path( $filename, $rev ) ;

Returns the full path to the working copy of the local filename. Each VCP::Plugin gets their own hierarchy to use, usually rooted at a directory named /tmp/vcp$$/plugin-source-foo/ for a module VCP::Plugin::Source::foo. $$ is vcp's process ID. This is typically CW$work_root/$filename/$rev, but this may change. CW$rev is put last instead of first in order to minimize the overhead of creating lots of directories. It *must* be under CW$work_root in order for rm_work_path() to fully clean. All directories will be created as needed, so you should be able to create the file easily after calling this. This is only called by subclasses, and is optional: a subclass could create it's own caching system. Directories are created mode 0775 (rwxrwxr-x), subject to modification by umask or your local operating system. This will be modifiable in the future.

rm_work_path

   $self->rm_work_path( $filename, $rev ) ;
   $self->rm_work_path( $dirname ) ;

Removes a directory or file from the work directory tree. Also removes any and all directories that become empty as a result up to the work root (/tmp on Unix).

work_root

   $root = $self->work_root ;
   $self->work_root( $new_root ) ;
   $self->work_root( $new_root, $dir1, $dir2, .... ) ;

Gets/sets the work root. This defaults to

   File::Spec->tmpdir . "/vcp$$/" . $plugin_name

but may be altered. If set to a relative path, the current working directory is prepended. The returned value is always absolute, and will not change if you chdir(). Depending on the operating system, however, it might not be located on to the current volume. If not, it's a bug, please patch away.

command_chdir

Sets/gets the directory to chdir into before running the default command. DEPRECATED: use in_dir => dirname instead:

   $self->cvs(
      [..],
      \$in,
      \$out,
      in_dir => $dirname,
   );

command_stderr_filter

   $self->command_stderr_filter( qr/^cvs add: use 'cvs commit'.*\n/m ) ;
   $self->command_stderr_filter( sub { my $t = shift ; $$t =~ ... } ) ;

Some commandscough*cvs*coughjust don't seem to be able to shut up on stderr. Other times we need to watch stderr for some meaningful output. This allows you to filter out expected whinging on stderr so that the command appears to run cleanly and doesn't cause CW$self->cmd(...) to barf when it sees expected output on stderr. This can also be used to filter out intermittent expected errors that aren't errors in all contexts when they aren't actually errors. DEPRECATED: use stderr_filter => qr/regexp/ instead:

    $self->ss( [ 'Delete', $file, "-I-y" ],
        stderr_filter => qr{^You have.*checked out.*Y[\r\n]*$}s,
        );

repo_id

   $self->repo_id( $repo_id ) ;
   $repo_id = $self->repo_id ;

Sets/gets the repo_id, a unique identifier for the repository.

repo_scheme

   $self->repo_scheme( $scheme_name ) ;
   $scheme_name = $self->repo_scheme ;

Sets/gets the scheme specified (cvs, p4, revml, etc). This is normally superfluous, since the scheme name is peeked at in order to load the correct VCP::{Source,Dest}::* class, which then calls this. This is usually set automatically by parse_repo_spec.

repo_user

   $self->repo_user( $user_name ) ;
   $user_name = $self->repo_user ;

Sets/gets the user name to log in to the repository with. Some plugins ignore this, like revml, while others, like p4, use it. This is usually set automatically by parse_repo_spec.

repo_password

   $self->repo_password( $password ) ;
   $password = $self->repo_password ;

Sets/gets the password to log in to the repository with. Some plugins ignore this, like revml, while others, like p4, use it. This is usually set automatically by parse_repo_spec.

repo_server

   $self->repo_server( $server ) ;
   $server = $self->repo_server ;

Sets/gets the repository to log in to. Some plugins ignore this, like revml, while others, like p4, use it. This is usually set automatically by parse_repo_spec.

repo_filespec

   $self->repo_filespec( $filespec ) ;
   $filespec = $self->repo_filespec ;

Sets/gets the filespec. This is usually set automatically by parse_repo_spec.

rev_root

   $self->rev_root( 'depot' ) ;
   $rr = $self->rev_root ;

The rev_root is the root of the tree being sourced. See deduce_rev_root for automated extraction. Root values should have neither a leading or trailing directory separator. '/' and '\' are recognized as directory separators and runs of these are converted to single '/' characters. Leading and trailing '/' characters are then removed.

deduce_rev_root

   $self->deduce_rev_root ;
   print $self->rev_root ;

This is used in most plugins to deduce the rev_root from the filespec portion of the source or destination spec if the user did not specify a rev_root as an option. This function sets the rev_root to be the portion of the filespec up to (but not including) the first file/directory name with a wildcard. '/' and '\' are recognized as directory separators, and '*', '?', and '...' as wildcard sequences. Runs of '/' and '\' characters are treated as single '/' characters (this may damage UNC paths). NOTE: if no wildcards are found and the last character is a '/' or '\\', then the entire string will be considered to be the rev_root. Otherwise the spec is expected to refer to a file, in which case the rev_root does not include the final name. This means that

   cvs:/foo

and

   cvs:/foo/

are different.

normalize_name

   $fn = $self->normalize_name( $fn ) ;

Normalizes the filename by converting runs of '\' and '/' to '/', removing leading '/' characters, and removing a leading rev_root. Dies if the name does not begin with rev_root.

case_sensitive

Returns TRUE or FALSE: whether or not to be case sensitive. If not set as an option, returns !is_win32.

denormalize_name

   $fn = $self->denormalize_name( $fn ) ;

Denormalizes the filename by prepending the rev_root. May do more in subclass overloads. For instance, does not prepend a '//' by default for instance, but p4 overloads do that.

db_dir

Set or return the directory name where the transfer state databases are stored. This is the directory to store the state information for this transfer in. This includes the mapping of source repository versions (name+rev_id, usually) to destination repository versions and the status of the last transfer, so that incremental transfers may restart where they left off.

_db_store_location

Determine the location to store the transfer state databases. Uses the path provided by the --db-dir option if present, else use directory 'vcp_state' in the directory the program was started in. The file name is an escaped repo_id. This is passed in to the appropriate DBFile or used directly by the destinations as need be.

run_safely

Runs a command safely, first chdiring in to the proper directory and then running it while examining STDERR through an optional filter and looking at the result codes to see if the command exited acceptably. Most often called from VCP::Utils::foo methods.

command_result_code

Returns the result code from the last CWrun_safely() command. This is a separate method because (a) most invocations set the ok result codes list so that funny looking but ok results are ignored, and (2) because returning the command execution code from the run() command leads to funny looking inverted logic because most shell commands return 0 for sucess. Now, if Perl has an N but false special case to go with its 0 but true. This is read-only.

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.

Barrie Slaymaker <barries@slaysys.com>