Files in a project may contain instances of keywords that (in effect)
prcs checkin
will replace with certain information.
Conceptually, upon checkin, each keyword instance in every file
of the project (not just
those listed in the checkin subcommand)
is updated as described below with the value of its
keyword in the new project version. As a performance consideration,
however, this is implemented in such a way that partial checkins only
have to examine the files that are listed in the checkin subcommand (see section Keywords and File Identifiers).
There are two forms of keyword instance: simple and formatted. A simple keyword instance has one of the forms
$keyword$ $keyword: data$
This syntax is strict: PRCS does not recognize a keyword when there
is whitespace on either side (separating it from the dollar sign that
precedes it or the dollar sign or colon that follows). There may not be
newlines anywhere in the keyword instance. If the keyword is one that
PRCS recognizes, other than Format
, prcs checkin
replaces the instance with an instance of the second form, with the data
part depending on the particular keyword. Formatted keyword instances
allow a more flexible replacement format.
PRCS understands the following built-in keywords, in addition to any declared in the Project-Keywords attribute. Others are ignored (their instances are left unchanged). Instances of the Source and ProjectHeader keywords change whenever the file is moved from one directory to another within a project. Instances of Project, ProjectDate, ProjectAuthor, ProjectMajorVersion, ProjectMinorVersion, ProjectVersion, and ProjectHeader can change even when the file containing them does not, since they depend on the project, not the file. These keywords are known collectively as project-related keywords.
Keyword replacement is recursive.
Replacement of a keyword takes place on a string which is either the
quoted contents of a Format
keyword or the defined value of a
regular keyword instance. When this string contains an instance of a
keyword which is not currently being replaced, it recursively outputs
the value of that keyword. Processed text is not reexamined. A keyword
instance is not replaced when it is appears during a recursive
replacement of the same keyword, to prevent loops.
One minor glitch in the above description. Since the `$' character delimits keyword instances, tt is necessary to prevent `$' characters from being inserted as the value of a non-formatted keyword. All text after the first `$' would otherwise end up being inserted into the document. For example, if the keyword K had value "I have a `$' character!" were replaced:
$K: I have a $ character!$
Then, the next replacement would result in:
$K: I have a $ character!$ character!$
and so on. Therefore, when spurious `$' characters are found
inside the contents of a regular keyword value (not Format
), they
are replaced with the `|' character.
Sometimes, you want keyword replacement data to appear without the
leading $keyword:
and trailing `$'. A formatted keyword
instance allows this. An appearance in your file of
$Format: "string"$ string
will cause prcs checkin
to replace the next line of the source
file (i.e., the line after the second `$') with string, after
first making modified keyword substitutions in it. Specifically, each
instance of $keyword$
in string (for which
keyword is one of the recognized keywords) is replaced by just the
data that would be placed to the right of the `:' in a simple
keyword instance. The Format
instance itself is not
altered--only the subsequent line. For example, if a file in a project contains
/* $Format: "static char* version = \"$ProjectVersion$\";"$ */ static char* version = "1.2-be.3";
then the version of the file checked in for version 1.2 of the project will contain
/* $Format: "static char* version = \"$ProjectVersion$\";"$ */ static char* version = "1.2-be.3";
The format string may not contain newlines. It may contain quotation
marks if they are stropped with a backslash, as in the example above.
In general, the backslash quotes the succeeding character. Any keyword
instances on a list after a Format
instance are ignored (that is,
they are left unchanged by keyword substitution). Any nested instance
of Format
is also left unchanged.
The actual content of a working file upon checkout depends on two things: the internal file identifier recorded for it and the contents of the project descriptor. The internal file identifier designates a particular "raw" file contents stored in the repository that never changes once it is first created. The checked out file consists of this contents modified by keyword replacement. If the same file identifier is used for two files in two different projects, the checked-out working files will differ in the values supplied for these keywords. This is a subtle point, but it is significant when you copy a file identifier from one project to another.
For example, suppose that file F in version 1.2 of project P contains the line
/* $ProjectVersion: 1.2-be.3 $ */
and that its entry in the Files attribute of P.prj is
(F (P/0_F 1.1))
If you decide to rename F to G for the next version of P, you can do so by changing its line in the Files attribute to
(G (P/0_F 1.1))
When you check the project back in, creating version 1.3, this same line will be retained as its file identifier (assuming, that is, you made no changes to G or its former incarnation, F). However, in version 1.3 of P, G will contain
/* $ProjectVersion: 1.2-be.3 $ */
That is, PRCS actually performs all keyword replacement on check-out (think of it as lazy replacement). It only makes a user-visible difference in the handling of internal identifiers. It also has a considerable effect on the performance of partial checkins (those that contain a list of specific files and directories to check in, and copy all unmentioned files from file identifiers listed in the Files attribute). Because PRCS does not have to examine the files excluded from the file list for keywords, it can process them very quickly.
Go to the first, previous, next, last section, table of contents.