languages/tcl/docs/overview.pod

   1 =head1 OVERVIEW
   2
   3 This is a from-scratch implementation, based primarily on the Tcl man page(s),
   4 and the cvs-current test suite for Tcl.
   5
   6 Another interesting project would have been to modify the Tcl source and have
   7 it generate Parrot directly. Many people smarter than I am have declared this
   8 I<hard>, so I'm rather happy I'm working on it this way.  (Apparently Tcl's
   9 bytecode engine is very optimized for Tcl (big surprise).  So, converting the
  10 Tcl-specific bytecodes there to Parrot would be a big deal.)
  11
  12 =head1 RUNNING TCL
  13
  14 =head2 Generated Files
  15
  16 When you make Tcl, you're generating several files:
  17
  18 =over 4
  19
  20 =item tclsh
  21
  22 While not included in the C<make all> target, you can C<make tclsh> (or
  23 whatever the executable would be called on your platform), and this will give
  24 you a faux-executable; a C binary that loads in all the Parrot bytecode for
  25 partcl. You can then use this in most places where you see C<parrot tcl.pbc>
  26
  27 =item runtime/tcllib.pbc
  28
  29 This file is used to load all the various commands, ops, etc. into
  30 the appropriate namespaces, as well as declare and register the TCL
  31 compiler for the C<compile> opcode.
  32
  33 This file is then included by F<tcllib.pir> which is compiled to F<tcllib.pbc>.
  34
  35 =item tcl.pbc
  36
  37 This is roughly equivalent to C<tclsh> - It takes the command line arguments
  38 (currently, the name of the file you wish to parse), and reads in the file,
  39 and uses the Tcl library to parse those contents as Tcl. You can also specify
  40 command line options to be used with this bytecode file.
  41
  42 =item src/grammar/expr/pge2past.pir
  43
  44 =item src/grammar/expr/past2pir.pir
  45
  46 =item src/grammar/expr/expression.pir
  47
  48 This C<PIR> files are generated from their corresponding C<.tg> and C<.pg>
  49 files. These grammar files allow us to use PGE's implementation of perl6
  50 rules to more simply specify our parsing rules. We use these rules to handle
  51 both the general parsing for Tcl itself, as well as the sub-"language"
  52 used by expressions in [expr] and elsewhere.
  53
  54 =back
  55
  56 =head2 PMCS
  57
  58 The Tcl PMCs (Parrot Magic Cookies) are the user visible data types. These
  59 live in the C<*.pmc> files in F<src/pmc/>. They are compiled into a
  60 dynamically loadable library which is loaded with the C<.HLL> directive
  61 (HLL stands for High Level Language). Most of the functionality associated
  62 with these PMCS is derived from the base Parrot classes, except as noted below.
  63
  64 =over 4
  65
  66 =item TclString
  67
  68 Scalar string, with an override for the boolean truth values.
  69
  70 =item TclInt
  71
  72 Scalar integer, with an override for various math. (For example, Parrot
  73 Integers automatically promote to float division, while Tcl does not.)
  74
  75 =item TclFloat
  76
  77 Scalar float, with an override of the stringification: Tcl floats are
  78 somewhat unusual compared to other Parrot HLLs in that integer-valued floats
  79 stringify with a trailing C<.0>.
  80
  81 =item TclList
  82
  83 Ordered container, corresponding to values generated by the C<[list]> builtin.
  84 Overrides the default stringification provided by Parrot Arrays.
  85
  86 =item TclArray
  87
  88 Hash like container, corresponding to values created with the C<[array]>
  89 builtin.
  90
  91 =item TclDict
  92
  93 Hash like container, corresponding to values created with the C<[dict]>
  94 builtin. Unlike arrays, dictionaries can nest, having dictionaries as
  95 values; Also, dictionaries act more like TclLists in terms of their
  96 conversion to string and back.
  97
  98 =item TclObject
  99
 100 A virtual type, which is used to provide some shimmer (aka morph) methods
 101 common to all the scalar value types.
 102
 103 =back
 104
 105 =head1 TESTS
 106
 107 To run the test suite, C<make test>. If you want to also get output from the
 108 TODO tests, C<make devtest> instead. This is NOT the Tcl test suite.
 109 Occasional failures are suspected against svn-head; there should be no
 110 failures in a released version, however.
 111
 112 To run the Tcl test suite, type C<make spectest>. This will checkout the
 113 appropriate CVS copy of the tests from the Tcl repository and run them.
 114 Warning, this will be slow.
 115
 116 =head1 EXAMPLES
 117
 118 There are examples in the C<examples> directory that are vaguely more
 119 interesting. Change to that directory and type C<make> for directions.
 120
 121 =cut