TkScript Reference Guide

Up:

Index of TkScript » Documentation
Index of TkScript » Documentation » TkScript reference guide

TkScript

Reference Guide

Table of Contents:

1. Introduction - Purpose of this documentation and some hints
2. System requirements and installation - How to download/install TkScript
3. License » Legal stuff, please read before using TkScript
- 3.1. TkScript » Software License for the core script engine (TkScript)
- 3.2. YAC » Software License for the TkScript/C++ plugin interface
- 3.3. Plugins » Software licenses for native plugins
- 3.4. TkScript applications and libraries » Software Licenses for applications and libraries written in TkScript
4. User Interface » Command line arguments, MIME types, env. variables..
- 4.1. Environment variables » Environment variables recognized by TkScript
- 4.2. Win32 registry entries » Registry keys recognized by TkScript
- 4.3. MIME integration » Mainly used to click-start .tkx files in web- or filebrowsers
- 4.4. Command line interface » Description of command line arguments
5. VFS » Projects, the virtual filesystem and TKX packages
- 5.1. Projects and TKX archives » About project files (.tkp)
- 5.2. Accessing local files » About filestreams, pathnames and separator chars..
- 5.3. Script source files » How to add a script file to a project
- 5.4. Creating distributable TKX archives » Converting a project to a single-file package
6. Modules » Script source files
- 6.1. Module names » How to assign unique module names
- 6.2. Common module include directory » How to include files from a common directory
7. Scanner » Identifiers, keywords, literals, constants, comments, ..
- 7.1. Comments » How to exclude text passages from being interpreted as code
- 7.2. Reserved keywords » A list of all reserved keywords
- 7.3. User defined constants » About module, class and plugin constants
8. Variables » Values, variables and datatypes
- 8.1. Values and variables » About values, variables and container objects
- 8.2. Basic datatypes » Atomic datatypes
- 8.3. Number objects » Additional C++ number types provided by the core API
- 8.4. Dynamically typed variables » When the variable type depends on the currently assigned value
- 8.5. Built-in native classes » Datatype classes written in C++
- 8.6. User defined classes » Datatype classes written in TkScript
- 8.7. Value wrapper objects » Most commonly used to pass an object reference plus ownership to a native C++ extension function or method
- 8.8. Scope of variables » Where variables are placed are where they can be "seen"
9. Objects » Objects, pointers and memory managment
- 9.1. The YAC_Object interface » Description of the core C++ base class that all TkScript objects are derived from
- 9.2. Object references (pointers) » About references to objects, types and ownerships.
- 9.3. Spawning new objects » When and how new objects are created
- 9.4. Deleting objects » When automatic clean-up happens and how to force deletion of an object
- 9.5. Memory managment » DOs and DONTs when dealing with object references
10. Strings » A word or two about strings
- 10.1. Splitting strings » How to split a string into an array of substrings
- 10.2. File I/O » Reading/writing ASCII files
- 10.3. XML » The minimalistic XML parser built into the String class
  - 10.3.1. XFM » The tkui user interface description language, a sample application for the XML parser
11. Operators » Operators and priorities, arrays, hashtables and streams
- 11.1. Operators » Brief introduction to operators
- 11.2. Assignment operators » double-arg expression shortcuts in assignments
- 11.3. Operator priorities » List of priority levels
- 11.4. Array operator » Reading/writing array elements
- 11.5. The stream operator » Reading and writing objects from and to I/O streams (serialization)
12. Expressions » Standard and special purpose expressions
- 12.1. Constant expressions » Constants and constant folding
- 12.2. Variable expressions » Returning the value of a variable
- 12.3. The new and deref expressions » Create new objects or unlink them from variables or script class members
- 12.4. The [] array expression » Creating arrays on-the-fly
- 12.5. The #[] hash table expression » Creating HashTable objects on-the-fly
- 12.6. The #() value expression » Creating Value objects on-the-fly
- 12.7. The {} list expression » Creating ListNode objects on-the-fly
- 12.8. The instanceof expression » Used to test whether two (native or script class) objects are type-compatible
- 12.9. Expressions as statements » The magic _ variable
- 12.10. Built-in functions » Other built-in function expressions and intrinsics
13. Statements » Statements, flow control and statement sequences
- 13.1. Statement sequences » ... { } ...
- 13.2. The if..else statement » Conditional execution of two alternative statement sequences
- 13.3. The do..while statement » Conditional loop that checks the loop condition after an iteration
- 13.4. The while statement » Conditional loop that checks the loop condition before an iteration
- 13.5. The switch statement » Multiple choice selection of code paths
- 13.6. The for statement » Conditional loop, similar to while but with pre/post sequences
- 13.7. The loop statement » Conditional loop with a fixed loop condition
- 13.8. The foreach statement » Used to iterate container objects
- 13.9. The break statement » How to break out of loops
- 13.10. The try..catch, finally statements » Error/exception handling
- 13.11. The prepare statement » One time variable initializations
- 13.12. The clamp and wrap statements » Used to clamp or wrap int and float values to/within a given range
- 13.13. The use statement » Load native code plugins and bind signal handlers
- 13.14. The define and enum statements » User defined module and class constants
- 13.15. The print statement » print, trace, dtrace, die, stderr, stdout
- 13.16. The trace statement » trace and dtrace
- 13.17. The die statement » Raise fatal exception and quit application
- 13.18. The function statement » Define a function
- 13.19. The constraint statement » Define a function argument or return value constraint expression
- 13.20. The exception statement » Define a new exception type
- 13.21. The return statement » Return from a function or method call
- 13.22. The class statement » Define a class
- 13.23. The delegate statement » Define a class method delegate
- 13.24. The explain statement » Document a function, method, class or constant
14. Functions » Functions and static methods
- 14.1. Functions » Introduction to functions
- 14.2. Native functions » About native "C" functions
- 14.3. Module functions » About module functions
- 14.4. Static methods » About class functions
- 14.5. Arguments » About function argument lists
- 14.6. Recursion » Re-entrant and recursive functions
- 14.7. Return value » About function return values
- 14.8. Constraints » Validity checks for arguments and return values
- 14.9. Function objects » How to create references to functions or static methods
- 14.10. Synchronization » How to synchronize methods in a multi-threaded application
15. Exceptions » Exception and error handling
- 15.1. Inheritance » About exception inheritance and pre-defined exception types
- 15.2. Critical exceptions » About fatal errors and parachutes
- 15.3. Uncritical errors » About expected error conditions
- 15.4. try and catch » .. and finally
- 15.5. die » Output message and raise Death exception
16. Classes » Script classes
- 16.1. Declaration » About class declarations and namespaces
- 16.2. Polymorphy » About base classes and multiple inheritance
- 16.3. Members » About class members / fields and permissions
- 16.4. Methods » About methods, constructors, vtables and multi-thread synchronization
- 16.5. Constants » How to define constants in the scope of a class
- 16.6. Exceptions » How to define exceptions in the scope of a class
- 16.7. Delegates » Callback methods in the scope of a class

1. Introduction

This Reference Guide is meant as a hands-on documentation for the TkScript language and its core API.

It does not teach programming in general. However, I tried to include as many (self contained) code examples as possible.

If you already know other (procedural) programming languages, this guide should get you started with TkScript in no time.

If you don't, never mind, the hardest part of "programming" is usually not the syntax, anyway ;)

Here are a few hints that you should keep in mind:

Memory managment is, to a certain degree, up to the script application !
- There is NO garbage collector
  - Nevertheless, memory allocation speed is close-to-optimum due to object pooling. a good, optimized C runtime (e.g. GNU libc) is almost as fast as this. however, benchmarks with other C runtimes have shown that a 2-700% speed up can be achieved.
- Make sure to read Spawning new objects
For novices: it is often not necessary to use "pointers", most objects can copy other objects (=)
RAII (Resource_acquisition_is_initialization, look it up on the web!)
TkScript is a *support* language for compiler languages like C and C++. it is not meant to replace them !
- Put your number-crunching, pixel-pushing, cpu-intensive loops in a native C++/YAC plugin !

~Bastian

2. System requirements and installation

Up:

Index of TkScript » Documentation » TkScript reference guide » System requirements and installation

TkScript is available as source code which is distributed under terms of the GNU General Public License.
Precompiled packages for Win32/X86 are released on a regular basis.

The sources can be compiled on Win32, Linux, Cygwin (tested) and probably also on other Un*x - alike operating systems (Solaris, Irix, QNX, FreeBSD, ...). Also see Compiling on GNU/Linux.

TkScript uses zlib to handle compressed script packages (.tkx, .tsl).

The script engine has been tested on several CPU architectures including Intel x86, Motorola 68K, PowerPC and ARM v5-v7.

The plugin libraries have different requirements, e.g. OpenGL 1.1 and SDL/SDL_net are required for the tksdl and tkopengl plugins.

The JIT is currently only supported on X86/32bit. A new JIT (featuring e.g. register allocation) has been developed which currently supports the X86/32, X64 and ARMv5 instruction set architectures (ISAs) but it still needs to be integrated in TkScript.

Please see the Downloads page for details on how to obtain and install TkScript.

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