summaryrefslogtreecommitdiffstats
path: root/taccle/README.md
diff options
context:
space:
mode:
authorWilliam Joye <wjoye@cfa.harvard.edu>2018-02-20 20:17:57 (GMT)
committerWilliam Joye <wjoye@cfa.harvard.edu>2018-02-20 20:17:57 (GMT)
commitf9ed678902dea0db45cd88c6da96da79310dfdfb (patch)
treee9a9785561e658f314c9e1b1ed112e6ca7688da7 /taccle/README.md
parenta0baa564b54177527964fae8f0cc0d64d7db8ac7 (diff)
parenta591c85cba3570d69a809b2099c3f108c7e26eb8 (diff)
downloadblt-f9ed678902dea0db45cd88c6da96da79310dfdfb.zip
blt-f9ed678902dea0db45cd88c6da96da79310dfdfb.tar.gz
blt-f9ed678902dea0db45cd88c6da96da79310dfdfb.tar.bz2
Merge commit 'a591c85cba3570d69a809b2099c3f108c7e26eb8' as 'taccle'
Diffstat (limited to 'taccle/README.md')
-rw-r--r--taccle/README.md121
1 files changed, 121 insertions, 0 deletions
diff --git a/taccle/README.md b/taccle/README.md
new file mode 100644
index 0000000..6a3b1ff
--- /dev/null
+++ b/taccle/README.md
@@ -0,0 +1,121 @@
+Copyright
+---------
+taccle itself is protected by the GNU General Public License. See the
+file COPYING for details. Of course, any code you generate using
+taccle is subject to whatever restrictions you place on it.
+
+
+Availability
+------------
+A wiki page for taccle may be found at http://mini.net/tcl/taccle.
+An archive of taccle files are available at http://tcl.jtang.org/taccle.
+
+
+taccle README
+-------------
+taccle is another compiler compiler for the Tcl language. It takes as
+input a "taccle specification file"; from this taccle generates a Tcl
+file that implements an LALR(1) parser. The program brings to the Tcl
+language what yacc and bison do for C and C++.
+
+This release of taccle implements nearly all features of yacc:
+ - %token and %start declarations
+ - epsilon transitions (i.e., "empty" rules)
+ - embedded (mid-rule) actions
+ - literal tokens
+ - symbol values and synthesized attributes
+ - the error token and error recovery
+ - shift/reduce and reduce/reduce conflict notification
+ - operator precedence with %left, %right, %nonassoc, and %prec
+ - functions yyerror, YYABORT, YYACCEPT, and yyclearin
+ - infinite recursion detection
+
+Features currently missing in taccle are:
+ - inherited attributes
+
+Because taccle uses the lset command it requires Tcl 8.4 or greater.
+
+Be aware of the following differences between taccle and yacc:
+
+1. taccle (and Tcl) has no concept of variable types. Thus %union and
+ %type declarations are no longer needed.
+
+2. yacc uses variables $1, $2, etc for symbol values; it uses $$ for
+ the synthesized attribute. Although both $1 and $$ are legal
+ variable references in Tcl the latter is more awkward; the
+ expression `set $ foo' is not legal. Instead of $$ use the name
+ '_', as in `set _ foo'. These variables' scopes are valid only
+ within the context of an action. See
+ examples/simple_calculator.tac for an example.
+
+ (The astute observer notes that using $_ for synthesized values is
+ similar to Perl's use of the auto-variable $_.)
+
+3. taccle has error handling just like bison. It always declares the
+ terminal `error' that is pushed onto the stack whenever it detects
+ a syntax error. Although yyclearin is implemented neither
+ YYRECOVERING nor yyerrok are. The example
+ interactive_calculator.tac implements error handling.
+
+4. Like yacc, taccle requires a token generator. The examples use
+ fickle (http://mini.net/tcl/fickle), though others are welcome.
+
+5. taccle calls a global function yylex to fetch the next token. This
+ yylex function is expected to return the next token in the input
+ stream, either a string or a number. Normally this poses no
+ problem except for the case of a literal zero. Tcl makes no
+ distinction between the integer zero and the string zero. Because
+ zero is reserved for the end of input marker, taccle will refuse
+ grammars that employ literal zeros. You can get around this by
+ declaring `%token ZERO' and using that instead.
+
+6. Another literal that causes all sorts of problems is the open brace
+ '{'. Because most things are represented internally as lists the
+ presence of the brace breaks everything. Thus taccle will refuse
+ to parse grammars with this literal; you'll have to use a %token
+ instead.
+
+
+Using the Examples
+------------------
+Execute taccle as if it were yacc:
+
+ $ tclsh ./taccle.tcl -d some_spec_file.tac
+
+This will generate two files, some_spec_file.tcl and
+some_spec_file.tab.tcl. The first contains the actual parser code;
+execute it by calling yyparse. The latter file is file to be sourced
+by the lexer, much akin to yacc's y.tab.h file.
+
+The Makefile in the examples subdirectory will generate two simple
+calculator programs. You will need a copy of fickle (available at
+http://mini.net/tcl/fickle) and may need to modify its location on
+line 4 of the Makefile. After filtering simple_calculator through
+ficcle and taccle execute it like so:
+
+ $ echo "6*9" | tclsh simple_calculator.tcl
+
+If all goes well the program displays:
+
+ Result is 54
+
+A more interesting example is interactive_calculator.tcl. This one is
+designed to handle any arbitrary number of commands. Upon errornous
+equations it recovers by discarding the rest of the buffer. Here is
+an example session of it:
+
+ $ tclsh interactive_calculator.tcl
+ 6*9
+ = 54
+ 1++2++3
+ = error
+ 1 + 2 + 3
+ = 6
+
+The final example, infix_calc.tcl, shows how to use operator
+precedence to resolve shift/reduce conflicts. It understands both
+left associative operators (addition et al) as well as right
+associative (exponentation). Here is an example use:
+
+ $ echo "2^2^2 - 10 * 2 + 6 / 3" | tclsh infix_calc.tcl
+ -2