mirror of
https://github.com/python/cpython.git
synced 2025-11-04 11:49:12 +00:00
87 lines
4.2 KiB
TeX
87 lines
4.2 KiB
TeX
\section{\module{compilerlike} ---
|
|
framework code for building compiler-like programs.}
|
|
|
|
\declaremodule{standard}{set}
|
|
\modulesynopsis{Framework code for building compiler-like programs.}
|
|
\moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
|
|
\sectionauthor{Eric S. Raymond}{esr@thyrsus.com}
|
|
|
|
There is a common `compiler-like' pattern in Unix scripts which is useful
|
|
for translation utilities of all sorts. A program following this pattern
|
|
behaves as a filter when no argument files are specified on the command
|
|
line, but otherwise transforms each file individually into a corresponding
|
|
output file.
|
|
|
|
The \function{filefilter}, \function{linefilter}, and
|
|
\function{sponge} functions in this module provide a framework and
|
|
glue code to make such programs easy to write. You supply a function
|
|
to massage the file data; depending on which entry point you use, it
|
|
can take input and output file pointers, or it can take a string
|
|
consisting of the entire file's data and return a replacement, or it
|
|
can take in succession strings consisting of each of the file's lines
|
|
and return a translated line for each.
|
|
|
|
All three of these entry points take a name, an argument list of files,
|
|
a data transformation function, and a name transformation function.
|
|
They differ only in the arguments they pass to the transformation
|
|
function when it is called.
|
|
|
|
The name argument is not used by the functions in this module, it is
|
|
simply passed as the first argument to the transformation function.
|
|
Typically it is a string that names the filter and is used in
|
|
generating error messages, but it could be arbitrary data.
|
|
|
|
The second argument is interpreted as a list of filenames. The files
|
|
are transformed in left to right order in the list. A filename
|
|
consisting of a dash is interpreted as a directive to read from
|
|
standard input (this can be useful in pipelines).
|
|
|
|
The third argument is the data transformation function.
|
|
Interpretation of this argument varies across the three
|
|
entry points and is described below.
|
|
|
|
The fourth, optional argument is a name transformation function or
|
|
name suffix string. If it is of string type, the shortest suffix of each
|
|
filename beginning with the first character of the argument string
|
|
is stripped off. If the first character of the argument does not
|
|
occur in the filename, no suffix is removed. Then the name suffix
|
|
argument is concatenated to the end of the stripped filename. (Thus,
|
|
a name suffix argument of ".x" will cause the filenames foo.c and
|
|
bar.d to be transformed to foo.x and bar.x respectively.)
|
|
|
|
If the fourth argument is specified and is a function, the name of the
|
|
input file is passed to it and the return value of the function
|
|
becomes the name of the output software. If this argument is not
|
|
specified, the imnput file is replaced with the transformed version.
|
|
|
|
Replacement of each file is atomic and doesn't occur until the
|
|
translation of that file has completed. Any tempfiles are removed
|
|
automatically on any exception thrown by the translation function,
|
|
and the exception is then passed upwards.
|
|
|
|
\begin{funcdesc}{filefilter}{name, file, arguments, trans_data\optional{,trans_file}}
|
|
Filter using a function taking the name, filename, and two file-object
|
|
arguments. The function is expected to read data from the input file
|
|
object, transform it, and write the data to the output file object.
|
|
When the function terminates, the translation is done. The return
|
|
value of the transformation function is not used.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{linefilter}{name, file, arguments,trans_data\optional{,trans_file}}
|
|
Filter using a function taking the name, the filename, and a string
|
|
argument. The return value of the function should be a string. This
|
|
function is applied to each line in the input file in turn; the return
|
|
values become the lines of the transformed file.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sponge}{name, file, arguments, trans_data\optional{, trans_file}}
|
|
Filter using a function taking the name, the filename, and a string
|
|
argument. The return value of the function should be a string. The
|
|
function will be passed the entire contents of the input file as a
|
|
string. The string return value of the function will become the
|
|
entire contents of the transformed file.
|
|
\end{funcdesc}
|
|
|
|
# End
|
|
|
|
|