![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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:
- Access Apex information sources such as:
- Version control information
- Configuration management information
- UNIX filesystem information
- Object relationships
- Switch values
- Perform C-shell-style name modification
- Perform conditional keyword replacement
- Generate lists
- Generate tables
Keyword replacement occurs as part of a number of different Apex operations including:
- Source File Creation
Ada, C and C++ source files can be created with initial contents based on prototype files that undergo keyword replacement.
- Version Creation
For Apex/Summit, keyword replacement is applied to file contents prior to check in. This allows the file contents to be modified based on version control information. For example, the file can be customized to contain its version number.
In the following example, the keyword variables $date$ and $object$ are expanded into strings when the file is checked in.
Before control:
-- File Name: Test.ada -- $object$ -- $date$ procedure Test is begin null; end Test;After control and subsequent check_out:
Add a comment that specifies the version number:
-- File Name: Test.ada -- $object: /vc/mstepien/key.ss/view.wrk/Test.ada $ -- $date: 03/25/1999 11:12:12 $ procedure Test is begin null; end Test;
-- $version$After check_in:
-- File Name: Test.ada -- $object: /vc/mstepien/key.ss/view.wrk/Test.ada $ -- $version: 5 $ -- $date: 04/24/2000 10:10:10 $ procedure Test is begin null; end Test;- Report Generation
Reports can be generated based on format strings that undergo keyword replacement.
- Build Management
The Build Management system uses keyword replacement to control the meaning of build commands and to control the contents of makefiles.
Keyword Replacement ProcessThe 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 SyntaxKeywords 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.
- <object>
Replaced by the pathname of the context object.
- <directory> or <dir>
Replaced by the pathname of the directory containing the context object. If the context object is itself a directory then the name of the context object is used.
- <view>
For Apex/ClearCase, replaced by the pathname of the Rational subsystem (rss) containing the context object. If the context object is itself an rss then the name of the context object is used. If the context object is not in an rss then the empty string is used.
- <subsystem> or <ss>
- <user>
- <machine>
The name of the machine upon which the command is running.
- <time>
The current local time and date.
- <gm_time>
The current GMT time and date.
- <options>
The options of the current Apex command.
- <arguments> or <args>
The arguments of the current Apex command.
- <resolve pathname default>
If the pathname resolves to an object then replace the keyword with the canonical pathname of the object (after applying any attributes and modifiers). If the pathname does not resolve then replace the keyword with the optional default value.
- <$environment-variable>
Where environment-variable is the name of any UNIX environment variable. If the variable is defined then the keyword is replaced by its value, subject to any modifiers, attributes, etc. If the variable is not defined then the keyword is replaced by the empty string.
- <quote> or <q>
Used to quote keywords to disable replacement. Keyword replacement is disabled between two matching quote keywords.
- <vobtag> (Apex/ClearCase)
The VOB-TAB for the current directory.
- <setview> (Apex/ClearCase)
The current ClearCase setview.
- <wdview> (Apex/ClearCase)
The ClearCase view of the current working directory
- <library_context>
Either the name or the enclosing ClearCase style subsystem or the name of the enclosing Summit/CM view.
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:
- h
Remove a trailing name segment, leaving the head.
- r
Remove a trailing suffix, leaving the basename.
- e
- t
Remove all but the last name segment.
- s
Generate the subsystem-relative name from the current name.
- v
Generate the view-relative name from the current name.
- c
- u
Change the current name to upper case.
- l
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:
- no_date
- cdate
- locale_date
- short_date
- expanded_date
- year
- month_day_year
- day_month_year
- year_month_day
- ada_date
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:
- no_time
No clock time portion is displayed.
- ctime
- locale_time
- expanded_time
- military_time
- short_time
- ada_time
The default is :month_day_year:military_time.
Miscellaneous Modifiers
- b
Boolean modifier. If the value is "false" or empty then causes replacement by "false". Otherwise causes replacement by "true".
- n
Boolean negation modifier. If the value is "false" or empty then causes replacement by "true". Otherwise causes replacement by "false".
- q
Put a set of objects into a single string with entries separated by spaces. This is implied at the end of a string.
- substXY
Replace the character X by the character Y in the current string.
- subst(pattern-string, replacement-string)
Replaces all occurrences of pattern-string by replacement-string.
- append(string)
Append the designated string if the current string is not empty.
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
- class
The Apex object class of the named object.
- directory
The enclosing directory of the object.
- subsystem
The subsystem associated with the object.
- view
Subsystem and View Attributes
- host_architecture
The host architecture associated with the library context.
- languages
The languages that can be compiled in the library context. The possible values are "Ada" and "C++".
- model
The model associated with the view.
- storage
The parent directory of the physical storage directory of the view or subsystem.
- target_architecture
The target architecture associated with the view.
- view_kind
- switch(switch-name, default-value)
Replaced by the value of the switch in the view or subsystem.
- if_switch (switch-name, true-value, false-value)
Replaced by true-value or false-value depending on the value of the switch in the view or subsystem.
- if_switch_eq (switch-name, test, true-value, false-value)
Replaced by true-value or false-value if the value of the switch in the view or subsystem is equal or not equal to the value of the test field.
- switch_set (switch-name)
Replaced by true if the value of the switch in the view or subsystem is set.
- imported_view(subsystem-name)
The full pathname of the view that the given view-object imports from subsystem-name. If no such import exists, then the empty string is returned. The subsystem-name argument can be either a full pathname or a simple name of a subsystem.
Access Control Attributes (Apex/ClearCase)
- access_category
The Apex access category associated with the object.
- group
The UNIX group associated with the object.
- owner
- umask
The mask that would be used by the UNIX umask command to create objects with permissions consistent with the Apex access category.
ClearCase Attributes (Apex/ClearCase)
- extended_name
The version extended name of the object.
- branch
The name of the ClearCase branch associated with the object.
- rule
The Rule used to select the object in the current view.
- element_type
The type of the object. ClearCase allows definition of new element types but the predefined element types (in the magic file) are file, compressed_file, text_file, compressed_text_file, binary_delta_file, html, ms_word, rose, xml, directory and file_system_object (Generic element type, with no associated type manager)
- comments
- activities
Alias for tasks. Lists UCM activities attached to a version.
- vob_branches
Alias for subsystem_histories. Lists all branch types defined for the context VOB.
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.
- added_lines [(version-number) [,version-number])]
The total number of lines added between the two versions.
- author [(version-number)]
The name of the user who checked in the file. Same as check_in_user.
- change_regions [(version-number [, version-number])]
The total number of change regions between the specified versions.
- checked_in
Replaced by "true" if the object is checked in, replaced by the empty string otherwise.
- checked_out
Replaced by "true" if the object is checked out with a reservation, replaced by the empty string otherwise.
- check_in_user [(version-number)]
check_in_time [(version-number)]
check_in_view [(version-number)]The check in user, time, and view of the version associated with the context object.
- check_out_user [(version-number)]
check_out_time [(version-number)]
check_out_view [(version-number)]The check out user, time, and view of the version associated with the context object.
- cmvc_state [(version-number)]
The checked in/out state of the context object. The possible replacement values are "checked_in", "checked_out", "private" and "uncontrolled".
- contains_checked_out
Replaced by "true" if the directory contains files that are checked out with reservation, replaced by the empty string otherwise.
- contains_controlled
Replaced by "true" if the directory contains files that are controlled, replaced by the empty string otherwise.
- contains_private
Replaced by "true" if the directory contains files that are privately checked out, replaced by the empty string otherwise.
- controlled
Replaced by "true" if the object is controlled, replaced by the empty string otherwise.
- date
The check in time of the file. Same as check_in_time.
- deleted_lines [(version-number [,version-number])]
The lines deleted between the specified versions.
- element
The version control element associated with the object.
- history
The name of the version control history associated with the context object. If the object is a view then the default history is supplied.
- latest_check_in_user
latest_check_in_time
latest_check_in_viewThe check in user, time and view of the latest version.
- latest_check_out_user
latest_check_out_time
latest_check_out_viewThe check out user, time, and view of the latest version.
- latest_state
The checked in/out state of the latest version on the history of the context object.
- latest_version
The version number of the latest version in the history of the context object.
- notes [(version-number)]
Replaced by the notes associated with the specified version.
- private
Replaced by "true" if the object is privately checked out, replaced by the empty string otherwise.
- version
The version number of the context object.
- version_name
The full version name of the object. This includes the subsystem, element, history and version number.
- subsytem_histories
A list of simple names of the histories that are defined in the enclosing subsystem.
- tasks [(version-number)]
Replaced by the tasks associated with the specified version.
- up_to_date
Replaced by "true" if the file is controlled and has the latest version. Replaced by the empty string otherwise.
- Extended Version Attributes
All extended version attributes can used in the same way as predefined attributes. Extended attributes can be given with or without explicit version numbers.
- attr_name
A special attribute that can only be applied to object produced by the attribute generator. This will produce the name of the attribute.
- attr_value
A special attribute that can only be applied to object produced by the attribute generator. This will produce the name of the attribute.
Import/Export Attributes
- export_set
The export set being used for the current import object. Only available in lists when the imports of a context object are being processed.
- import_kind
The kind of the current import object. Only available in lists when the imports of a context object are being processed.
- import_status
The status of the current import object. Only available in lists when the imports of a context object are being processed.
Remote Development Attributes
- remote
Replace by "true" if the view of subsystem is in a remote domain.
- orphan
Replaced by "true" if the view or subsystem is in a remote domain and is not accessible.
- remote_domain
If the view or subsystem is in a remote domain then the name of the domain is provided.
Program Source File Attributes
- blank_lines
The total number of blank lines in the file. If applied to a directory then this evaluates to the total number of blank lines in all Ada, C and C++ source files in the directory.
- comment_lines
The total number of comment lines in the file. If applied to a directory then this evaluates to the total number of comment lines in all Ada, C and C++ source files in the directory.
- object_file
The pathname of the object file associated with the named source file.
- source_lines
The total number of programming language source lines in the file. If applied to a directory then this evaluates to the total number of programming language source lines in all Ada, C and C++ source files in the directory. This count does not include blank lines or comment lines.
- total_lines
The total number of lines in the file. This value will equal the total of the `blank_lines, `comment_lines, and `source_lines. If applied to a directory then this evaluates to the total number of lines in all Ada, C and C++ source files in the directory.
- total_core_files
The total number of core files in the directory.
- total_executable_files
The total number of executables in the directory.
- total_object_files
The total number of object files in the directory.
- total_source_files
The total number of Ada, C, and C++ source files in the directory.
Build Management Attributes
- compile_closure
Replaced by "true" if current command options and switches in the enclosing view specify compilation of the closure when building libraries or linking main programs. Replaced by the empty string otherwise.
- registered_in_ignore
Replaced by "true" if the object is a C/C++ file that is registered as a file to ignore, replaced by the empty string otherwise.
- registered_in_main
Replaced by "true" if the object is a C/C++ file that is registered as a main program, replaced by the empty string otherwise.
UNIX Filesystem Attributes
- group
- last_accessed
The time the object was last accessed.
- last_changed
The time the status of the object was last changed.
- last_modified
The time the object was last modified.
- owner
- permission
Attributes for Internal Rational Use
- total_cna_files
- total_cna_size
- total_core_size
- total_executable_size
- total_object_size
Total size of object files in the specified view.
- total_size
Total size of specified object and child objects.
- total_templates_files
Total number of files in .templates directory.
- total_templates_size
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)>
<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:
Keywords are also provided to determine whether or not switches have been set.
is replaced by true if the switch has been explicitly set on the command line, in the current switch file, or an environment variable.
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.
Message Prefix Keywords
Keywords are provided for the standard message prefix values as show in Table 20.
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> <object'controlled> <then> <object:t> <object'version> <endif>
<If> Keyword Boolean Operators
The following new operators are now available in the boolean-expression for the conditional keyword <if>:
apex report -format "<if> <-f><object><and><not><-z><object> <then> <object:t> is a data file and not empty <endif>" foo
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:
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:
- context
The new context set is identical to the old context set.
- controlled_files
uncontrolled_files
checked_in_files
checked_out_files
private_files
out_of_date_filesIf the context set contains a directory then all child objects with the designated version control state will be added to the result context set. If the context set contains a file then the file will be added to the result context set if its version control state matches the specified value.
- versions
Generate the set of all versions for the context objects. In the format-string associated with the generator, version-oriented attributes will be associated with the value corresponding to the specified version. For example, the following command will list all version numbers.
"{<gen> versions, <object'version>,<nl>}"
- attributes
Generate the set of attributes associated with the current version of the context objects. In the format-string associated with the generator, special attribute-oriented attributes will be associated with the value corresponding to the specified version. For example, the following command will list all of the attributes that have been set for the current version of the context object.
"{<gen> attributes, <object'attr_name>,<nl>}"
- all_imports
explicit_imports | imports
implicit_imports | closure_imports
mutual_importsThe specified imports are added to the result context set.
- views
working_views
release_viewsGenerate the designated views in the current subsystem context.
- resolve pathname
The pathname is resolved and the resulting objects are added to the new context set. For example, the following expression would list the names of all of the children of original context objects:
{ <gen> resolve <object>/*, <object>,<comma>}
Note that any keywords in the pathname are evaluated against the original context set while keywords in the format-string are evaluated against the new context set.
- expand indirect-files ...
The indirect file is read and the contents are added to the result context set. In particular, if the indirect file names a configuration the contents of the configuration are read and added to the context set. For example, the following expression would list the views referenced by a configuration in the enclosing view:
{ <gen> expand <view>/config.cfg, <object> }
Note that any keywords in the indirect-files are evaluated against the original context set while keywords in the format-string are evaluated against the new context set.
In certain special cases the <gen> keyword can also contain additional information that is used to order the generated items. The following order specifications are supported:
- <gen,order imports>
Specifies that the generated items should be ordered based on their import relationships. Only applies to views.
- labels (Apex/ClearCase)
Generates the set of labels associated with the current version of the context objects. In the format-string associated with the generator, special label_name attribute will be associated with the value corresponding to the specified version. For example, the following command will list all of the labels that have been attached to the current version of the context object:
{<gen> labels, <object'label_name>,<nl>}
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.
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:
- <table, separator> or
- <table, sort integer, separator> or
- <table, sort_numeric integer, separator>
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:
This field is required and is interpreted as literal text that is used as the title for the column.
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.
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.
This field is optional. If set then the field has the format:
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.
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:
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:
Name Class --------- --------- lower.ss Subsystem middle.ss Subsystem upper.ss Subsystem
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 ReplacementThere are four different kinds of errors that can occur during keyword replacement:
- Keyword Syntax Error
Syntax errors occur when keyword expressions cannot be parsed or when an unknown keyword, attribute or modifier is used. When a keyword syntax error occurs an error message is emitted and no replacement occurs.
- Undefined Keyword Error
An undefined error occurs when an attribute or modifier is applied to a name for which it is not defined. For example, if an undefined switch name is used in a <switch()> keyword then an undefined error occurs. When an "undefined" error occurs the value of the replacement string is set to the value of $APEX_KEYWORD_UNDEFINED whose default value is "undefined".
- No_Object Keyword Error
A no_object error occurs when a named object does not exist. For example, if the <resolve> keyword is applied to a pathname that does not name an object then a no_object keyword error occurs. When this error occurs the replacement string is set to the value of $APEX_KEYWORD_NO_OBJECT whose default value is "object_does_not_exist".
- Other Keyword Error
For any other errors the value of the replacement string is set to the value of $APEX_KEYWORD_ERROR whose default value is "error".
Keyword Replacement During Command ExecutionKeyword 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:
- <name> or <unit>
- <unit_kind>
- <parent_unit> (Ada only)
When an Ada unit is created this keyword evaluates to the name of the parent unit if one exists.
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:
where attribute-name is the simple name of a keyword attribute. This can name any of the attributes described in the previous sections.
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
- $version_log$
This keyword causes version information for the version being checked in to be inserted immediately below the keyword. Each line of the inserted text will be preceded by the characters preceding the first $ in $version_log: $. This provides a mechanism to precede the version information with comment characters.
Because each version creation inserts new text following the keyword, this keyword effectively causes a version log to be inserted in the file.
Support is also provided for the RCS attributes named below. Although these keywords are supported for compatibility with RCS, their use is not recommended.
- $Header$
- $Id$
- $Locker$
- $Log$
- $RCSfile$
- $Revision$
- $Source$
- $State$
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |