TkScript |
|
reference guide | User Interface |
Table of Contents:
-
1. User interface
-
1.1. Environment variables
-
1.2. Registry entries (Win32)
-
1.3. MIME integration
-
1.4. Command line interface
-
1.4.1. Overview
- Help/usage
-
1.4.2. Scripts
- Arguments passed to script applications
-
1.4.3. Commandline options by category
-
1.4.3.1. Show runtime version
- How to print version information to stdout
-
1.4.3.2. Running script applications
-
1.4.3.2.1. File extensions
- .tks, .tkp, .tkx, .tsl
-
1.4.3.2.2. Default application path
- app: and TKS_APPLICATION_PATH
-
1.4.3.2.3. Overriding/setting default library, application, module and plugin directories
-
1.4.3.2.4. Adding extra files to a pre-packaged application
- -ef, --extrafile <file>
-
1.4.3.2.5. Function stack sizes and recursion depth
- -fss, --functionstacksize, -fcs, --functioncallstacksize
-
1.4.3.2.6. Quiet program execution
- -q, --quiet
-
1.4.3.3. Compiling/packaging applications and libraries
-
1.4.3.4. Memory pooling related options
-
1.4.3.5. JIT related options
-
1.4.3.6. Debugging
-
1.4.3.7. Runtime feature restrictions
-
1.4.3.8. Statement profiling
- -esp, --enablestatementprofiling
-
1.4.3.9. Emitting inline documentation in DOG format
- -ee, --emitexplanations
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
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: |
- 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)
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
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: |
- 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: |
- 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
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.
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:
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:
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
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