Next: , Previous: package and unpackage, Up: Subcommands



6.16 Prcs execute

— Command: prcs execute [option ...] [project [file-or-dir ...]] [-- command [arg ...]]

ADDITIONAL OPTIONS: -r, -P, --pre, --all, --pipe `--match pattern', `--not pattern'

Execute `command arg ...,' suitably modified as described below, for the name of each file and directory in file-or-dir in the specified version, filtered by any --match and --not operators as described below. This elaborate command is intended to facilitate efficient, open-ended extension of the functions of prcs. Each directory, whether or not explicitly named in the project, is included once, either in pre- or post-order.

With the --all option, command is executed once. Otherwise, it is executed once per file name.

The pattern options filter the selected files. To be selected, the entry in the Files attribute for a given file must satisfy the --match pattern (if any) and not satisfy the --not pattern, if any. Each pattern is a regular expression; an entry satisfies the pattern if either the name or any of the `:' options matches the pattern.

For each execution of command, prcs first replaces the following strings wherever they appear in command and in each arg:

{}
Replaced by the name of the file. With the --all option, replaced by the sequence of all selected file names, separated by “unquoted blanks” (that is, blanks that divide the replacement string into separate arguments).
{options}
Replaced by a string consisting of all colon-options applicable to the file (see Files attribute), separated by “quoted blanks” (that is, blanks that do not divide the replacement string into separate arguments). If a directory is not explicitly named in the project file, it is listed with a :implicit-directory option, whether or not it appears separately in the Files attribute. These directories appear whether or not the files containing them were on the command line (otherwise, it would be impossible to get just the directories). The project file is included with the :project-file attribute. With the --all option, all of these colon-option strings are concatenated together, with the strings for different files separated by unquoted blanks.
{file}
The name of a file containing the contents of the appropriate version of the file. Unless the internal file identifier is null (which can only happen when there is no -r option, so that the working version is specified), this is the name of a temporary file containing a checked-out copy of the appropriate version, which is deleted after command completes. With a null internal file identifier, {file} is the same as {}. It is the empty string for a directory or a file carrying the :symlink option. With the --all option, all of these file names are concatenated together, separated by unquoted blanks.

(In contexts where curly braces are special to your shell, you will have to escape them.) After these substitutions, prcs invokes command, which must be an executable file. It looks for command in the same directories as the shell (using the PATH environment variable). When -- and what follows are omitted, they default to

          -- /bin/echo {}
     

which simply echoes the names of all files and directories in the selected version, one per line.

One small glitch: prcs execute uses the current directory in effect when it is invoked as the current directory seen by command. This is true, even when the project operand specifies a subdirectory. For example,

          % cd /usr/users/foo
          % prcs execute D/P -- pwd
     

will print /usr/users/foo once for each file listed in /usr/users/foo/D/P.prj, and not /usr/users/foo/D, as the general description of the project operand might otherwise suggest (see Specifying Projects). This allows you to do something like the following:

          % ln -s . P-1.0
          % tar -cvf P-1.0.tar `prcs execute --not :.*directory P-1.0`
     

for making tarfiles containing all files in a project in an appropriately named subdirectory for distribution.

If the --pipe option is present, then the contents of the file (as would be contained in the file named by {file}) is supplied as the standard input. The --pipe and --all options are incompatible. Any arg whose replacement contains unquoted blanks (introduced by the --all option) is divided at those blanks into separate arguments (even in the case where substitution results in a null string, that null string will be broken out as a separate argument). Each of the resulting arguments, is passed directly to the program specified by command as a single string, with no further processing by any shell.

With the --all option, prcs will invoke command only once. The order of the lists of arguments replacing each pattern in command is consistent, so that, for example, the options for the first file name in the replacement for {} is the first string in the replacement for {options}. For example, if a project contains the files A, B/Q, and B/R, then

          prcs execute --all . -- foo -a{}-b "{options}"
     

will execute (in effect) the single command

          foo -aA B/Q B/R B-b "" "" "" ":directory"
     

With the --pre (for pre-order) option the directory name is listed first, then the non-directory file names within that directory, then the subdirectories and their contents. Otherwise, subdirectories and their contents are listed first, then the names of its non-directory files, then the name of the directory itself.

With -n, the command prints the commands that will be executed without actually executing them.