tops - perform in-place substitutions on code.
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
"selector" with
"new_selector"{ [replace
"symbol" with
"symbol_replacement"]... } [where
("symbol"...) isOneOf
{("match" ...)...}]... [within
("symbol") {...}]... [error
"message"] [warning
"message"] ) [-classfile
classfile] [filename ...]
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"
- -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 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
comments, /* ... */.
- 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 brackets, 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 message 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_pattern.
- warning
"message"
- Generates a #warning message located at search_pattern.
- replacemethod
"selector" with
"new_selector"
- Replaces all invocations, declarations, implementations, 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 following. 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 argument.
- <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).
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,
implementations, 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. <b args>
specifies to replace all of the arguments in between the parentheses as
well.
- replace "NXGetNamedObject(<b args>)" with same
error "ApplicationConversion: NXGetNamedObject() 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
initContent:style:backing:buttonMask:defer: to
initWithContentRect: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
"(NSBackingStoreType)"
}
where ("<old>", "<new>") isOneOf {
("initContent:style:<style> backing:<backing>
buttonMask:<bmask> defer:<flag>",
"initWithContentRect:styleMask:<style> backing:<backing>
defer:<flag>"),
}
The following rule renames the method
minFrameWidth:forStyle:buttonMask: to
minFrameWidthWithTitle:styleMask: in all occurrences. Within
invocations of this method, it changes the style argument to be the logical
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 argument.
- replacemethod "minFrameWidth:forStyle:<style>
buttonMask:<bmask>" with
"minFrameWidthWithTitle:styleMask:<style>" {
replace "<style_arg>" with
"<style_arg>|<bmask_arg>"
replace "<style_type>" with "(unsigned int)"
}
within ("<implementation") { replace
"<bmask_param>" "<style_param>"
}