A command-line tool for literal text substitution.
Warning: this tool is useful for my needs but other programs like sed, the
C preprocessor, M4, etc., are better choices in most cases.
This is included in the artools package, available from the easyVision repository. Clone the repo, checkout the branch reorg, cd packages/tools, and cabal install.
$ hreplace [--rules='lhs=rhs;...'] [--latex] [--pure] < infile > outfile
If the program is called with --pure only the rules explicitly given in the
command line will be applied. Otherwise the following "commands" are also available:
!DEFINE lhs=rhs;lhs=rhs;...: add new replacement rules.
!DATE: insert the compilation date.
!IGNORE(hidden text): comment out text.
!QUOTE(text): quote text so that it can be printed by Haskell functions.
!INCLUDE(filename): include file.
!INCLUDE(filename string): include the contents of file from the first appearance of string until 2 newlines.
!REPLACE(things !WITH local rules) apply rules in a local scope.
!HSCOLOUR(something): pretty print inline.
The arguments can be:
enclosed by round, square, curly, or angled brackets
delimited by ":" or " " and a newline/end-of-string
delimited by any character not appearing in the argument string
No attempt is made to parse the text, so different delimiters must be used for nested functions calls. Things can go wrong in many unexpected ways with high probability. But in many cases using just space - newline allows for a clean syntax without explicit nested brackets.
By default multiple arguments in user defined rules are separated by spaces, but a different separator can be given as a first argument preceded by a single quote.
Extra separators are ignored and the last argument contains the rest of the string.
The characters used in the definition of rules such as " ", "=", ";", as well as newlines can be used in the lhs and rhs of the rules using special names.
By default rules don't evaluate their arguments and the results are reevaluated in the outer context to continue macro expansion. This behavior can be changed as follows:
If the function name is followed by ">" the arguments are evaluated before the rule is applied. (For example, this is needed for macros which perform substitutions on the contents of an included file.)
If the function name or lhs of a rule is preceded by "#" the result of the rule is kept unevaluated.
The main interest of this tool is the possibility of adding new transformation rules
written in Haskell. The executable program hreplace is just a wrapper to
the function ioReplace supplied by the module Util.Replace in the package
artools.
This tool is the basis of mkwb, the program used to generate these pages.