Protections Expansion
---------------------

**protexp.pl** is a form trigger for protections that allows multiple
protections lines to be specified as a single expression containing
special variables. The *form-in* half of the trigger expands the
expression into a set of actual protections entries, and the *form-out*
half of the trigger collapses it back into its shorter human-editable
form.

The following variables are implemented at this time.

### \$dirs(path)

Expands to a list of directories matching the given path. For example:

`write group * $dirs(//depot/*)/bin/...`

is expanded to become something like:

`write group * //depot/main/bin/...`\
`write group * //depot/r011/bin/...`\
`write group * //depot/r012/bin/...`

The path must use only use asterisk wildcards (it will be translated to
a **p4 dirs** call, so "..." is not supported). This syntax can be used
to help eliminate protections lines with multiple wildcards and their
attendant performance problems. (See [this 2007 User Conference
presentation](http://www.perforce.com/perforce/conferences/us/2007/presentations/MShields_Performance2007_paper.pdf)
for the pitfalls of multiple wildcards in protections.)

### \$user(group)

Expands to one line per group member (subgroups are handled
recursively). For example:

`write user $user(bobs) * //dev/$user(bobs)/...`

becomes something like:

`write user bobA * //dev/bobA/...`\
`write user bobB * //dev/bobB/...`\
`write user bobC * //dev/bobC/...`

This can be handy for setting up permissions on a large set of private
branches in a single swoop.

Setup
-----

### Installation

Edit the connection information in the script; you must provide the
port, user, and password/ticket in order for the trigger to run the
necessary p4 commands. You may also need to provide the full path to p4.

Add a pair of trigger entries like this:

`protexpOut form-out protect "perl protexp.pl out %formfile%"`\
`protexpIn  form-in  protect "perl protexp.pl in  %formfile%"`

### Usage notes

Don't mix and match different variables in the same line; the script
won't handle it well, and even if it did it doesn't seem like it would
be very useful.

With both halves of the trigger operating, you will never see the
expanded form of the variables. You can quickly disable the *form-out*
half by changing the "out" argument to "none"; you will then see the
expanded protection lines and the delimiters that include a hex-encoded
copy of the human-entered original line.

Note that the expansion happens at the time you save the protection
table; the expanded lines will **not** be automatically updated when new
directories or new users are added to the server. You can redo the
expansion just by running:

`p4 protect -o | p4 protect -i`

If this is cumbersome, you might consider adding another trigger that
does this when appropriate, e.g. a trigger on groups that regenerates
the protection table using the above command when a group is edited.
This part is left as an exercise to the reader.

[Category:Perforce administrative
tools](Category:Perforce_administrative_tools "wikilink")