1. TkScript Reference Guide » Variables

reference guide | Variables

Table of Contents:

1. Values and variables
  1. TkScript Reference Guide » Variables » Values and variables
A value is basically a piece of memory that stores
  • The type of the value (int, float, Object(-reference))
  • Ownership for object reference (boolean flag)
  • The actual value (32 or 64bits)
1.1. Container objects
Values can be assigned to container objects, like e.g. hash tables, variables, arrays or scriptclass objects.
The core TkScript API includes the following container classes: ClassArray, IntArray, FloatArray, HashTable, List, ListNode, ObjectArray, PointerArray, Pool, StringArray, TreeNode, Value, ValueArray.
1.2. Variables
Variables are basically named values.
Variables are visible in the scope in which they have been declared.
TkScript uses the following "scopes" for variables:
  • Global variables
    • Module variables (declared in the root statement sequence of a single source file)
      • Usually visible only within that module
    • Namespace variables
      • If the default namespace has been selected, variables will be stored in the scope of the current module
      • If a specific namespace has been created or selected, variables will be stored in the scope of that namespace
  • Function/Method variables
    • Declared in the statement tree of a script function or method
    • Declared in the parameter list of a script function or method
    • Function/method variables can be local or static
    • Usually not visible outside the function

Usually, a variable is not allowed to change type after it is declared.
An exception for this is the var (variant) datatype.
In the widest sense, script classes also provide a "scope" for named values (not unlike a HashTable). Class variables are called members, or fields.
Class members are initialized when a new instance of a class is created. Likewise, the members will be destroyed when a class instance (Class, Object) is deleted.
2. Basic datatypes
  1. TkScript Reference Guide » Variables » Basic datatypes

The following datatypes have designated code-paths in the scriptengine:
  • variant (var)
  • integer (int)
    • int has the following aliases:
      • boolean
      • byte
      • char
      • short
  • single precision floating point number (float)
  • (Object) Pointer.
    • A pointer is a reference to an instance of a C++ resp. script-class and thus the key to complex datastructures.
  • char sequence (String)
    • Strings are special object pointers

For reasons of simplicity, no further distinction between signed and unsigned integers is made (all integers are signed).
The boolean, char, byte and short datatypes are actually all mapped to the int datatype.
In case you need real e.g. unsigned byte arithmetic you must use the corresponding number object (e.g. UnsignedByte, also see Byte, Short, Integer, Float, Double, Long, UnsignedShort, UnsignedInteger, UnsignedLong).
TkScript has been tested on 32bit and 64bit platforms.
An int is 32bit also on 64bit platforms, please use the Long or UnsignedLong datatype if you need to handle 64bit integers.
The script language automatically converts between the datatypes String, int and float.
2.1. Some examples for variable declarations

int i;
int x = 10, y = 20, z = 30; // Declaration list and initialization
float f = 2PI;
String s = "hello, world."; // assign a copy of the right-handside String
String t <= "hello, world."; // reference to constant String
function SpawnNewString {
local String s = "hello, world.";
return deref s;
String r <= SpawnNewString();
3. Number objects
  1. TkScript Reference Guide » Variables » Number objects
  2. TkScript reference guide / Scanner » Number formats and literals » String-number conversions at runtime
TkScript provides number object classes for access to e.g. 64bit double or integer values.
The following number objects are built into the script engine: Boolean, Byte, Double, Float, Integer, Long, Short, UnsignedByte, UnsignedInteger, UnsignedLong, UnsignedShort.
These number objects can be used like they were native datatypes.
3.1. Number object example

Double da,db,dc;

da = 2PI; // assign 32bit float Values
db = 0.0000001;
dc = da * db * 0.12345678; // test mixed
print dc.printf("%4.24g");

da = 2.2;
dc = 3 * da; // test int-Double
print "dc=" + dc.printf("%4.24g");
3.2. Using number objects to pass atomic values by reference

Number objects are also useful to pass references to atomic int/float values by reference:

function Test(Float x, Float y, Float z) {
x = 1;
y = 2;
z = 3;
Float x, y, z;
Test(x, y, z);
trace "vec=("+x+";"+y+";"+z+")";
4. Dynamically typed variables
  1. TkScript Reference Guide » Variables » Dynamically typed variables

TkScript also supports dynamically typed variables (variants). The type of such a variable depends on the value assigned to it.
Please notice that (as of version you cannot access members and methods of complex datatype variants.
Arrays and hash tables should work, though.
Class members may not use the var datatype.
Dynamically typed variables are rarely needed but have proven useful when e.g. reading values from an Envelope class. They allow to distinguish whether a method has actually returned a value or nothing (void).
TkScript has been designed to be at least weakly typed. Objects must be cast to specificially typed classes before members or methods can be accessed.
The typeid and typename built-in functions can be used to query the type id or name of any given value.
For objects, the instanceof operator can be used to determine compatibility to any given class type.
The three basic datatypes (well, four including the String type), are:
  • YAC_TYPE_VOID -- 0, no type
  • YAC_TYPE_INT -- 1, 32bit integer
  • YAC_TYPE_FLOAT -- 2, 32bit floating point value
  • YAC_TYPE_OBJECT -- 3, reference to C++ (or scriptclass) object
  • YAC_TYPE_STRING -- 4, pseudo-type, reference to a C++ String object

The Value class is used to capture values into an Object countainer.
4.1. Example for the "var" datatype

var i=42;
var f=1.23;
var s="hello, world.";

print "typename(i)="+typename(i); // => int
print "typename(f)="+typename(f); // => float
print "typename(s)="+typename(s); // => String
5. Builtin native classes
  1. TkScript Reference Guide » Variables » Built-in native classes

See core for a list of the builtin native datatypes.
See tksdl, tkopengl, →tkcg, .. for more information about native classes exported by additional plugins.
The usefulness of a script engine is probably defined by the available native plugin APIs.
If you want to do anything outside of basic array/hash/string processing, then please take a look at the available plugins or simply write your own (it's simple if you know C++).
An interesting application of TkScript is tkui, a scripted graphical user interface (GUI) framework which uses the tksdl and tkopengl native backends.
6. User defined classes
  1. TkScript Reference Guide » Variables » User defined classes

Example for declaring a new script class datatype:

class MyClass {
int i = 42;
float f = PI;
String s = "hello, world.";

method test()
trace "MyClass::test() called.";
MyClass mc;
print mc.i;
mc.f *= 2;
print mc.f;
7. Value wrapper objects
  1. TkScript Reference Guide » Variables » Value wrapper objects
  2. TkScript reference guide / Expressions » The #() value expression
  3. TkScript reference guide / Functions » Native functions
Values (e.g. the result of an expression) can be captured into a Value wrapper object. The Value object also stores the object ownership flags (i.e. whether an Object is deletable).
This mechanism is mostly useful to pass deletable object references to e.g. native function/method calls.
(Note: objects are always passed by reference, without the ownership flag, in native call argument lists)
Other native classes that can store dynamically typed values are HashTable, List, ListNode, PointerArray, ValueArray and Variable.
Also see The #() value expression, Native functions.
7.1. Example
This example demonstrates how to capture a deletable String object in a Value object.

Value v <= #(String(42));
8. Scope of variables
  1. TkScript Reference Guide » Variables » Scope of variables
  • A variable declared in a module-global statement is visible only in the module's scope
  • If a namespace other than "default" is selected, the variable will be placed in the selected namespace
  • Variables declared within a function are visible in the function's scope
  • Function variables shadow global variables and class members
  • Function variables are "static" by default, use the "local" keyword to place variables in the function stack frame if the function is re-entrant or being called recursively.
  • Many language constructs support namespace addressing in identifier names

Global variables in other modules are accessible by prepending the module's name, e.g. MMyModule.myvariable.
Variables in other namespaces are addressed by prepending the namespace name, e.g. mynamespace::myvariable.

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