1. TkScript Reference Guide » VFS

reference guide | VFS

Table of Contents:

1. Projects and TKX archives
  1. TkScript Reference Guide » VFS » Projects and TKX archives
  2. TkScript reference guide / Modules » Script modules » Project files

TKS uses a virtual file system (VFS) which allows to transparently access packaged .tkx archives as well as real local filesystems.
The VFS is read-only and all contained files have to be specified in a project file (.tkp), which is used to map logical to local file names.
The project file is evaluated when testing a project during development and finally when the project is converted to a compressed .tkx archive.
This mechanism makes it possible to package an application in a single, compact and gzip compressed file which can easily be distributed / published. Furthermore, exchanging e.g. an image file for another is merely a matter of changing the project file; no knowledge of the actual script-code is required.
created="8.November 2003" 
"programming" ="Bastian Spiegel <bs@tkscript.de>" 
"code/mymodule.tks" ="mod:mymodule.tks" 
"code/main.tks" ="main.tks" 
"data/any" ="data/foo.bar" 

Here's another (more simple) example (smoothscroll.tkp):
font.png = emacs-1920x16x8.png 

As you can see, a project file basically lists all the files that shall be included in the .tkx resp. .tsl files when packaging the project.
Local pathnames can be assigned alias names so that the script code does not have to be updated when the actual resource filename changes.
Setting a proper [project] name is merely important when creating script libraries resp. exporting documentation info (via the -ee command line option).
You can ignore the [chapter] section, it was used in early TkScript/ActiveX releases to show a loader/intro while the rest of the package was still downloading.
The [authors] section is optionally provided for informational purposes.
Script packages (.tkx, .tkp, .tks) can be integrated with a web/file browser by installing a MIME handler, see MIME integration.
2. Accessing local files
  1. TkScript Reference Guide » VFS » Accessing local files
The File class is used to access local files.
The PakFile class is used to transparently map files to either the local filesystem or the TKX virtual filesystem.
The StdInStream, StdOutStream and StdErrStream classes are used to access the standard file streams.
To avoid the problems that arise with the different kinds of presentations of pathnames under different operating systems, absolute pathnames should be avoided if possible.
The / char, which fortunately has become common even under Microsoft Windows (which uses the \ char by tradition) should be used to separate directories. Drive-letters and mount points should not be used for portabilities sake.
Note: The access to local files (except the ones listed in the project file) can be entirely prevented by using the command line switch --nolocalfiles, see TkScript reference guide / User Interface.
3. Script source files
  1. TkScript Reference Guide » VFS » Script source files

A script source (.tks) is added to a project simply by adding its file name in the .tkp file. All files (modules) ending with .tks will be compiled/initialized when the project is run.
The prefix mod: substitutes the current module searchpath. The prefix lib: substitutes the current library searchpath.
Backticks can be used to include a file, e.g. `some file.txt` .
Please consider that the script sources will be included in the packaged archives unless script libraries (lib:) are used.
Example myproject.tkp:
# a comment 
4. Testing a project before packaging it
In order to test a project (.tkp) before packaging it to a .tkx archive, simply run the project file:
$ tks myproject.tkp 

You can leave out the file suffix, it will be added automatically:
$ tks myproject 
4.1. How files are mapped
Pak files are accessed by their logic file names.
The logic file name is the same as the local file name if the corresponding project file line only contains a single token:

If the line in the project file contains two tokens separated by the = character, the logic file name on the left handside is mapped to the local file on the right hand side:
mylogicfilename.txt = resources/textfiles/localfile.txt 

The current working directory is stored when the script runtime is initialized. If a pak file entry does not have an absolute path name, it will be prefixed with the stored working directory.
This means that it is safe to switch the working directory while the application is running: Pak files will still be mapped to the correct local file.
5. Creating distributable TKX archives
  1. TkScript Reference Guide » VFS » Creating distributable TKX archives
A TkScript project (.tkp) can be compiled to a compressed .tkx file which will then contain all files required for execution, i.e. those listed in the project file.
Example project file sieve.tkp:

Example command line to package the sample project:
$ tks -c sieve.tkp 

The suffix .tkp may be omitted:
$ tks -c sieve 

Afterwards, a sieve.tkx file should be located in the current directory.
As described in the TkScript reference guide / User Interface section, there are several command line options to optimize packages for size, e.g. by disabling line number information or tokenizing the script before compression:
$ tks -ps -nln -c sieve 

Note: .tkx files require zlib support.

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