TOPS(1) 						      General Commands Manual							   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 ("sym-
       bol"...) 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 ...]

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 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  usu-
	      ally 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  con-
	      verted 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).

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, 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>"
		  }

Apple Computer, Inc.						  March 14, 1995							   TOPS(1)