TOPS(1) TOPS(1)
NAME
tops - perform in-place substitutions on code.
SYNOPSIS
tops [-help] [-verbose] [-nocontext] [-nofileinfo] [-semiverbose)]
[-dont] (-scriptfile scriptname) (find ""searchpattern"" [where
(""symbol""...) isOneOf {{(""match""...)...}}] ...) (replace ""searchpat-
tern"" with ""replacementpattern"" same [where (""symbol""...) isOneOf
{{(""match""...)...}}]... [within (""symbol"") {{...}}]... [error ""message""]
[warning ""message""]) ( replacemethod ""selector"" with ""newselector""{{
[replace ""symbol"" with ""symbolreplacement""]... }} [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 'Application' should be converted to 'NSApplication'. In
tops syntax, 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 information in ver-
bose 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 scriptname
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 comments, /* ... */.
find ""searchpattern""
Locates all occurrences of searchpattern in the file.
searchpattern can contain literal strings and tokens in angle
brackets, as described below.
where (""symbol""...) isOneOf {{(""match""...)...}}
When searchpattern contains tokens in angle brackets, further
refines what the token specified by symbol should match.
replace ""searchpattern"" with ""replacementpattern"" same
Replaces all occurrences of searchpattern in the file with
replacementpattern. same replaces searchpattern with itself.
You usually use same when you want to print out an error or
warning message instead of replacing the code.
within (""symbol"") {{...}}
Specifies further conversions within one of the tokens specified
in searchpattern. find, replace, and replacemethod rules can
appear within the angle brackets.
error ""message""
Generates an ##error message located at searchpattern.
warning ""message""
Generates a ##warning message located at searchpattern.
replacemethod ""selector"" with ""newselector""
Replaces all invocations, declarations, implementations, and
@@selector expressions using the method selector with newselec-
tor.
-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 spec-
ify more than one filename, separated by spaces. The files are
converted in place; no backups are created. If no file is speci-
fied, 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 partic-
ular syntax element rather than a literal string. The tokens have the
form:
<>
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 <> in the selector,
replacemethod defines the following. The Examples section shows an
example of using one of these.
<>
Represents the tokens in the invocation of the method, that is,
what is supplied for the foo argument.
<>
Represents the type for foo that appears in the declaration.
<>
Represents the parameter in the declaration.
replacemethod also defines the following labels:
<>
Represents the body of the method implementation (not including
curly braces).
<>
Represents the receiver of the message.
<> 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 MyProjectDir/*.[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 invocations, declarations, implementa-
tions, and @@selector expressions.
replacemethod "removeRowAt:andFree:" with
"removeRow:andRelease:"
The following rule marks all calls to the function NXGetNamedObject()
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. <> specifies to replace all of the argu-
ments in between the parentheses as well.
replace "NXGetNamedObject()" with same
error "ApplicationConversion: NXGetNamedObject() is obso-
lete. 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 invo-
cations, it reverses the value specified for the flag argument.
replacemethod "myMethod:" with "myNewMethod:"
{ replace "" with "!" }
The following rule renames the method initContent::style::backing::button-
ask::defer:: to initWithContentRect::styleask::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 "" with "" {
replace "" with "(unsigned int)"
replace "" with "(NSBackingStoreType)"
}
where ("", "") isOneOf { ("initCon-
tent:style: |
