Up:
  1. TkScript Reference Guide » User Interface
TkScript

reference guide | User Interface


 
Table of Contents:

 
1. User interface

This section describes how to invoke and configure the TkScript runtime.
 
TkScript is a console application so its "user interface" basically consists of commandline arguments.
 
Via MIME integration handlers, TkScript can be integrated with e.g. a web or file system browser.
 
1.1. Environment variables
Up:
  1. TkScript Reference Guide » User Interface » Environment variables

TkScript uses a couple of environment variables to locate plugins, modules, libraries and applications.
1.1.1. TKS_PLUGIN_PATH
If set, plugins (.so, .dll) are searched in the given directory (must include trailing directory separator!).
1.1.2. TKS_MODULE_PATH
Up:
  1. TkScript reference guide / Modules » Common module include directory
If set, script modules (.tks) are searched in the given directory (must include trailing directory separator!).
1.1.3. TKS_LIBRARY_PATH
If set, script libraries (.tsl) are searched in the given directory (must include trailing directory separator!).
1.1.4. TKS_APPLICATION_PATH
If set, script applications (.tks,.tkx) are searched in the given directory (must include trailing directory separator!).
1.2. Registry entries (Win32)
Up:
  1. TkScript Reference Guide » User Interface » Win32 registry entries
The following Win32 registry entries are used to locate plugins, modules, libraries and applications if the respective dir. has not been set via cmdline option or environment variable.
1.2.1. HKLM\\SOFTWARE\\TKS\\TKS_PLUGIN_PATH
HKEY_LOCAL_MACHINE\\Software\\TKS\\TKS_PLUGIN_PATH
See TKS_PLUGIN_PATH
1.2.2. HKLM\\SOFTWARE\\TKS\\TKS_MODULE_PATH
HKEY_LOCAL_MACHINE\\Software\\TKS\\TKS_MODULE_PATH
See TKS_MODULE_PATH
1.2.3. HKLM\\SOFTWARE\\TKS\\TKS_LIBRARY_PATH
HKEY_LOCAL_MACHINE\\Software\\TKS\\TKS_LIBRARY_PATH
See TKS_LIBRARY_PATH
1.2.4. HKLM\\SOFTWARE\\TKS\\TKS_APPLICATION_PATH
HKEY_LOCAL_MACHINE\\Software\\TKS\\TKS_APPLICATION_PATH
See TKS_APPLICATION_PATH
1.2.5. HKLM\\SOFTWARE\\Cygnus Solutions\\Cygwin\\mounts v2\\/usr/lib
HKEY_LOCAL_MACHINE\\Software\\Cygnus Solutions\\Cygwin\\mounts v2\\/usr/lib
If TkScript has been compiled with HAVE_CYGWIN, this registry value is used to replace /usr/lib with the actual windows path in filenames. This is mainly useful to set up the plugin/module/library/application directories like on e.g. Linux, i.e. /usr/lib/tks/plugins, /usr/lib/tks/applications, and so on.
1.3. MIME integration
Up:
  1. TkScript Reference Guide » User Interface » MIME integration
  2. Downloads » Executables » Windows 2000/XP 32bit » Milestone releases » setup.exe
  3. Downloads » Executables » Windows 2000/XP 32bit » Current development snapshot » tks-preview.exe
  4. TkScript reference guide / User Interface » User interface

The following MIME types can be used to integrate TkScript with web/file browsers so that an application is automatically launched when a user clicks on a .tkx, .tkp resp. .tks file/URL.
 
1.3.1. application/x-tks
This MIME type is used for .tks single-file scripts.
1.3.2. application/x-tkp
This MIME type is used for .tkp script projects.
1.3.3. application/x-tkx
Up:
  1. TkScript reference guide / Modules » Common module include directory
This MIME type is used for .tkx script "executables" (packaged script projects).
1.3.4. application/x-tsl
Up:
  1. TkScript reference guide / Modules » Common module include directory
This MIME type is used for .tsl script "libraries" (packaged script projects).
1.3.5. Example .htaccess configuration
This is the .htaccess file I use on my website (which is hosted with the Apache HTTPD): 
AddType application/x-tkx tkx 
AddType application/x-tks tks
1.3.6. Security considerations
TkScript has not been designed as a front-end language in sensitive environments like e.g. web browsers. Keep in mind that improper use may result in crashes / segmentation faults.
 
If used correctly, TKS may work fine as a back-end language in web servers (but better not feed it any user-written scripts via dynamic compilation) or as a support language for GUI applications or games.
 
1.3.6.1. Paranoia
If you install a MIME integration type handler for TKS for use in web/file browsers, you should, if possible, run the script engine with minimal user privileges (e.g. guest) and/or maybe even in a chroot environment.
1.4. Command line interface
Up:
  1. TkScript Reference Guide » User Interface » Command line interface
  2. TkScript reference guide / Functions » Recursion » Limits
1.4.1. Overview
$ tks -h 
TKS - an extensible c++ glue script language 0.9.10.40. (C) 2001-2008 Bastian Spiegel. 
 
          -- visit http://tkscript.de for further information. 
 
 USAGE: 
        tks source [args] 
        tks source.tks [args] 
        tks source.tkx [args] 
        tks source.tkp [args] 
        tks -c    --compile proj 
        tks -c    --compile proj.tkp [outfile.tkx] 
        tks -cl   --compile library 
        tks -cl   --compile library.tkp [outfile.tsl] 
        tks -d    --debuglevel nr 
        tks -da   --disassemble 
        tks -fi   --forceint 
        tks -njo  --nojitopt 
        tks -nbc  --noboundarycheck 
        tks -nra  --noarrayautoresize 
        tks -ps   --packedscripts 
        tks -nur  --nounresolveds 
        tks -num  --nounresolvedmembers 
        tks -nuf  --nounresolvedfunctions 
        tks -ncs  --noconstraints 
        tks -nln  --nolinenumbers 
        tks -ndo  --nodeleteobjects 
        tks -ecs  --enableconstraints 
        tks -fss  --functionstacksize <size> 
        tks -fcs  --functioncallstacksize <size> 
        tks -esp  --enablestatementprofiling 
        tks -ee   --emitexplanations 
        tks -h    --help 
        tks -l    --list proj.tkx 
        tks -lp   --librarypath </path/to/dir/>|<drive:\path\to\dir\> 
        tks -ch   --chapter <name> 
        tks -mp   --modulepath </path/to/dir/>|<drive:\path\to\dir\> 
        tks -nlf  --nolocalfiles 
        tks -np   --noplugins 
        tks -pp   --pluginpath </path/to/dir/>|<drive:\path\to\dir\> 
        tks -ap   --applicationpath </path/to/dir/>|<drive:\path\to\dir\> 
        tks -ef   --extrafile <sourcefile> 
        tks -pls  --poolstrings <num> 
        tks -pl   --poollimit <prio> <kbytes> 
        tks -pla  --poollimitall <kbytes> 
        tks -pfr  --poolfreeratio <prio> <ratio> 
        tks -pfra --poolfreeratioall <ratio> 
        tks -q    --quiet 
        tks -v    --version
1.4.2. Scripts
Any argument that is not processed by the main TkScript command line parser is available to scripts via the global Arguments variable.
 
Example: 

String arg; 
int argi = 0; 
foreach arg in Arguments { 
   trace "arg["+argi+"]=" + #(Arguments[argi]); 
   argi++; 
}

 
If invoked using 

$ tks test.tks 1 2 3

 
it yields the following output (or similar): 
arg[0]=<String#0x01BF05F4("1")> 
arg[1]=<String#0x01BF0618("2")> 
arg[2]=<String#0x01BF063C("3")>
1.4.3. Commandline options by category
1.4.3.1. Show runtime version
The option -v, --version is used to print the TkScript version number, then exit. 
$ tks -v 
0.9.10.40
1.4.3.2. Running script applications
If tkscript is invoked with no arguments, it tries to load the default application data.tkx and execute it.
 
If tkscript is invoked with only a filename or URL (win32 only ATM), it tries to load the given file and execute it.
Examples: 
$ tks sieve.tks 
Eratosthenes Sieve prime number calculation 
10000 iterations<br> 
1899 primes
1.4.3.2.1. File extensions
The file type is determined by the file extension. .tks is used for single file script applications, .tkp is used for script project files (i.e. multi file script applications), .tkx is used for packaged script applications ("executables"), .tsl is used for packaged script libraries.
 
If the file name contains no file extension, TkScript first tries the .tkp, then the .tkx and finally the .tks extension.
1.4.3.2.2. Default application path
If the script filename starts with app:, the application package will be searched in the TKS_APPLICATION_PATH. Example: 
$ tks app:dog++ 
Usage: 
    tks app:dog++ [-pn,--projectname <projectname>] <inputfiles> | tks app:dog 
 
 
[---] dog++: invalid arguments. 
 
[---] caught critical exception "Death", message="" 
[---] in module "Main" line 27. 
[---] Runtime callstack: 
[---]      1.: "Main":34: <throw> 
[---]      2.: "Main":278: ::PrintUsage() (in "Main":27)
1.4.3.2.3. Overriding/setting default library, application, module and plugin directories

These options override any environment variables or registry entries.
1.4.3.2.3.1. Setting the plugin path
The -pp, --pluginpath option is used to set the current TKS_PLUGIN_PATH.
1.4.3.2.3.2. Setting the module path
The -mp, --modulepath option is used to set the current TKS_MODULE_PATH.
1.4.3.2.3.3. Setting the library path
The -lp, --librarypath option is used to set the current TKS_LIBRARY_PATH.
1.4.3.2.3.4. Setting the application path
The -ap, --applicationpath option is used to set the current TKS_APPLICATION_PATH.
1.4.3.2.4. Adding extra files to a pre-packaged application
The -ef, --extrafile option is used to add a file to a .tkx application during startup. This mechanism was originally added to allow document-specific DSA script extensions, see The DOG manual.
1.4.3.2.5. Function stack sizes and recursion depth
The -fss, --functionstacksize option is used to set the number of values available for function stackframes. The -fcs, --functioncallstacksize option is used to set the maximum function call stack depth.
1.4.3.2.6. Quiet program execution
The -q, --quiet option is used to disable all output to stdout.
1.4.3.3. Compiling/packaging applications and libraries
1.4.3.3.1. Packaging an application
The -c option is used to create a .tkx application package from a project file.
 
Example: 
$ tks -c sieve

This would create a file sieve.tkx from the project file sieve.tkp.
1.4.3.3.2. Packaging a library
The -cl option is used to create a .tsl library package from a project file.
 
Example: 
$ tks -cl ui

This would create a file ui.tsl from the project file ui.tkp.
1.4.3.3.3. Enable tokenization
The option -ps, --packedscripts is used to enable tokenization so that .tkx and .tsl
files will not include the entire source code of a script but only a stripped-down, tokenized form (e.g. without comments).
1.4.3.3.4. Removing line number information from packaged files
The option -nln is used to strip off line number information from .tkx and .tsl files.
1.4.3.3.5. Listing the contents of a package
The -l, --list option is used to list the contents of a .tkx or .tsl file. Example: 
$ tks -l sieve.tkx 
[...] VFS Directory of "sieve.tkx". 
[...] tak size=600. 
[...] pak TOC: 
 
[...] 01: chapter name="main" #files=1 origsize=1577 comprsize=569 ratio=36.08. 
[...] 01: chapter TOC: 
[...] 01:01: logic="code/main.tks" local="sieve.tks" off=38 size=1539 type=0.
1.4.3.4. Memory pooling related options
A couple of command line options can be used to tweak the memory pools used for runtime object allocation. TkScript memory pools use 3 different priority levels: 
#define YAC_POOL_PRIORITY_LOW    0 
#define YAC_POOL_PRIORITY_MEDIUM 1 
#define YAC_POOL_PRIORITY_HIGH   2

 
While the main pools are indexed via object-byte-size, there also are different sub-pools for each priority level.
1.4.3.4.1. Setting the pool size(s)
The -pl, --poollimit option is used to configure the pool size (in KBytes) for the given priority level.
The -pla, --poollimitall option is used to configure the pool size (in KBytes) for all priority levels.
The default pool size is 2 MBytes. The maximum pool size is 32 MBytes.
1.4.3.4.2. Setting the "free" threshold/ratio
The -pfr, --poolfreeratio option is used to set the threshold level (0..1) for the given priority level.
If the total element size / total avail size ratio for a priority level exceeds this threshold, pool fragments will be freed when the last element in a fragment is freed.
The -pfra, --poolfreeratioall option set the same threshold ratio for all priority levels.
1.4.3.5. JIT related options
1.4.3.5.1. Force interpreted mode
The option -fi, --forceint is used to force interpreted mode.
1.4.3.5.2. Disable JIT optimizations (debug)
The option -njo, --nojitopt is used to disable some JIT optimizations (mainly for debugging).
1.4.3.5.3. Disable array boundary checks
The option -nbc, --noboundarycheck is used to exclude array boundary checks (speed hack).
1.4.3.5.4. Disassemble JIT code
The option -da, --disassemble is used to print a disassembly of the generated JIT code before executing it (mainly for debugging).
1.4.3.6. Debugging
Up:
  1. TkScript reference guide / Objects » Object references (pointers) » InvalidPointer
  2. TkScript reference guide / Objects » Memory managment » Caveats
1.4.3.6.1. The debug level
The -d, --debuglevel option is used to set the debug level in the range 0..100. Debug levels over 20 tend to produce a lot of debug output. Debug levels over 90 can be used to trace function calls. The debug level can also be read by plugins using the →yac plugin interface.
1.4.3.6.2. Dead object detection
TkScript does not use garbage collection and allows applications to keep references to objects that may already be deleted.
 
Nevermind, in order to help debugging the more twisted situation where an object was deleted and a new object is already allocated at the same memory address, there is the possibility to never actually delete any objects!
 
Objects will simply be marked dead (and their destructors will be called). This will allow the TkScript runtime to detect the dead object on-access.
 
Use the -ndo, --nodeleteobjects option if you want to try this. The memory leaked by runtime will be cleant up by the operating system.
1.4.3.7. Runtime feature restrictions
The following options are used to disable language features or restrict file access.
1.4.3.7.1. Disabling plugins
The -np, --noplugins option is used to forbid the use of additional native code plugins libraries.
1.4.3.7.2. Unresolved variables and functions / lazy linking
These options are mainly useful for internal testing/debugging.
The -nur, --nounresolveds option forbids "unresolved nodes".
The -num, --nounresolvedmembers option forbids "unresolved member nodes".
The -nuf, --nounresolvedfunctions option forbids "unresolved function nodes".
1.4.3.7.3. Disabling local file access
The -nlf, --nolocalfiles option is used to make all attempts to open local files fail. This also works with plugins if they use the Stream resp. File class to access files.
1.4.3.7.4. Disabling script constraints
The -ncs, --noconstraints option is used to turn off checking of script constraints (in method/function calls).
1.4.3.7.5. Automatic array resizing
The -nra, --noarrayautoresize option is used to disable automatic on-access array resizing.
1.4.3.8. Statement profiling
The -esp, --enablestatementprofiling option is used to output profiling statistics when the script exits. Note: This does not work with JIT compiled code!
1.4.3.8.1. Example
$ tks -esp -fi sieve.tks 
Eratosthenes Sieve prime number calculation 
10000 iterations<br> 
1899 primes 
added 15 profile lines 
------------------------------------ 
Profile result (call_count) (Top 10.000): 
  Num statement lines covered: 15/71 
  <linenr>   <module_name> <line_nr> <total_ms> <avg_ms> <call_count> <ratio1st> <ratioParent> 
  00001.: Main:17 -1843.44246919 0.000698763 1638300 (1/1) (1/1) *** for ( i = 0 ; i <= size ; i ++ ) flags [ i ] = true ; 
  00002.: Main:27 1070.37073854 0.000709596 1499900 (1/1.09227281819) (1/1.09227281819) *** k += prime ; 
  00003.: Main:26 85.5757512327 0.000708569 1499900 (1/1.09227281819) (1/1) ***flags [ k ] = false ; 
  00004.: Main:18 -451.222137548 0.000646717 819200 (1/1.99987792969) (1/1.83093261719) *** for ( i = 0 ; i <= size ; i ++ ) 
  00005.: Main:29 129.941014748 0.000677589 189900 (1/8.62717219589) (1/4.31384939442) *** count ++ ; 
  00006.: Main:23 -863.534195727 0.000698406 189900 (1/8.62717219589) (1/1) ***k = i + prime ; 
  00007.: Main:22 -859.132936166 0.000713092 189900 (1/8.62717219589) (1/1) ***prime = i + i + 3 ; 
  00008.: Main:14 0.0693524780218 0.00069395 101 (1/16220.7920792) (1/1880.1980198) *** for ( iter = 1 ; iter <= NUM_BENCHMARK_ITERATIONS ; iter ++ ) 
  00009.: Main:16 0.0724954879843 0.000704962 100 (1/16383) (1/1.01) *** count = 0 ; 
  00010.: Main:34 0.850527081639 0.850527 1 (1/1638300) (1/100) *** trace count+  primes ; 
  00011.: Main:12 0.802755646873 0.802756 1 (1/1638300) (1/1) *** trace 10000 iterations<br> ; 
  00012.: Main:10 0.974704889813 0.974705 1 (1/1638300) (1/1) *** trace Eratosthenes Sieve prime number calculation ; 
  00013.: Main:8 0.000628584530205 0.000628585 1 (1/1638300) (1/1) *** int size= 8190 ; 
  00014.: Main:5 0.000907952198759 0.000907952 1 (1/1638300) (1/1) *** int NUM_BENCHMARK_ITERATIONS = ( 100 ) ; 
  00015.: Main:3 0.00139683834277 0.00139684 1 (1/1638300) (1/1) *** int flags [ 8191 ] ; flags . numElements = 8191 ; 
------------------------------------ 
------------------------------------ 
Profile result (millisec_sum) (Top 10.000): 
  Num statement lines covered: 15/71 
  <linenr>   <module_name> <line_nr> <total_ms> <avg_ms> <call_count> <ratio1st> <ratioParent> 
  00001.: Main:27 1070.37073854 0.000709596 1499900 (1/1) (1/1) *** k += prime ; 
  00002.: Main:29 129.941014748 0.000677589 189900 (1/8.23735862475) (1/8.23735862475) *** count ++ ; 
  00003.: Main:26 85.5757512327 0.000708569 1499900 (1/12.5078742882) (1/1.51843265032) *** flags [ k ] = false ; 
  00004.: Main:10 0.974704889813 0.974705 1 (1/1098.14852652) (1/87.7965752784)*** trace Eratosthenes Sieve prime number calculation ; 
  00005.: Main:34 0.850527081639 0.850527 1 (1/1258.47931435) (1/1.14600100438)*** trace count +  primes ; 
  00006.: Main:12 0.802755646873 0.802756 1 (1/1333.37055019) (1/1.05950931015)*** trace 10000 iterations<br> ; 
  00007.: Main:16 0.0724954879843 0.000704962 100 (1/14764.6531984) (1/11.0731808171) *** count = 0 ; 
  00008.: Main:14 0.0693524780218 0.00069395 101 (1/15433.7778414) (1/1.04531936064) *** for ( iter = 1 ; iter <= NUM_BENCHMARK_ITERATIONS ; iter ++ ) 
  00009.: Main:3 0.00139683834277 0.00139684 1 (1/766281.040379) (1/49.6496093343) *** int flags [ 8191 ] ; flags . numElements = 8191 ; 
  00010.: Main:5 0.000907952198759 0.000907952 1 (1/1178884.4611) (1/1.53844920986) *** int NUM_BENCHMARK_ITERATIONS = ( 100 ) ; 
  00011.: Main:8 0.000628584530205 0.000628585 1 (1/1702827.0457) (1/1.44443929994) *** int size = 8190 ; 
  00012.: Main:18 -451.222137548 0.000646717 819200 (1/0) (1/0) *** for ( i = 0; i <= size ; i ++ ) 
  00013.: Main:22 -859.132936166 0.000713092 189900 (1/0) (1/0) *** prime = i +i + 3 ; 
  00014.: Main:23 -863.534195727 0.000698406 189900 (1/0) (1/0) *** k = i + prime ; 
  00015.: Main:17 -1843.44246919 0.000698763 1638300 (1/0) (1/0) *** for ( i = 0 ; i <= size ; i ++ ) flags [ i ] = true ; 
------------------------------------ 
------------------------------------ 
Profile result (avg_millisec) (Top 10.000): 
  Num statement lines covered: 15/71 
  <linenr>   <module_name> <line_nr> <total_ms> <avg_ms> <call_count> <ratio1st> <ratioParent> 
  00001.: Main:10 0.974704889813 0.974705 1 (1/1) (1/1) *** trace Eratosthenes Sieve prime number calculation ; 
  00002.: Main:34 0.850527081639 0.850527 1 (1/1.14600100438) (1/1.14600100438)*** trace count +  primes ; 
  00003.: Main:12 0.802755646873 0.802756 1 (1/1.21419873359) (1/1.05950931015)*** trace 10000 iterations<br> ; 
  00004.: Main:3 0.00139683834277 0.00139684 1 (1/697.793624336) (1/574.694739035) *** int flags [ 8191 ] ; flags . numElements = 8191 ; 
  00005.: Main:5 0.000907952198759 0.000907952 1 (1/1073.52005) (1/1.53844920986) *** int NUM_BENCHMARK_ITERATIONS = ( 100 ) ; 
  00006.: Main:22 -859.132936166 0.000713092 189900 (1/1366.87050682) (1/1.27326034275) *** prime = i + i + 3 ; 
  00007.: Main:27 1070.37073854 0.000709596 1499900 (1/1373.60634567) (1/1.00492792756) *** k += prime ; 
  00008.: Main:26 85.5757512327 0.000708569 1499900 (1/1375.59576651) (1/1.00144831949) *** flags [ k ] = false ; 
  00009.: Main:16 0.0724954879843 0.000704962 100 (1/1382.63492959) (1/1.00511717414) *** count = 0 ; 
  00010.: Main:17 -1843.44246919 0.000698763 1638300 (1/1394.90068287) (1/1.00887128845) *** for ( i = 0 ; i <= size ; i ++ ) flags [ i ] = true ; 
  00011.: Main:23 -863.534195727 0.000698406 189900 (1/1395.61442027) (1/1.00051167614) *** k = i + prime ; 
  00012.: Main:14 0.0693524780218 0.00069395 101 (1/1404.57446798) (1/1.00642014555) *** for ( iter = 1 ; iter <= NUM_BENCHMARK_ITERATIONS ; iter ++ ) 
  00013.: Main:29 129.941014748 0.000677589 189900 (1/1438.48992269) (1/1.0241464269) *** count ++ ; 
  00014.: Main:18 -451.222137548 0.000646717 819200 (1/1507.15887171) (1/1.04773683008) *** for ( i = 0 ; i <= size ; i ++ ) 
  00015.: Main:8 0.000628584530205 0.000628585 1 (1/1550.6345495) (1/1.02884611477) *** int size = 8190 ; 
------------------------------------
1.4.3.9. Emitting inline documentation in DOG format
The -ee, --emitexplanations option is used to dump code documentation (written using the explain keyword) to stdout. The resulting file can be fed to the DOG (see The DOG manual) to produce a set of HTML pages. These HTML pages can also be linked with other documentation. For example, this HTML documentation was auto-generated using dog and dog++ (for the plugin documentation).

auto-generated by "DOG", the TkScript document generator. Wed, 31/Dec/2008 15:53:35