-- TransDoc.tioga
-- last edited by: R. Nix, April 12, 1984 6:59:40 pm PST
name  Trans:
<<description>>
<<trans [switches]  [pattern replacement] fileNames>>
<<Trans does a pattern-directed global substitution to a group of files.  Trans has a subset of the functionality of the EditTool's 
substitute command; however, it is better suited to the task of performing 50 different global substitutions to each of 50 files. >>
<<Trans's main shortcoming is that it cannot deal with Tioga node structure.  It's not that it deals with nodes badly -- it doesn't 
deal with them at all.  C'est la vie; somebody should write a Streams-like or Rope-like interface to editing Tioga documents in 
order to make such things easier.>>
<<Trans may be viewed as transforming files filled with records; the pattern is used to specify the format of the records to be 
transformed.  The replacement is used to specify how you want the record  to change.  >>
<<The pattern syntax is given in RegularExpressionDoc.tioga.  You delimit the fields of the record using the <> notation, e.g. the 
pattern ``<lastName>, <firstName>\n'' might match a list of names.  The replacement syntax is similar to the EditTool's, in that 
the replacement expression ``<firstName> <lastName>\n'' will interchange the order of names in the text matched by the pattern.  
Note that apostrophe, ``''', is the quote-character, in case you want to stick a ``<'' in a replacement.  There are special purpose 
hacks for changing field capitalization: ``<lastName:u>'' would capitalize the ``<lastName>'' field,  ``<lastName:l>'' would make 
it be all lower case.  >>
<<Trans accepts lots of switches:>>
<<-pattern (-p)  
By default, Trans interprets the pattern as a regular expression using the syntax described in RegularExpressionDoc.tioga.>>
<<-literal (-l)
If this switch is given, then Trans interprets patterns as literal text.>>
<<-caseSensitive (-c)  
Capitalization is significant in matching the pattern agains the text.>>
<<-ignoreCase (-i)
By default, Trans ignores capitalization differences when matching the pattern against the text.>>
<<-wordMatch (-w)
Match text only on word boundaries.>>
<<-matchAnywhere (-m)  
By default, Trans will match the pattern anywhere.>>
<<-deleteMatched (-d)
If the -d switch is given, then no replacement expression should be given, and Trans will delete all text that matches the pattern. 
 This switch is necessary because the CommandTool's command line parser doesn't parse "" as a token.>>
<<-selectMatched (-s)
If this switch is given, then Trans will delete all text that doesn't match the pattern, and will apply the given replacement to 
the text that does match the pattern.>>
<<-replaceMatched (-t)
By default, Trans replaces text that matches the pattern with the text determined by the replacement expression, copying the text 
that doesn't match the pattern over into the output.>>
<<-appendFile (-a)
This switch takes an argument, which is the name of a file to which all output will be appended.  Normally when a list of file 
names is given, each file is processed separately, and output is written to a new generation of each file.   This switch is useful, 
in conjunction with the -s switch, for doing something like collecting the names of all procedures defined in a set of files.>>
<<-filePatterns (-f)
This is how you tell Trans to do more than one pattern => replacement transformation.  This switch takes an argument, which is the 
name of a file.  Each line of the file should be a Trans command line, sans file names, but including any switches that you'd like 
to be in effect (including other -f switches).  Trans will apply each of the commands in the file to each of the files specified on 
the command line.  Switch settings are dynamically scoped, e.g. the switch settings given on the command line specify the defaults 
for each pattern-replacement line in the file, but each pattern-replacement line can override those defaults.>>
<<>>
<<bugs>>
<<Trans knows nothing about Tioga formatting.>>
<<implementation >>
<<TransImpl.mesa in Trans.df>>
<<contact>>
<<Bob Nix <Nix.pa>>>