'''Tcl Assembly Language'''. Assembles into stack-based CISC [bytecode] as used by Tcl's bytecode compiler.

See [MS's bytecode engine ideas] and [The anatomy of a bytecoded command] for more explanations.

As usual, Tcl's [introspection] helps in learning about TAL:
======
% tcl::unsupported::assemble help
======
bad instruction "help": must be push, add, append, appendArray, appendArrayStk, appendStk, arrayExistsImm, arrayExistsStk, arrayMakeImm, arrayMakeStk, beginCatch, bitand, bitnot, bitor, bitxor, concat, coroName, currentNamespace, dictAppend, dictExists, dictExpand, dictGet, dictIncrImm, dictLappend, dictRecombineStk, dictRecombineImm, dictSet, dictUnset, div, dup, endCatch, eq, eval, evalStk, exist, existArray, existArrayStk, existStk, expon, expr, exprStk, ge, gt, incr, incrArray, incrArrayImm, incrArrayStk, incrArrayStkImm, incrImm, incrStk, incrStkImm, infoLevelArgs, infoLevelNumber, invokeStk, jump, jump4, jumpFalse, jumpFalse4, jumpTable, jumpTrue, jumpTrue4, label, land, lappend, lappendArray, lappendArrayStk, lappendStk, le, lindexMulti, list, listConcat, listIn, listIndex, listIndexImm, listLength, listNotIn, load, loadArray, loadArrayStk, loadStk, lor, lsetFlat, lsetList, lshift, lt, mod, mult, neq, nop, not, nsupvar, over, pop, pushReturnCode, pushReturnOpts, pushResult, regexp, resolveCmd, reverse, rshift, store, storeArray, storeArrayStk, storeStk, strcmp, streq, strfind, strindex, strlen, strmap, strmatch, strneq, strrange, strrfind, sub, tclooClass, tclooIsObject, tclooNamespace, tclooSelf, tryCvtToNumeric, uminus, unset, unsetArray, unsetArrayStk, unsetStk, uplus, upvar, variable, verifyDict, or yield

Lots of help for the enquiring mind... ;^)

For experimenting, here are some little helpers:
======
interp alias {} asm {} ::tcl::unsupported::assemble
interp alias {} disasm {} ::tcl::unsupported::disassemble

#-- Code a proc in Tcl, see how its bytecode disassembles:
proc aproc {name argl body} {
    proc $name $argl $body
    disasm proc $name
}
======
Execution happens immediately:
======
% set x hello
hello
% asm "push $x;strlen"
5
======
The classic ''sign'' (of a number) example in TAL, corresponding to ''expr {$x>0 - $x<0}'':
======
% proc sign x {asm {load x; push 0; gt; load x; push 0; lt; sub}}
% sign 42
1
% sign -42
-1
% sign 0
0
======
This illustrates how braced vs. non-braced [expr]essions are byte-compiled differently:
======
% aproc f x {expr {$x+1}}
ByteCode 0x0x93492f0, refCt 1, epoch 15, interp 0x0x92c07a0 (epoch 15)
  Source "expr {$x+1}"
  Cmds 1, src 11, inst 6, litObjs 1, aux 0, stkDepth 2, code/src 0.00
  Proc 0x0x935b298, refCt 1, args 1, compiled locals 1
      slot 0, scalar, arg, "x"
  Commands 1:
      1: pc 0-4, src 0-10
  Command 1: "expr {$x+1}"
    (0) loadScalar1 %v0         # var "x"
    (2) push1 0         # "1"
    (4) add 
    (5) done 

% aproc f x {expr $x+1}
ByteCode 0x0x93492f0, refCt 1, epoch 15, interp 0x0x92c07a0 (epoch 15)
  Source "expr $x+1"
  Cmds 1, src 9, inst 8, litObjs 1, aux 0, stkDepth 2, code/src 0.00
  Proc 0x0x937b8f0, refCt 1, args 1, compiled locals 1
      slot 0, scalar, arg, "x"
  Commands 1:
      1: pc 0-6, src 0-8
  Command 1: "expr $x+1"
    (0) loadScalar1 %v0         # var "x"
    (2) push1 0         # "+1"
    (4) concat1 2 
    (6) exprStk 
    (7) done 

====== 

** Examples **

[Fib in TAL], by [kbk], 2012-08-21

** Discussion **
----
[CMcC]: I've put some incomplete work on tcl script generation of bytecodes here: http://wiki.tcl.tk/_repo/bytecode/

It dates from Apr03, and may not even compile - it's certainly incomplete.

----
[Zarutian] 28. oktober 2006: hmm... specifying the grammar of TAL shouldn't be hard.

Backus Naur Forms:
  <statement> ::= [<label>] <instruction> "\n"
  <label>   ::= <alpanumeric string> ":"
  <instruction> ::= <mnemonic name> [<parameter>]*

[AMG]: This is not the final BNF of TAL, if the example on the [assemble] page is any indicator.  It seems the grammar is even simpler than you envision, since `label` is itself a mnemonic.  Another difference is the existence of comments, which seem to go from # to end of line, and semicolons as statement separators.  I'm guessing semicolons and newlines are interchangeable, and semicolons are only strictly needed when multiple statements appear on a line or when a comment appears on the same line as a statement.  I'd like to see a formal definition...

[Zarutian] 28. oktober 2006: Type of instructions needed:
   * Arithmetic and logic operations
   * Input/Output
   * Memory fetching and storage
   * Branching

But the question is: what architecture does TAL target? Tcl bytecodes?

[AK] (Jan 10 2007): AFAIK it would target Tcl bytecodes. As for the grammar, I would say it should be a list representation in general, and anything more formatted can be derived from that, i.e., for display, maybe editing, etc.

[DKF] (same day): It should be noted that currently it is obscenely difficult to manage branching properly, especially when they are forward jumps. It should also be noted that there are some instructions that it is probably difficult to issue outside the main BCC anyway, as they use complex blocks of metadata (especially those relating to foreach loops and switch jump-tables).

<<categories>> Glossary