Keyword Expansions in SnapshotCM

Keyword substitution provides a way to embed certain information in a file automatically as part of checking out a file. Keyword expansion can be enabled or disabled independently for each file.

Keyword Forms

Keywords take any of three forms, and two variation:

1. $Keyword$
2. $Keyword: value $
3. $Keyword:: fixed length value $
4. $,Keyword ...
5. $$Keyword ...

Initially, the user enters strings of the form $keyword$. On checkout, these strings are replaced with strings of the form $keyword: value $ (note the space before and after value). If a revision containing strings of the latter form is checked back in, the value fields will be replaced during the next checkout. Thus, the keyword values are automatically updated on checkout.

The form containing two colons is used for situations where a fixed amount of space is to be used for the value. Keyword expansion in any mode will not change the space used. If the new value is too long, it will be truncated. If too short, it will be space padded.

Two variation of these forms are also provided. The first, with a comma between the leading dollar and the keyword, separates fields with commas rather than spaces. Here are two examples:

$,Date:,2013/02/08,10:06:15,-0700,$
$,Revision:,29,$.

Here is a C language example which uses macros to extract the revision number into an integer variable and the revision date into a string variable, all without needing to parse and extract the field at run-time:

#define Value3of4(a,b,c,d) c
#define String3of6(a,b,c,d,e,f) #c
#define String4of6(a,b,c,d,e,f) #d

int revision = Value3of4($,Revision:,29,$);
const char *date = String3of6($,Date:,2013/02/08,10:06:15,-0700,$);
const char *time = String4of6($,Date:,2013/02/08,10:06:15,-0700,$);

The last variation contains a doubling of the leading dollar ($) character, and causes HTML comments to be inserted into the expansion to provide a way for certain info to be automatically kept accurate in HTML pages. For example:

<P>Last updated on <!--$$JustDate$-->.

can be used to imbed a date string into HTML files. This will be expanded to:

<P>Last updated on <!--$$JustDate:-->2013/02/08<!--$-->.

and will display as

Last updated on 2013/02/08.

Keyword Expansion Modes

1. Off
2. Keyword
3. Keyword+Value
4. Value

Keyword and value expansion is the default for most text files, and allows automatic updating or adding of comments, file names, etc. to files. Keyword only expansion is useful to avoid extraneous differences when comparing and merging file revisions, so that keyword value differences will not be displayed. Value only is of limited use, primarily for situations where the keywords themselves would get in the way. However, such content, if checked in, would remove the keywords from your file. Off is the default for binary and generated text files (such as postscript files).

Keyword Expansions

Keyword	Description	Example
$Archive$	The full archive pathname of the file.	$Archive: /path/file $
$Author$	The account name of the user who created the revision.	$Author: author $
$Date$	The date and time the revision was created.	$Date: 1997/08/23 12:30:37 -0700 $
$Header$	A standard header containing the full pathname of the file, the revision number, revision date and time, and the author (account) of the revision.	$Header: /path/file 23 date time author $
$History$	Same expansion as $Log$.	// $History: file $ // Revision 23 date time author /project/Current // multi-line comment //
$Id$	Same as $Header$, except that filename is without a path.	$Id: file 23 date time author $
$JustDate$	The date of the revision.	$JustDate: 1997/08/23 $
$Log$	The change comment supplied during check in, preceded by a header containing the filename, and a line with the revision number, the date and time of the revision, the author and the snapshot path for the snapshot from which the check in occurred.	// $Log: file $ // Revision 23 date time author /project/Current // multi-line comment //
$Logfile$	The full pathname of the file.	$Logfile: /path/file $
$Modtime$	Same as $Date$.	$Modtime: 1997/08/23 12:30:37 -0700 $
$Name$	Same as $Snapshot$.	$Name: /project/Current $
$NoKeywords$	Signal to stop keyword editing for the remainder of the file.	$NoKeywords:$
$Project$	The project for the snapshot used to do the check out.	$Project: /folder/project $
$RCSfile$	The basename of the file.	$RCSfile: file $
$Revision$	The revision number of the file.	$Revision: 23 $
$Source$	The full pathname of the file.	$Source: /path/file $
$Snapshot$	The full snapshot path for the snapshot used to do the check out.	$Snapshot: /project/Current $
$Workfile$	Same as $Source$.	$Workfile: /path/file $

Notes:

$Author$

Author of the most current revision, whether attribute or content change.

$Date$

This date and time, like all others in keyword expansions, will look like: YYYY/MM/DD HH:MM:SS [+-]ZZZZ, where YYYY is a four digit year, MM, DD, HH, MM and SS are 2 digit month, day, hours (00-23), minutes and seconds, and ZZZZ is a 4 digit time zone offset per RFC 822. The date and time will be given in the local time zone of the client, with the time zone specifying the offset from UTC.

$Log$

Existing log messages are not replaced. Instead, the new log message is inserted after the $Log: file $ line. This is useful for accumulating a complete change log in a source file.

Each inserted line is prefixed by the string that prefixes the $Log$ line. For example, if the $Log$ line is

    // $Log: file $

each line of the log is prefixed with "// " (slash, slash, space). This is useful for languages with comments that go to the end of the line.

The convention for other languages is to use a " * " (space, star, space) or similar prefix inside a multiline comment. For example, the initial log comment of a C program conventionally is of the following form:

    /*
     * $History$
     */

To prevent recursive expansion of keywords in comments, keyword strings in a comment will be modified by inserting a space after the initial $ character. Only recognized keyword strings will be modified.

Special character encoding.

The following characters in keyword value expansions are represented by escape sequences to keep keyword strings well-formed.

character	escape sequence
tab	\t
nuline	\n
space	\040
$	\044
\	\\