TXL(1) TXL(1) NAME txl - TXL Programming Language Compiler/Interpreter (Version 10.5) SYNOPSIS txl [ options ] [ -ooutputfile ] inputfile [ txlfile ] [ - useroptions] DESCRIPTION TXL is a programming language specifically designed to support trans- formational programming. The basic paradigm of TXL involves trans- forming input to output using a set of structural transformation rules that describe by example how different parts of the input are to be changed into output. Each TXL program defines its own context free grammar according to which the input is to be parsed, and rules are constrained to preserve grammatical structure in order to guarantee a well-formed result. The TXL intepreter is a general purpose source-to-source transformation system, well suited to a wide class of computational problems but par- ticularly adept at language processing. TXL has been used for rapid prototyping of new language parsers, semantic analyzers, translators, transliterators and interpreters; rapid prototyping of new and domain- directed features and dialects in existing languages; software code analysis and design recovery; software restructuring and remodulariza- tion; metaprogramming and retroactive reuse; source-level optimiza- tion and parallelization; inter-paradigm program transformation; logi- cal formula simplification and interpretation; program analysis, instrumentation and measurement; program normalization and structural comparison. The `txl' command provides a convenient interface for executing TXL programs to transform input files. The first command argument, `input- file', specifies the input file to be transformed by the TXL program, and the second argument, `txlfile', is the TXL program itself. The txlfile must be named ending in `.Txl' (e.g., Transform.Txl ) and is normally either in the present working directory, the Txl subdirectory of the present working directory, or the TXL system library (e.g., /usr/local/lib/txl or C:/windows/txl ). If the txlfile is omitted, then it is inferred from the file name suffix of the given inputfile. For example, if the given input file to be transformed is `myinput.pas' then the the TXL program file is inferred to be `pas.Txl'. Unless the -c option is used, in which case execution is suppressed, the txl command compiles, loads and executes the the TXL program to transform the given input file. Transformed output (only) is sent to the standard output stream ( /dev/stdout or CONOUT$ ) and may be saved in an output file using either the -o option of shell redirection (e.g., txlinputfiletxlfile>outputfile ). TXL messages are sent to the terminal independently via the standard error stream ( /dev/stderr or CONERR$ ) and can be redirected separately (e.g., txlinputfiletxl- file>outputfile2>errorfile ). OPTIONS The following options are recognized by the txl command. -q[uiet] Quiet operation - turn off all information messages. TXL normally prints a version identification and short progress messages indicating the stage of processing on the standard error stream as it runs. The -quiet option suppresses all such messages, and allows TXL to print error messages only. -v[erbose] Verbose operation - give greater detail in information mes- sages. Causes TXL to print detailed progress messages giving information on space and files used by each stage of process- ing. Also enables a number of common warning messages that are suppressed by default. -c[ompile] Compile TXL program to TXL virtual machine byte code only (do not execute). The compiled TXL virtual machine byte code for the TXL program prog.Txl is output to the file prog.CTxl The TXL byte code file can be loaded and executed directly by subsequent txl commands using the -l option, thus avoiding the overhead of recompiling the program on every run. TXL byte code files can be converted to C and compiled to stand- alone TXL applications by the txlc command (see "man txlc"). -l[oad] Load and transform input using a previously compiled TXL pro- gram. The compiled TXL virtual machine byte code for the TXL program prog.Txl is loaded directly from the file prog.CTxl , which must be a TXL byte code file created by a previous txl- c command. The name of the TXL byte code file can either be inferred from the suffix of the first argument file or be explicitly given as the second argument. In either case the suffix of the TXL program file is ignored and .CTxl is used instead. TXL byte code files can be converted to C and com- piled to standalone TXL applications by the txlc command (see "man txlc"). -define SYMBOL Define the TXL preprocessor symbol SYMBOL. Sets the pre- processor symbol SYMBOL to defined, so that #ifdefSYMBOL pre- processor directives will succeed in the compile of the TXL program. -comment Treat comments in the input file as input items. Normally TXL discards any comments in the input before parsing. When this option is used, comments are treated as input items to be parsed like any other. Care must be take to insure that the input language grammar explicitly allows comments in all the expected places, otherwise syntax errors will be flagged. -char Treat all input characters (including newlines and spaces) as significant. Normally TXL treats newlines, spaces and tabs ("white space") in input as separators only. When this option is specified, all characters in the input are treated as significant and categorized as tokens to be parsed accord- ing to the grammar. This option enables the predefined token classes [space] (any sequence of spaces and tabs) and [new- line] (a newline character). The grammar must be crafted to accept newlines and spaces wherever they may occur in the input. This option automatically suppresses all output spac- ing. -newline Treat newline characters only (not tabs and spaces) as sig- nificant. Normally TXL treats newlines, spaces and tabs ("white space") in input as separators only. When this option is specified, newline characters (i.e. line bound- aries) in the input are treated as significant and catego- rized as tokens to be parsed according to the grammar. This option enables the predefined token class [newline] (a new- line character,that is, ASCII LF (Unix/Linux) or CR/LF (Win- dows) ). The grammar must be crafted to accept newlines and spaces wherever they may occur in the input. -multiline Allow tokens to cross line boundaries (default). TXL allows tokens such as [stringlit] and [charlit] to cross line bound- aries in order to handle multi-line strings, as for example in C. Newlines inside a mutli-line token are preserved in the token text. For some languages and grammars it may be necessary to limit tokens to a single line by disabling this option using -nomultiline as a #pragma in the grammar. -token Treat newlines and spaces as separators only. Disables char- acter level input, and treats all newlines, spaces and tabs as separators only. This is the default input mode. -txl Treat the input being transformed as TXL source. This option makes it possible to transform TXL programs themselves using TXL. Sets the lexical conventions of the input to TXL's own defaults. In particular, disables unquoted character liter- als and enables treatment of single quotes as separate input tokens. -attr Print attributes in the transformed output. Normally attributes (items of type [attr X] for some X) are not printed in the output of a TXL program. -raw Output transformed source in raw (unspaced) format. Normally TXL uses a set of built-in spacing rules appropriate to most high-level programming languages for formatting output. This option turns off all spacing and line wrapping in output except where the output would otherwise be ambiguous (e.g. between two adjacent identifiers), and as explicitly speci- fied in the grammar using [SP] and [NL]. When used in con- junction with [SP], [NL] and [IN]/[EX], this option gives the user complete control over output formatting. -id[chars] 'CCC' Treat the characters 'CCC' as valid following characters in [id] tokens. Adds the given characters as valid following (second and subsequent) characters in the [id] predefined token class. More general control over [id] can be achieved using the tokens statement in the TXL program. -sp[chars] 'CCC' Treat the characters 'CCC' as white space. Adds the given characters to the set of characters treated as equivalent to the space character and treated as separators. If -char is specified, these characters will be added to those matched by the [space] predefined token class. -esc[char] 'C' Use 'C' as the escape character in string and character lit- erals. Sets the string and character literal escape charac- ter to 'C'. By default the escape character is '' (e.g., "Here: If either "'" or '"' is specified, then '"' is used for string literals (e.g., "Here: "" is an embedded quote") and "'" is used for character literals (e.g., 'Here: '' is an embedded quote'). -upper Translate all unquoted input to upper case. Translates all input tokens except [stringlit] and [charlit] to upper case on input. -lower Translate all unquoted input to lower case. Translates all input tokens except [stringlit] and [charlit] to lower case on input. -case Ignore case in input. By default TXL is case-sensitive, that is, abc,ABC and aBc are all treated as different. This option specifies that the input language is case-insensitive, that is, abc,ABC,aBc and Abc are all to be treated as the same. Original case of input tokens is preserved in output unless explicitly changed by the TXL program (for example, using the [toupper] or [tolower] built-in functions). -w[idth] NNN Set the maximum output line width to NNN characters. By default TXL formats output in at most 128 characters per line. NNN must be a positive integer between 20 and 32767. This option has no effect when -raw is used. -in[dent] NN Set the output indentation increment to NN characters. Sets the number of character positions indented by [IN] and exdented by [EX] directives to NN characters. The default is 4 characters. -tabnl Output [TAB_NN] directives may force a newline. Allows [TAB_NN] directives to force a new line in the output if nec- essary to align the next output token at output column NN. This is the default. -xml Output as an XML parse tree. Outputs the result of the transformation as an XML parse tree (only). Useful in con- verting source text to XML syntax trees, and when debugging transformations. See also the -Dparse and -Dresult debugging options. -i[nclude] DIR Add DIR to the TXL include file search path. Adds DIR to the set of directories searched for TXL include files that are not present in the present working directory or its Txl sub- directory. The directories are searched in the order that their -I directives are given on the command line. If an include file is not found in any of these directories, then TXL system library directory (e.g., /usr/local/lib/txl) is searched last. -s[ize] MM Set the TXL transform size to MM megabytes. Sets the virtual memory allocated to TXL interpreter and transformer data structures to the indicated size. MM must be a positive integer between 2 and 999. In order to maximize transform efficiency, TXL liberally exploits the operating system's native virtual memory by artificially pre-allocating a fixed amount of static storage rather than attempting to manage storage dynamically. This strategy places static limits on the size of the input that can be processed as well as on the complexity and depth of the transformation that can be per- formed. This option explicitly sets the amount of static storage available and thus can be used to increase these lim- its. This option is normally used only when the system default limits have been exceeded. See also the -usage option. -u[sage] Report TXL resource usage statistics at the end of the run. Prints a table of the static limits on the various TXL inter- nal data structures and the amount of each actually used by the TXL run. This option can be used to choose an appropri- ate transform size for typical input data (see the -size option above). -o FILE Write standard output to file FILE. Normally TXL writes the output of the run to the standard output. This option redi- rects output to the specified file instead. -noOPTION Turn command line option OPTION off. Explicitly turns off any command line option (e.g., -noraw). - USERARGS Pass remaining command arguments to the TXL program. Passes all following command line arguments to the TXL program in the predefined global variable TXLargs. For example, the command line : txl eg.in in.Txl -s 100 - -myopt foo -otheropt will initialize TXLargs to the [repeat stringlit] value "-myopt" "foo" "-otheropt". DEBUGGING OPTIONS The following debugging options are recognized by txl. All output pro- duced by these options is sent to the terminal via the standard error stream. -analyze Invoke the TXL grammar and rule set analyzer. Causes the TXL compiler to perform an additional set of checks on the gram- mar and rule set, including a check for ambiguities and potential efficiency issues in the grammar. This option may significantly slow down the compile. -Dscan Print the input tokens to the standard error stream in XML format. Prints the input tokens recognized by the TXL scan- ner on the terminal via the standard error stream. Useful when debugging token definitions and unexpected syntax errors in the input. -Dparse Print the input parse tree to the standard error stream in XML format. Print the input parse tree on the terminal via the standard error stream. Useful when debugging grammars, or in understanding why a pattern has not matched the input. -Dresult Print the output parse tree to the standard error stream in XML format. Print the output parse tree on the terminal via the standard error stream. Useful when debugging grammars, or in understanding why output is not formatted as expected. -Dgrammar Print the program grammar to the standard error stream as a parse tree schema in XML format. TXL compiles input language grammars to a compact generic tree format used as both a pat- tern and a generator for parse trees of input. This option prints the compiled grammar tree for use in debugging subtle problems with a grammar. -Dpattern Print all pattern and replacement parse tree schemas to the standard error stream in XML format. The parse tree of every pattern and replacement in the TXL program's rule set is printed on the terminal via the standard error stream. This option is useful in debugging patterns of rules that fail to match input as expected. -Drules Print out the names of rules to the standard error stream as they are applied. A convenient trace of the order in which the rules and functions of the TXL program are actually invoked. -Dapply Print out the actual transformations made by rule applica- tions on the terminal as they happen. Useful for following the progress of a transformation. Transformations are output in the form A => B, where A and B are the text output form of the original and result scope of the transforming rule respectively. FILES inputfile the input to be transformed txlfile the TXL program to transform it /usr/local/lib/txl system TXL program library BUGS Bugs should be reported using the support page on the TXL website, http://www.txl.ca . SEE ALSO txldb(1), ``The TXL Programming Language, version 10.5'', ``User's Guide to the TXL Compiler/Interpreter, version 10.5''. AUTHORS Version 10.5 of TXL was designed and implemented by J.R. Cordy at Queen's University, Legasys Corp. and TXL Software Research Inc. between 1994 and 2007. TXL was originally designed by J.R. Cordy and C.D. Halpern-Hamu at the University of Toronto in 1985, and was originally implemented by J.R. Cordy, E.M. Promislow and I.H. Carmichael at Queen's University between 1986 and 1988. Version 7 was completely redesigned and implemented by J.R. Cordy and A. Malton at Queen's University in 1992. COPYRIGHT Copyright 2007 Queen's University at Kingston and James R. Cordy. 10 December 2007 TXL(1)