TOPS(1) TOPS(1)

NAME
       tops - perform in-place substitutions on code.

SYNOPSIS
       ttooppss  [-hheellpp]  [-vveerrbboossee]  [-nnooccoonntteexxtt]  [-nnooffiilleeiinnffoo]  [-sseemmiivveerrbboossee)]
       [-ddoonntt]  (-ssccrriippttffiillee  scriptname)  |  (ffiinndd  ""searchpattern""  [wwhheerree
       ((""symbol""...))  iissOOnneeOOff  {{((""match""...))...}}] ...) | (rreeppllaaccee ""searchpat-
       tern"" wwiitthh ""replacementpattern"" | ssaammee  [wwhheerree  ((""symbol""...))  iissOOnneeOOff
       {{((""match""...))...}}]...  [wwiitthhiinn  ((""symbol""))  {{...}}]... [eerrrroorr ""message""]
       [wwaarrnniinngg ""message""]) | ( rreeppllaacceemmeetthhoodd ""selector"" wwiitthh  ""newselector""{{
       [rreeppllaaccee ""symbol"" wwiitthh ""symbolreplacement""]...  }} [wwhheerree ((""symbol""...))
       iissOOnneeOOff {{((""match""  ...))...}}]...  [wwiitthhiinn  ((""symbol""))  {{...}}]...  [eerrrroorr
       ""message""]  [wwaarrnniinngg ""message""] ) [-ccllaassssffiillee classfile] [filename ...]

DESCRIPTION
       ttooppss 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"

OOPPTTIIOONNSS
       -hheellpp  Displays the tops syntax line.

       -vveerrbboossee
              Prints out the source code lines that are being changed  by  the
              command.

       -nnooccoonntteexxtt
              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.

       -nnooffiilleeiinnffoo
              Does not print the file name and line number information in ver-
              bose messages.

       -sseemmiivveerrbboossee
              Shows how much of the file has been processed.

       -ddoonntt  Shows what changes would be made  to  the  source  code  without
              actually performing the changes.

       -ssccrriippttffiillee scriptname
              Specifies  the  script  file containing the rules that tops will
              apply to your code. The script file can contain three  types  of
              rules:  ffiinndd, rreeppllaaccee, and rreeppllaacceemmeetthhoodd. It also can contain C-
              style comments, /* ... */.

       ffiinndd ""searchpattern""
              Locates  all  occurrences  of  searchpattern   in   the   file.
              searchpattern  can  contain literal strings and tokens in angle
              brackets, as described below.

       wwhheerree ((""symbol""...)) iissOOnneeOOff {{((""match""...))...}}
              When searchpattern contains tokens in angle  brackets,  further
              refines what the token specified by symbol should match.

       rreeppllaaccee ""searchpattern"" wwiitthh ""replacementpattern"" | ssaammee
              Replaces  all  occurrences  of  searchpattern  in the file with
              replacementpattern. ssaammee replaces searchpattern  with  itself.
              You  usually  use  ssaammee  when  you want to print out an error or
              warning message instead of replacing the code.

       wwiitthhiinn ((""symbol"")) {{...}}
              Specifies further conversions within one of the tokens specified
              in  searchpattern.  ffiinndd,  rreeppllaaccee, and rreeppllaacceemmeetthhoodd rules can
              appear within the angle brackets.

       eerrrroorr ""message""
              Generates an ##eerrrroorr message located at searchpattern.

       wwaarrnniinngg ""message""
              Generates a ##wwaarrnniinngg message located at searchpattern.

       rreeppllaacceemmeetthhoodd ""selector"" wwiitthh ""newselector""
              Replaces all  invocations,  declarations,  implementations,  and
              @@sseelleeccttoorr  expressions using the method selector with newselec-
              tor.

       -ccllaassssffiillee 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:

       aa      Matches any sequence of tokens.

       bb      Matches  any balanced sequence of tokens, that is, a sequence of
              tokens within parentheses or curly braces.

       ee      Matches any expression. This is the default.

       ss      Matches any string.

       tt      Matches any one token.

       ww      Matches white space, including comments.

       In a rreeppllaacceemmeetthhoodd rule, three subtokens are defined for each token you
       specify  in  the  selector.  For  each  token  <>  in  the selector,
       rreeppllaacceemmeetthhoodd 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.

       rreeppllaacceemmeetthhoodd 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).

EEXXAAMMPPLLEESS
       The following is a typical ttooppss command  invocation.  The  script  file
       MyRules.tops  contains  the ffiinndd, rreeppllaaccee, and rreeppllaacceemmeetthhoodd rules that
       are performed on the files in  MyProjectDir.  The  -sseemmiivveerrbboossee  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    rreemmoovveeRRoowwAAtt::aannddFFrreeee::    to
       rreemmoovveeRRooww::aannddRReelleeaassee:: in  all  invocations,  declarations,  implementa-
       tions, and @@sseelleeccttoorr expressions.

              replacemethod             "removeRowAt:andFree:"            with
              "removeRow:andRelease:"

       The following rule marks all calls to the  function  NNXXGGeettNNaammeeddOObbjjeecctt(())
       with  the  error message. ssaammee means replace this function with itself.
       NNXXGGeettNNaammeeddOObbjjeecctt(()) 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 iinniittCCoonntteenntt::ssttyyllee::bbaacckkiinngg::bbuuttttoonn-
       MMaasskk::ddeeffeerr::   to  iinniittWWiitthhCCoonntteennttRReecctt::ssttyylleeMMaasskk::bbaacckkiinngg::ddeeffeerr::  in  all
       occurrences. In the declarations of this method, it  changes  the  type
       for  the style argument to be uunnssiiggnneedd iinntt and the type for the backing
       argument to be NSBackingStoreType.

              replacemethod "" with "" {
                  replace "" with "(unsigned int)"
                  replace "" with "(NSBackingStoreType)"
                  }
                  where   ("",   "")   isOneOf   {        ("initCon-
              tent:style: