TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Keyword Replacement

Keyword replacement occurs as part of a number of different Apex commands and provides a flexible way in which users can customize Apex operations or get access to Apex information sources.

In its simplest form, keyword replacement provides a way in which strings containing special tokens called keywords are evaluated to produce result strings in which the keywords have been replaced by the names or attributes of Apex objects. For example, the keyword <subsystem> is replaced by the name of the current subsystem. Apex keyword replacement also provides capabilities to:

Keyword replacement occurs as part of a number of different Apex operations including:


Keyword Replacement Process

The keyword replacement process is essentially very simple. A format string containing keywords is evaluated against a set of context objects to produce a result string. Depending on the command in which keyword replacement occurs, the format string, context objects and destination of the result string can be specified explicitly or can be derived from the arguments to the original operation.

In the case of creation of new Ada, C, or C++ source files, the format string is the contents of the prototype file, the context object is the source file that is being created, and the result string is stored as the contents of the new source file. In the case of report generation, the format string, the context objects, and the handling of the result string are all specified explicitly.

The heart of the keyword replacement process is the evaluation of the format string against the context objects. The syntax of keywords and the way in which they are replaced is described in the next section.


Keyword Syntax

Keywords can be used to specify simple replacements such as the name of the context object, or complex replacements such as a table containing all of the controlled objects in a view.

Keywords are identified by the brackets "<" and ">" for basic keywords and the braces "{" and "}" for list- and table-oriented keywords. Keyword names are case insensitive. The brackets "<" and ">" may not be nested.

Basic Keywords

Basic keywords have the general form:

<simple-keyword-name'attribute-name:modifier default>

where `attribute-name and :modifier are optional, may occur in any order and may be repeated any number of times after the simple-keyword-name. The default field is also optional and must occur as the last part of the keyword and must be separated by a space from the rest of the keyword string. If the keyword evaluates to the empty string and default is present then the keyword is replaced by the default value.

Simple Keywords

During keyword replacement, simple keywords are replaced by the fully-qualified permanent name of the designated object or by the designated command state.

Simple keywords include:

Pathname Modifiers

Keyword replacement supports C-shell style name modifiers for altering the pathnames produced by other keyword replacements. Each modifier must be preceded by a colon (":") and multiple modifiers are allowed. Modifiers follow simple keywords or attribute designators within the brackets "<" and ">". For example, the format string <object:t:r> would be replaced with the simple name of the context object with the extension removed.

The following modifiers are supported:

Index Modifiers

An integer value can be used as a modifier for the <options> and <arguments> keywords to provide access to a specific option or argument. For example, <arguments:2> would return the second argument to the original Apex command.

Time Modifiers

Modifiers are also provided for specifying the time format that will be used for the <time> and <gm_time> keywords and for any attributes that return a time value. Separate modifiers can be specified for the clock time and date portions of the time.

The format of the date portion of the time can be specified with the following modifiers that are shown with examples of dates in their respective formats:

The clock time portion of the time can be formatted with the following modifiers that are shown with examples of times in the respective formats:

The default is :month_day_year:military_time.

Miscellaneous Modifiers

Attributes

Attributes for objects can be interrogated within keyword replacement. Attribute replacement has the format `attribute-name or `attr(attribute-name) and must follow a simple keyword within the "<" and ">" brackets. Multiple attribute replacements can be applied and attribute replacement can also be applied to modified names. For example, the format string <object'cmvc_state> will be replaced by the current version control state of the context object. Attribute replacement results in the empty string if the attribute does not apply to the named object.

General Attributes
Subsystem and View Attributes
Access Control Attributes (Apex/ClearCase)
ClearCase Attributes (Apex/ClearCase)
Version Control Attributes

Attributes listed below can be applied to files, directories or views to provide information about the version control state of the object. Attributes that are applied to files will provide information about the current version unless an explicit version number parameter is supplied.

Import/Export Attributes
Remote Development Attributes
Program Source File Attributes
Build Management Attributes
UNIX Filesystem Attributes
Attributes for Internal Rational Use

All sizes are given in bytes.

Miscellaneous Attributes

Switch Keywords

Special keywords are also provided for getting access to Apex switches. The regular switch keyword has the syntax:

<switch (switch-name, default-value)>

where switch-name is the name of any context or session switch and default-value is an optional field. The keyword is replaced by the value of the named switch, however if the value is the empty string and default-value was provided then the keyword is replaced by the default value.

Conditional switch keywords have the syntax:

<if_switch (switch-name, true-value, false-value)>

and

<if_switch_eq (switch-name, test, true-value, false-value)>

where switch-name is the name of any switch. In the first form, the keyword is replaced by the string specified by true-value if the value of switch is true, non-zero, or non-empty (depending on the type of switch) and the keyword is replaced by the false-value string otherwise. In the second form, the keyword is replaced by true-value if the value of the switch is equal to the value of test and the keyword is replaced by false-value otherwise.

Like all boolean-valued keywords, switch values are replaced by the empty string when the switch evaluates to false. This behavior can be altered to emit the value false by using the :b modified as shown in the example below:

<switch(my_switch_name):b>

Keywords are also provided to determine whether or not switches have been set.

<switch_set (switch-name)>

is replaced by true if the switch has been explicitly set on the command line, in the current switch file, or an environment variable.

<option_set (switch-name)>

is replaced by true if the switch was explicitly on the command line.

Literal Keywords

There are also a number of literal keywords that evaluate to punctuation characters. The set of literal keywords is given in Table 19.

Table 19 Literal Keywords
Keyword
Replacement Character
<nil>
empty string
<space>
blank
<tab>
tab
<newline>, <nl>
new line
<comma>, <,>
  ,
<period>, <.>
  .
<colon>, <:>
  :
<semicolon>, <;>
  ;
<exclam>, <!>
  !
<question>, <?>
  ?
<star>, <*>
  *
<plus>, <+>
  +
<minus>, <dash>,<->
  -
<equal>, <=>
  =
<sharp>, <#>
  #
<percent>, <%>
  %
<underline>, <_>
  _
<dollar>, <$>
  $
<ampersand>, <&>
  &
<at>, <@>
  @
<slash>, </>
  /
<backslash>, <\>
  \
<circumflex>, <^>
  ^
<grave>, <`>
  `
<bar>, <|>
  |
<tilde>, <~>
  ~
<single_quote>,<sq>
  `
<double_quote>, <dq>
  "
<less_than>, <lt>
  <
<greater_than>, <gt>
  >
<lparen>, <(>
  (
<rparen>, <)>
  )
<lbrace>, <{>
  {
<rbrace>, <}>
  }
<lbracket>, <[>
  [
<rbracket>, <]>
  ]

Message Prefix Keywords

Keywords are provided for the standard message prefix values as show in Table 20.

Table 20 Message Prefix Keywords
Keyword
Replacement String
<auxiliary_msg>
:::
<debug_msg>
???
<note_msg>
---
<note1_msg>
---
<note2_msg>
---
<note3_msg>
---
<positive_msg>
+++
<position_msg>
>>>
<negative_msg>
++*
<warning_msg
!!!
<error_msg>
***
<exception_msg
%%%
<sharp_msg>
###
<dollar_msg>
$$$
<at_msg>
@@@
<continuation_msg>
...
<internal_error_msg>
&&&
<not_required_msg>
++-
<system_error_msg>
**%

Conditional Keywords

Conditional keywords provide a means for conditional generation of text. Conditional keywords have the form:

<if> boolean-expression
<then> format-string    
<elsif> boolean-expression
<then> format-string
<else> format-string
<endif>

where there can be any number of <elsif> clauses and the <else> clause is optional. The format-string is any string, possibly containing additional keyword tokens including conditional keywords, list keywords and table keywords.

The boolean-expression is an expression involving the operators <eq>, <ne>, <and>, and <or> (with the usual precedence) and parentheses for grouping. The arguments to the operators can be literal strings without spaces, strings including spaces that are quoted using <dq>, and basic keywords. Boolean expressions evaluate to true if the resulting strings are non-empty and false otherwise. Note that consecutive <dq> symbols can be used when one wishes to insert a literal double quote into an expression.

For example, the following conditional expression will list the name of an object and its version number if the object is controlled:

<If> Keyword Boolean Operators

The following new operators are now available in the boolean-expression for the conditional keyword <if>:

<not> boolean-exp
Logically negate boolean-exp
<-r> file
Is file readable?
<-w> file
Is file writable?
<-x> file
Is file executable?
<-e> file
Does file exist?
<-o> file
Does the user own file?
<-z> file
Is file empty (of zero length)?
<-f> file
Is file a normal data file?
<-d> file
Is file a directory?

For example:

List-oriented Keywords

Lists provide a way to handle sets of context objects and to generate sets of context objects. Lists can not be nested.

Simple Lists

Simple lists provide a way to handle sets of context objects. For example, simple lists provide a way to generate a report with the name of each context object on a separate line.

Simple keyword lists have the form:

{ format-string, separator-string }

where format-string can contain any basic keyword expression, conditional keyword expression or literal text. The separator-string is optional and can only contain literal keywords and literal text. When a simple list keyword expression is evaluated in the context of a set of objects, the format-string is evaluated once for each object in the set. The final result consists of individual result strings concatenated together and separated by the evaluation of the separator-string. The order in which objects in the set are processed is not defined.

For example, the following expression would generate a set of simple object names separated by commas:

{<object:t>,<comma>}

Another example provides a way to list all files in the context set that are privately checked out:

{<if><object'private><then><object:t><endif>,<nl>}

Generated Lists

Generated lists provide a way in which to generate a new context object set from original context object set and then evaluate a list for the new context object set. For example, a generated list can be specified to generate the children of a particular directory and then evaluate the list for the set of children.

Generated lists have the syntax:

{ <gen> gen-expression, format-string, separator-string }

where format-string and separator-string have the same meaning as in simple lists.

The gen-expression specifies the way in which the new context set is generated from original set. The gen-expression can have one of the following forms:

Table-oriented Keywords

Table-oriented keywords provide a way to generate a table based on the result of an simple or generated list. For example, tables could be generated from the results of the simple and generated lists described in the previous sections.

Tables have the format:

table-keyword column-description-list { column-list }

The meaning of the different parts of a table format are described below.

Table Keyword

The table-keyword designates that a table is to be constructed and specifies whether or not the rows of the table should be sorted. The table-keyword has the form:

where the sort and sort_numeric fields specify that the table is to be sorted and the integer specifies the column that is to serve as the sort key. The default value of the integer is 1. The value sort specifies that sorting is to be done alphabetically, while the value sort_numeric specifies that sorting is to be done numerically.

Also in a table-keyword the separator is optional and is used to specify any characters that should occur to the left of the first column

Column Description Lists

A column-description-list is a list of column-description entries. Each column-description entry provides a title, justification specification, summary specification, scaling specification and separator for a specific column. A column-description has the following form:

column-title<justification,summary,scale,separator>

where the fields have the following meanings:

column-title

This field is required and is interpreted as literal text that is used as the title for the column.

justification

This field is required and specifies whether the column is to have left justification, right justification, or be centered. The possible values are left, right, center.

summary

This field is optional, If set to the literal value summary then the values in the this column are assumed to be integers that will be summed and the result placed in a final summary row. If this field not set then no summary is produced for the column.

scale

This field is optional. If set then the field has the format:

scale factor precision

where factor is either K, M or G and specifies that the result be scaled by either one thousand, one million or one billion. The precision specifies the digits after the decimal point to display. The default precision is 0. If the scale field is omitted then no scaling occurs. If the scale file is provided without a factor then K is assumed.

separator

This field is optional. If set then value of the field is interpreted as literal text that is used to separate this column from the following column.

A example column-description for a column containing the names of views might be:

View Name<left, >

A column of numbers to be summed might have the column-description:

Line Count<right,summary,scale K 1, >

Column Lists

A column-list has the same syntax as the simple and generated lists described earlier with additional feature that the <column> keyword is used to separate the parts of the list that are to be placed in separate columns and no list separator entries are allowed. For example, the following list can be used to generate the name and cmvc state for a set of context objects:

{<object> <object'cmvc_state>,<nl>}

If this list were to be used to generate the content of table the list would be changed to contain:

{<object><column><object'cmvc_state>}

Table Evaluation

When keyword replacement is performed on a format string containing a table specification, a row of the table is generated for each of the objects in the context set. Note that if the column-list is a generated list then a row of the table will be generated for each of the objects in the generated context set.

For example, the following format string could be used to generate a table containing the simple name of a set of objects and their Apex class:

<table,sort>Name<left, >Class<left>
{<object:t><column><object'class>}

When this string is supplied to the report command as the value of the -format option and the contents of a directory are passed as parameters to the command then the result would appear as:

The table above, could also have been generated if the report command was invoked with just the parent directory as the argument to the command. In this case however, the format string would need to specify a generator to generate the names of the child objects. This format string is shown below:

<table>Name<left, >Class<left>
{gen <dir>/*,<object:t><column><object'class>}

Comments in Keyword Strings

The comment character in keyword replacement strings is "#". Text between "#" and the end of the line is ignored by the keyword replacement process.


Error Handling During Keyword Replacement

There are four different kinds of errors that can occur during keyword replacement:


Keyword Replacement During Command Execution

Keyword replacement occurs implicitly as part of some Apex commands such as check_in. The command typically defines a set of additional simple keywords that can only be used in replacements involving that command or type of command.

Source File Creation

When Ada, C, or C++ source files are created the initial values of the files can be based on prototype files. Prototype files undergo keyword replacement in the context of the new source file and the result is used to provide the initial value of the new source file.

Simple Keywords

In addition to the normal keywords there are several keywords that are only available for use in prototype files. These keywords include:

Version Creation

Keyword replacement during version creation is performed only for Apex/Summit. This section describes the version creation attribute evaluation rules that are applied during a check_in command or other version creation operation. Additional attributes, that are available with these commands, are also listed.

Keyword replacement during version creation scans for strings of the form $string$ or $string: $, where string is any alphanumeric character or an underscore. It is recommended that keyword replacement be applied with extreme caution to files that may contain unintended replacement sequences, such as shell scripts.

Version Creation Attribute Evaluation

Normally, when keywords are evaluated the original keyword tokens are completely replaced by the specified values. During version creation, an alternative syntax is used for evaluating attributes. This syntax allows the original attribute name to be retained and to be followed by its value. This syntax has the form:

$attribute-name: $

where attribute-name is the simple name of a keyword attribute. This can name any of the attributes described in the previous sections.

For example, the expression:

$history: $

would evaluate to:

$history: Common $

Version creation attribute evaluation provides functionality similar to that provided by RCS. The attributes are always evaluated for the file that is being checked in and, like all keywords, are case insensitive.

Additional Attributes

Support is also provided for the RCS attributes named below. Although these keywords are supported for compatibility with RCS, their use is not recommended.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS