Go to the first, previous, next, last section, table of contents.


9 Keywords

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.

Recognized Keywords

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.

Author
The login of the user who created this checked-in version of the file. Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword.
Date
The date and time at which this version of the file was checked in. Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword.
Basename
The base name of the file, as it appears in the Files attribute.
Revision
A notation that serves as a revision number for this file (it is independent of the project's version number, and changes only when the file changes). Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword.
Id
A standard header combining the Basename, Revision, Date, and Author.
Source
The full name of the file, as a pathname relative to the root of the project's directory tree.
Project
The name of the project containing the file version.
ProjectDate
The date and time the project containing this file version was checked in.
ProjectAuthor
The login name of the user who checked in the project version containing this file version.
ProjectMajorVersion
The major version name of the project version containing this file version.
ProjectMinorVersion
The minor version name (a number) of the project version containing this file version.
ProjectVersion
The complete version designator for this project version. It has the form M.N, where M is the major project-version name and N is the minor project-version name.
ProjectHeader
A standard header combining the Project, ProjectVersion, ProjectDate, and ProjectAuthor.

Recognized 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.

Formatted Keyword Instances

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.

Keywords and File Identifiers

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.