Framework code for compilerlike scripts.

1 files changed, 87 insertions, 0 deletions

diff --git a/Doc/lib/libcompilerlike.tex b/Doc/lib/libcompilerlike.tex
new file mode 100644
index 0000000..3e9daff
--- /dev/null
+++ b/Doc/lib/libcompilerlike.tex
@@ -0,0 +1,87 @@
+\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, arguments, trans_data\optional{,trans_file}}
+Filter using a function taking the name 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,arguments,trans_data\optional{,trans_file}}
+Filter using a function taking the name 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, arguments, trans_data\optional{, trans_file}}
+Filter using a function taking the name 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
+
+