package VCP::Filter::map; =head1 NAME VCP::Filter::map - rewrite name and branch number. =head1 SYNOPSIS ## From the command line: vcp <source> map: p1 r1 p2 r2 -- <dest> ## In a .vcp file: Map: path_glob_1<branch_1> path_out_1<branch_result_1> path_glob_2<branch_2> path_out_2<branch_result_2> # ... etc ... =head1 DESCRIPTION Maps source files, revisions, and branches to destination files and branches while copying a repository. This is done by rewriting the name and branch_id of revisions according to a list of rules. =head2 Rules A rule is a pair of expressions specifying a pattern to match against the each incoming revision's name and branch_id and a result to use to replace the revision's name and branch_id. The list of rules is evaluated top down; the last rule in the list that matches is used to generate the new name and branch_id. There is a default rule that applies to all files Note that sorting is performed in the destination, so the map will affect the sort order and the original file name and branch_id are lost. =head2 Patterns and Rule Expressions Patterns and rules are composed of two subexpressions, the C<path_expr> and the C<branch_expr> like so: path_expr<branch_expr> The C<< <branch_expr> >> (including angle brackets) is optional and may be forbidden by some sources or destinations that embed the concept of a branch in the path_part. (See L<VCP::Dest::p4|VCP::Dest::p4> for an example, though this may be changed in the future). For now, the symbols C<#> and C<@> are reserved for future used in all expressions and must be escaped using C<\>, and various shell-like wildcards are implemented in pattern expressions. =head2 Pattern Expressions Both the C<path_expr> and C<branch_expr> specify patterns using shell regular expression syntax with the extension that parenthesese are used to extract portions of the match in to numbered variables which may be used in the result construction, like Perl regular expressions: ? Matches one character other than "/" * Matches zero or more characters other than "/" ... Matches zero or more characters, including "/" (foo) Matches "foo" and stores it in the $1, $2, etc Some example pattern C<path_expr>s are: Pattern path_expr Matches ========= ======= foo the top level file "foo" foo/bar the file "foo/bar" ... all files (like a missing path_expr) foo/... all files under "foo/" .../bar all files named "bar" anywhere */bar all files named "bar" one dir down ....pm all files ending in ".pm" ?.pm all top level 4 char files ending in ".pm" \?.pm the top level file "?.pm" (*)/... all files in subdirs, puts the top level dirname in $1 Unix-style slashes are used, even on operating systems where that may not be the preferred local custom. The characters C<#>, C<@>, C<[>, C<]>, C<{>, C<}>, C<E<gt>>, C<E<lt>> and C<$> are not permitted in pattern expressions and must be escaped using a C<\>, as must any wildcard characters meant to be taken literally (this is true in result expressions as well). Relative paths are taken relative to the rev_root indicated in the source specification for pattern C<path_expr>s (or in the destination specification for result C<path_expr>s). For now, a relative path is a path that does not begin with the character C</>, so be aware that the pattern C<(/)> is relative. This is a limitation of the implementation and may change, until it does, don't rely on a leading "(" making a path relative and use multiple rules to match multiple absolute paths. If no C<path_expr> is provided, C<...> is assumed and the pattern will match on all filenames. Some example pattern C<branch_expr>s are: Pattern branch_expr Matches files on =========== ================ <> no branch <...> all branches (like a missing <branch_expr> <foo> branch "foo" <R...> branches beginning with "R" <R(...)> branches beginning with "R", the other chars in $1 If no C<branch_expr> is provided, files on all branches are matched. C<*> and C<...> still match differently in pattern C<branch_expr>s, as in <path_expr> patterns, but this is likely to make no difference, as I've not yet seen a branch label with a "/" in it. Still, it is wise to avoid "*" in C<branch_expr> patterns. Some example composite patterns are (any $ variables set are given in parenthesis): Pattern Matches ======= ======= foo<> top level files named "foo" not on a branch (...)<> all files not on a branch ($1) (...)/(...)<> all files not on a branch ($1,$2) ...<R1> all files on branch "R1" .../foo<R...> all files "foo" on branches beginning with "R" (...)/foo<R(...)> all files "foo" on branches beginning with "R" ($1, $2) =head2 Result Expressions Result expressions look a lot like patthern expressions except that wildcards are not allowed and C<$1> and C<${1}> style variable interpolation is. The characters C<@>, C<#>, C<E<gt>>, C<E<lt>> must be escaped, and C<$> must be escaped if meant to be taken literally. =head2 Command Line Parsing For large maps or repeated use, the map is best specified in a .vcp file. For quick one-offs or scripted situations, however, the map: scheme may be used on the command line. In this case, each parameter is a "word" and every pair of words is a ( pattern, result ) pair. Because L<vcp|vcp> command line parsing is performed incrementally and the next filter or destination specifications can look exactly like a pattern or result, the special token "--" is used to terminate the list of patterns if map: is from on the command line. This may also be the last word in the C<Map:> section of a .vcp file, but that is superfluous. It is an error to use "--" before the last word in a .vcp file. =for test_script t/61map.t =cut $VERSION = 1 ; use strict ; use VCP::Filter; use Getopt::Long; use base qw( VCP::Filter ); use fields ( 'MAP_RULES', ## The rules to apply ); sub new { my $class = shift ; $class = ref $class || $class ; my $self = $class->SUPER::new( @_ ) ; ## Parse the options my ( $spec, $options ) = @_ ; { local *ARGV = $options ; GetOptions( "NoFreakinOptionsAllowed" => \undef, ) or $self->usage_and_exit ; } while ( @$options && $options->[0] ne "--" ) { } return $self ; } sub handle_rev { my VCP::Filter::map $self = shift; $self->dest->handle_rev( @_ ); } =head1 AUTHOR Barrie Slaymaker <barries@slaysys.com> =head1 COPYRIGHT Copyright (c) 2000, 2001, 2002 Perforce Software, Inc. All rights reserved. See L<VCP::License|VCP::License> (C<vcp help license>) for the terms of use. =cut 1
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#20 | 5404 | Barrie Slaymaker |
- SVN support added - Makefile gives clearer notices about missing optional prereqs. - VCP::Filter::labelmap and VCP::Filter::map: <<skip>> replaces deprecated <<delete>> to be clearer that no revisions are deleted from either repository but some just are skipped and not inserted. - VCP::Filter::map: support added for SVN-like branch labels - VCP::Source: support added for ISO8601 timestamps emitted by SVN. |
||
#19 | 4487 | Barrie Slaymaker | - dead code removal (thanks to clkao's coverage report) | ||
#18 | 4483 | Barrie Slaymaker | - calls to skip_rev() are summarized to STDOUT | ||
#17 | 4481 | Barrie Slaymaker | - VCP::Filter::map calls skip_rev when deleting a rev (spotted by clkao) | ||
#16 | 4021 | Barrie Slaymaker |
- Remove all phashes and all base & fields pragmas - Work around SWASHGET error |
||
#15 | 4012 | Barrie Slaymaker | - Remove dependance on pseudohashes (deprecated Perl feature) | ||
#14 | 3491 | Barrie Slaymaker | - All sections are now documented in generated config files | ||
#13 | 3415 | John Fetkovich | documentation cleaned up | ||
#12 | 3155 | Barrie Slaymaker |
Convert to logging using VCP::Logger to reduce stdout/err spew. Simplify & speed up debugging quite a bit. Provide more verbose information in logs. Print to STDERR progress reports to keep users from wondering what's going on. Breaks test; halfway through upgrading run3() to an inline function for speed and for VCP specific features. |
||
#11 | 3091 | Barrie Slaymaker |
Factor out rules list parsing; it's useful elsewhere and should not have been copy & edited in to two files in the first place. |
||
#10 | 3089 | Barrie Slaymaker | Fix minor bug in error reporting. | ||
#9 | 3028 | Barrie Slaymaker | Fix quoting issue in debugging statement | ||
#8 | 3026 | Barrie Slaymaker | Code and docs cleanup | ||
#7 | 3015 | Barrie Slaymaker |
Finally find & fix a stray "not an ARRAY reference" in perl's cleanup code (it's probably mishandling a closure) |
||
#6 | 2867 | John Fetkovich | debugging output change | ||
#5 | 2317 | Barrie Slaymaker | Get map working on revml->revml | ||
#4 | 2316 | Barrie Slaymaker | intermediate checkin | ||
#3 | 2315 | Barrie Slaymaker | update docs, implement a bit more mapping code | ||
#2 | 2307 | Barrie Slaymaker | get VCP::Filter::map working, update docs | ||
#1 | 2305 | Barrie Slaymaker | This too |