<html><head><title>VCP::Filter::map - rewrite name and branch number.</title></head><body><h1><a name="NAME">NAME
</a></h1><p>VCP::Filter::map - rewrite name and branch number.
<p><hr><h1><a name="SYNOPSIS">SYNOPSIS
</a></h1><pre> ## From the command line:
vcp <source> map: p1 r1 p2 r2 -- <dest>
</pre><pre> ## In a .vcp file:
</pre><pre> Map:
name_glob_1<branch_1> name_out_1<branch_result_1>
name_glob_2<branch_2> name_out_2<branch_result_2>
# ... etc ...
</pre><p><hr><h1><a name="DESCRIPTION">DESCRIPTION
</a></h1><p>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.
<h2><a name="Rules">Rules
</a></h2><p>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.
<p>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
<p>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.
<h2><a name="Patterns_and_Rule_Expressions">Patterns and Rule Expressions
</a></h2><p>Patterns and rules are composed of two subexpressions, the
<code>name_expr</code> and the <code>branch_id_expr</code> like so:
<pre> name_expr<branch_id_expr>
</pre><p>The <code><branch_id_expr></code> (including angle brackets) is optional and may
be forbidden by some sources or destinations that embed the concept of a
branch in the name_expr. (See <a href="../Dest/p4.html">VCP::Dest::p4</a> for an
example, though this may be changed in the future).
<p>For now, the symbols <code>#</code> and <code>@</code> are reserved for future used in all
expressions and must be escaped using <code>\</code>, and various shell-like
wildcards are implemented in pattern expressions.
<h2><a name="Pattern_Expressions">Pattern Expressions
</a></h2><p>Both the <code>name_expr</code> and <code>branch_id_expr</code> 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:
<pre> ? 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
</pre><p>Some example pattern <code>name_expr</code>s are:
<pre> Pattern
name_expr Matches
========= =======
foo the top level file "foo"
foo/bar the file "foo/bar"
... all files (like a missing name_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
</pre><p>Unix-style slashes are used, even on operating systems where that may
not be the preferred local custom. A pattern consisting of the empty
string is legal and matches everything (NOTE: currently there is no way
to take advantage of this; quoting is not implemented in the forms
parser yet. use "..." instead).
<p>Relative paths are taken relative to the rev_root indicated in the
source specification for pattern <code>name_expr</code>s (or in the destination
specification for result <code>name_expr</code>s). For now, a relative path is a
path that does not begin with the character <code>/</code>, so be aware that the
pattern <code>(/)</code> 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.
<p>If no <code>name_expr</code> is provided, <code>...</code> is assumed and the pattern will
match on all filenames.
<p>Some example pattern <code>branch_id_expr</code>s are:
<pre> Pattern
branch_id_expr Matches files on
=========== ================
<> no branch
<...> all branches (like a missing <branch_id_expr>
<foo> branch "foo"
<R...> branches beginning with "R"
<R(...)> branches beginning with "R", the other chars in $1
</pre><p>If no <code>branch_id_expr</code> is provided, files on all branches are matched.
<code>*</code> and <code>...</code> still match differently in pattern <code>branch_id_expr</code>s, as
in <name_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 <code>branch_id_expr</code> patterns.
<p>Some example composite patterns are (any $ variables set
are given in parenthesis):
<pre> 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)
</pre><h2><a name="Escaping">Escaping
</a></h2><p>Null characters and newlines are forbidden in all expressions.
<p>The characters <code>#</code>, <code>@</code>, <code>[</code>, <code>]</code>, <code>{</code>, <code>}</code>, <code>></code>, <code><</code>
and <code>$</code> must be escaped using a <code>\</code>, as must any wildcard characters
meant to be taken literally.
<p>In result expressions, the wildcard characters <code>*</code>, <code>?</code>, the wildcard
trigraph <code>...</code> and parentheses must each be escaped with single <code>\</code> as
well.
<p>No other characters are to be escaped.
<h2><a name="Case_sensitivity">Case sensitivity
</a></h2><p>By default, all patterns are case sensitive. There is no way to
override this at present; one will be added.
<h2><a name="Result_Expressions">Result Expressions
</a></h2><p>Result expressions look a lot like patthern expressions except that
wildcards are not allowed and <code>$1</code> and <code>${1}</code> style variable
interpolation is.
<h2><a name="Result_Actions_delete_and_keep_">Result Actions: <delete>> and <<keep>>
</a></h2><p>The result expression <code><<delete>></code> indicates to delete the revision,
while the result expression "<<keep>>" indicates to pass it through
unchanged:
<pre> Map:
# Pattern Result
# ================= ==========
old_stuff/... <<delete>> # Delete all files in /old
old_stuff/.../*.c <<keep>> # except these
</pre><p><code> <<delete</code>> > and <code> <<keep</code>> > may not appear in results; they are
standalone tokens.
<h2><a name="The_default_rule">The default rule
</a></h2><p>There is a default rule
<pre> ... <<keep>> ## Default rule: passes everything through as-is
</pre><p>that is evaluated before all the other rules. Thus, if no other rule
matches a revision, it is passed through unchanged.
<h2><a name="Command_Line_Parsing">Command Line Parsing
</a></h2><p>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.
<p>Because <a href="../../vcp.html">vcp</a> 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 <code>Map:</code> section of a .vcp file, but that is
superfluous. It is an error to use "--" before the last word in a .vcp
file.
<p><hr><h1><a name="LIMITATIONS">LIMITATIONS
</a></h1><p>There is no way (yet) of telling the mapper to continue processing the
rules list. We could implement labels like <code> <<<i>label</i></code>> > to be
allowed before pattern expressions (but not between pattern and result),
and we could then impelement <code> <<goto <i>label</i></code>> >. And a <code> <<next</code>>
> could be used to fall through to the next label. All of which is
wonderful, but I want to gain some real world experience with the
current system and find a use case for gotos and fallthroughs before I
implement them. This comment is here to solicit feedback :).
<p><hr><h1><a name="AUTHOR">AUTHOR
</a></h1><p>Barrie Slaymaker <barries@slaysys.com>
<p><hr><h1><a name="COPYRIGHT">COPYRIGHT
</a></h1><p>Copyright (c) 2000, 2001, 2002 Perforce Software, Inc.
All rights reserved.
<p>See <a href="../License.html">VCP::License</a> (<code>vcp help license</code>) for the terms of use.
<p><hr><i><font size="-1">Last updated: Fri Nov 8 13:07:22 2002</font></i></body></html>