TOPS(1) TOPS(1)
NAME
tops - perform in-place substitutions on code.
SYNOPSIS
tops [-help] [-verbose] [-nocontext] [-nofileinfo]
[-semiverbose)] [-dont] (-scriptfile script_name) | (find
"search_pattern" [where ("symbol"...) isOneOf
{("match"...)...}] ...) | (replace "search_pattern" with
"replacement_pattern" | same [where ("symbol"...) isOneOf
{("match"...)...}]... [within ("symbol") {...}]... [error
"message"] [warning "message"]) | ( replacemethod "selec-
tor" with "new_selector"{ [replace "symbol" with "sym-
bol_replacement"]... } [where ("symbol"...) isOneOf
{("match" ...)...}]... [within ("symbol") {...}]... [error
"message"] [warning "message"] ) [-classfile classfile]
[filename ...]
DESCRIPTION
tops is a tool that performs in-place substitutions on
source files according to a set of rules. Each tops rule
describes a particular translation. For example, one tops
rule might specify that occurrences of the token 'Applica-
tion' should be converted to 'NSApplication'. In tops syn-
tax, this rule will appear as:
replace "Application" with "NSApplication"
OPTIONS
-help Displays the tops syntax line.
-verbose
Prints out the source code lines that are being
changed by the command.
-nocontext
Instead of printing the whole source code line that
is being changed or searched for, shows only the
portion of the line that has the change.
-nofileinfo
Does not print the file name and line number infor-
mation in verbose messages.
-semiverbose
Shows how much of the file has been processed.
-dont Shows what changes would be made to the source code
without actually performing the changes.
-scriptfile script_name
Specifies the script file containing the rules that
tops will apply to your code. The script file can
contain three types of rules: find, replace, and
replacemethod. It also can contain C-style com-
ments, /* ... */.
find "search_pattern"
Locates all occurrences of search_pattern in the
file. search_pattern can contain literal strings
and tokens in angle brackets, as described below.
where ("symbol"...) isOneOf {("match"...)...}
When search_pattern contains tokens in angle brack-
ets, further refines what the token specified by
symbol should match.
replace "search_pattern" with "replacement_pattern" | same
Replaces all occurrences of search_pattern in the
file with replacement_pattern. same replaces
search_pattern with itself. You usually use same
when you want to print out an error or warning mes-
sage instead of replacing the code.
within ("symbol") {...}
Specifies further conversions within one of the
tokens specified in search_pattern. find, replace,
and replacemethod rules can appear within the angle
brackets.
error "message"
Generates an #error message located at search_pat-
tern.
warning "message"
Generates a #warning message located at search_pat-
tern.
replacemethod "selector" with "new_selector"
Replaces all invocations, declarations, implementa-
tions, and @selector expressions using the method
selector with new_selector.
-classfile classfile
Specifies a file that describes the class hierarchy
used by the files being processed.
filename ...
Specifies the source file(s) you want to convert.
You can specify more than one filename, separated
by spaces. The files are converted in place; no
backups are created. If no file is specified, the
tops commands are performed on standard input.
The simplest search pattern is a literal string, such as
"Application". Within the search pattern, you can define
tokens that specify a particular syntax element rather
than a literal string. The tokens have the form:
<type label>
where:
type Specifies the type of syntax element the token can
match with.
label Is a unique label that you assign to the token.
type can be one of the following:
a Matches any sequence of tokens.
b Matches any balanced sequence of tokens, that is, a
sequence of tokens within parentheses or curly
braces.
e Matches any expression. This is the default.
s Matches any string.
t Matches any one token.
w Matches white space, including comments.
In a replacemethod rule, three subtokens are defined for
each token you specify in the selector. For each token
<foo> in the selector, replacemethod defines the follow-
ing. The Examples section shows an example of using one of
these.
<foo_arg>
Represents the tokens in the invocation of the
method, that is, what is supplied for the foo argu-
ment.
<foo_type>
Represents the type for foo that appears in the
declaration.
<foo_param>
Represents the parameter in the declaration.
replacemethod also defines the following labels:
<implementation>
Represents the body of the method implementation
(not including curly braces).
<receiver>
Represents the receiver of the message.
<call> Represents the entire method invocation (including
the square brackets).
EXAMPLES
The following is a typical tops command invocation. The
script file MyRules.tops contains the find, replace, and
replacemethod rules that are performed on the files in
MyProjectDir. The -semiverbose option means that name of
the file being processed and the progress of the command
will be printed to standard output.
tops -semiverbose -scriptfile MyRules.tops MyPro-
jectDir/*.[hm]
The following is a typical rule that a tops script file
would contain. The rule renames the method
removeRowAt:andFree: to removeRow:andRelease: in all invo-
cations, declarations, implementations, and @selector
expressions.
replacemethod "removeRowAt:andFree:" with
"removeRow:andRelease:"
The following rule marks all calls to the function NXGet-
NamedObject() with the error message. same means replace
this function with itself. NXGetNamedObject() will still
appear in the file, but it will be marked by the error
message. <b args> specifies to replace all of the argu-
ments in between the parentheses as well.
replace "NXGetNamedObject(<b args>)" with same
error "ApplicationConversion: NXGetNamedOb-
ject() is obsolete. Replace with nib file outlets."
The following rule renames the method in all occurrences,
and swaps the second and third argument in all invocations
and declarations.
replacemethod "browser:fillMatrix:<2>inColumn:<3>"
with "browser:createRowsForColumn:<3>inMatrix:<2>"
The following rule renames the method in all occurrences.
In the invocations, it reverses the value specified for
the flag argument.
replacemethod "myMethod:<flag>" with
"myNewMethod:<flag>"
{ replace "<flag_arg>" with "!<flag_arg>" }
The following rule renames the method initCon-
tent:style:backing:buttonMask:defer: to initWithCon-
tentRect:styleMask:backing:defer: in all occurrences. In
the declarations of this method, it changes the type for
the style argument to be unsigned int and the type for the
backing argument to be NSBackingStoreType.
replacemethod "<old>" with "<new>" {
replace "<style_type>" with "(unsigned int)"
replace "<backing_type>" with "(NSBackingStore-
Type)"
}
where ("<old>", "<new>") isOneOf { ("init-
Content:style:<style> backing:<backing> button-
Mask:<bmask> defer:<flag>", "initWithCon-
tentRect:styleMask:<style> backing:<backing>
defer:<flag>"),
}
The following rule renames the method min-
FrameWidth:forStyle:buttonMask: to minFrameWidthWithTi-
tle:styleMask: in all occurrences. Within invocations of
this method, it changes the style argument to be the logi-
cal OR of the previous style argument and the previous
button mask argument. Within method declarations, it
changes the type for the style argument to be unsigned
int. Within the implementation of this method, it changes
all uses of the button mask argument to the style argu-
ment.
replacemethod "minFrameWidth:forStyle:<style> but-
tonMask:<bmask>" with "minFrameWidthWithTi-
tle:styleMask:<style>" {
replace "<style_arg>" with
"<style_arg>|<bmask_arg>"
replace "<style_type>" with "(unsigned int)"
}
within ("<implementation") { replace
"<bmask_param>" "<style_param>"
}
Apple Computer, Inc. March 14, 1995 TOPS(1)