Copyright ©1998 by AAA+ Software Forschungs- und Entwicklungs Ges.m.b.H. All Rights Reserved.
Joy Quick Reference
Syntax
cmd ?arg1 arg2 ...?
a Joy command is formed by words separated by white space. The first word is the name of the command, and the remaining words are arguments to the command. |
command1 ; command2
several commands may be written on a single line when separated by a semicolon. When written on separate lines, no semicolon is needed. |
obj messageName ?arg1 arg2 ...?
messaging like in Objective-C. The arguments may be written between the parts of messageName separated by colons. Brackets are only needed for nesting. |
$var
the dollar sign substitutes the value of a variable |
[cmd arg1 ?arg2 ...?]
brackets execute a nested command. If you want to pass the result of one command as the argument to another, you use this syntax. |
[constant]
returns the value of a constant (e.g. [NULL] returns char@0x0). |
"string"
quotation marks group words as a single argument to a command. Dollar signs and brackets are interpreted inside quotation marks |
{string}
braces also group words into a single argument, but without interpreting dollar signs and brackets within the braces |
\char
is used for special characters, e.g. \n (newline), \$ (dollar sign), \[ (bracket), \" (quotation mark), \{ (brace), \\ (backslash), \nnn (octal ASCII code) |
#comment
all characters after the # sign to the end of the line will be ignored by the Joy interpreter |
Types
bitfield width1 ?width2 ...? |
equivalent of a C bitfield (only valid inside a struct) |
BOOL
equivalent to the Objective-C type BOOL, its values represented by [NO] and [YES] |
char
equivalent to the C type char, represented by a one-character Joy string |
Class
equivalent to the Objective-C type Class |
double
equivalent to the C type double |
float
equivalent to the C type float |
id
equivalent to the Objective-C type id |
int
equivalent to the C type int (also used for enum's) |
long
equivalent to the C type long |
longlong
equivalent to the C type long long |
SEL
equivalent to the Objective-C type SEL |
short
equivalent to the C type short |
STR
shorthand for {char *} and eqivalent to char * in C |
struct type1 ?type2 ...?
equivalent of a C struct |
TclObj
equivalent to the C data type Tcl_Obj * defined by Tcl |
uchar
equivalent to the C type unsigned short |
uint
equivalent to the C type unsigned int |
ulong
equivalent to the C type unsigned long |
ulonglong
equivalent to the C type unsigned long long |
union type1 ?type2 ...?
equivalent of a C union |
ushort
equivalent to the C type unsigned short |
void
equivalent to the C type void |
Constants
[ItkObjCNullObj] |
special object representing a NULL pointer to a Tcl_Obj |
Variables
_cmd |
like in Objective-C, contains the message selector inside a skill implementation |
auto_path
list of all directories searched for auto loading |
env
array containing the environment variables |
errorCode
holds information about the last error |
errorInfo
holds the source code where the last error occurred |
objc:idCheckingEnabled
0: disable checking and don't register any id's 1: enable checking and register new id's when they are first seen by Joy 2: enable checking and register new id's at the moment the object is allocated (default) |
objc:tclTclTypeCheckingEnabled
0: no typechecking 1: arguments and return types of methods implemented in Joy are checked (default) |
self
inside a skill implementation self contains the instance receiving the message, else it contains the current Joy interpreter object |
tcl_platform
an array containing info about the hardware platform and the operating system |
tcl_rcRsrcName
name of a user specific TEXT resource which is sourced at startup. Works only on HFS and HFS+ filesystems. |
Commands
* id
shorthand for id cString - converts an NSString into a Joy string |
@ string
shorthand for NSString stringWithCString: string - converts a Joy string into an NSString. string need only be quoted when containing spaces. |
append var ?value1 value2 ...?
appends the given values to the string stored in var |
apropos pattern
searches all help pages for the regular expression pattern |
array anymore arrayName searchId
returns 1 if there are any more elements to process in an array search, 0 otherwise. searchId must be the return value from a previous invocation of array startsearch. |
array donesearch arrayName searchId
terminates an array search. searchId must be the return value from a previous invocation of array startsearch. |
array exists arrayName
returns 1 if arrayName is an array variable, 0 otherwise |
array get arrayName ?pattern?
returns a list where each odd-numbered element is the name of an element of arrayName and the succeeding element is the value of that element. If pattern is given, only those whose names match pattern (in glob-style pattern matching) are returned. |
array names arrayName ?pattern?
returns a list containg the names of all elements in array that match pattern (in glob-style pattern matching) or an empty string if there are no elements or no array of that name |
array nextelement arrayName searchId
returns the next array element in an array search. searchId must be the return value from a previous invocation of array startsearch. |
array set arrayName list
sets the value of array elements named after the odd-numbered elements of lists to the successive element |
array size arrayName
returns the number of elements in the array or 0 if it isn't an array |
array startsearch arrayName
initializes an element-to-element search through the array. Returns a search identifier which can be used by array nextelement and array donesearch. Multiple searches on the same array are allowed, adding or removing elements ends all searches on the searched array. |
break
aborts the innermost looping command |
case string ?in? patList body ?patList body ...
obsolete - use the switch command instead |
catch script ?var?
executes script and returns a non-zero value when an error occured. If var is given it contains the string returned from script (either a result or an error message). |
cequal string1 string2
return 1 if the given strings are equal, 0 otherwise |
cindex string indexExpr
returns the character indexed by the expression indexExpr from string (0 meaning the first element, end meaning the last element) |
clength string
shortcut for string length string |
clock clicks
returns a high-resolution system-dependent integer time value |
clock format clockValue ?-format string? ?-gmt boolean?
converts an integer time value (unit seconds) into a human-readable format and returns it. See help /joy/time/clock for details about the format string syntax. |
clock scan dateString ?-base clockVal? ?-gmt boolean?
converts dateString into an integer time value (unit seconds), understanding most standard date and/or time strings. See help /joy/time/clock for details. |
clock seconds
returns a low-resolution (unit seconds) system-dependent integer time value |
cconcat ?string1? ?string2 ...?
returns the string created by concatening the given strings |
concat ?list1 list2 ...?
returns the list created by putting the elements of the given lists into a single list |
continue
skips to the next iteration of a loop |
cpIn string
converts a Joy string into a dynamically allocated C string |
cpOut pointer
converts a dynamically allocated C string into a Joy string, freeing its memory |
crange string expr1 expr2
returns a substring of string ranging from the character indexed by the expression expr1 to the character indexed by the expression expr2, inclusive (0 meaning the first character, end meaning the last character) |
csubstr string expr1 expr2
returns a substring of string ranging from the character indexed by the expression expr1(0 meaning the first character, end meaning the last character) of length determined by the expression expr2(len meaning to the end of the string, end meaning len-1) |
ctoken var separators
parses a token out of the string stored in var where separators contains the separator characters for tokens in the string. The first token is returned and var is set to the remainder string following the token. |
ctype ?-failindex var? class string
return 1 if all characters in string are of the specified class, 0 otherwise. Optionally sets var to the index of the first character not in class. See help /joy/strings/ctype for the various class options. |
error message ?info? ?code?
raises an error. The optional parameters are stored in the global variables errorInfo and errorCode, respectively. |
eval arg ?arg ...?
concatenates all its arguments and evaluates the concatenation as a Joy command |
exit ?returnCode?
terminates the process with the exit status returnCode (defaults to 0). |
expr arg1 ?arg2 ...?
concatenates the arguments (adding spaces between them), evaluates the concatenation as a Joy expression and returns the result. Most C operators, the min and max operators (with two arguments) as well as string comparison are supported - see help /joy/math/expr for details. |
for start test next body
looping command similar to the C for statement. start, next and body must be Joy command strings and test is an expression string. |
for_array_keys var arrayName body
iterates over all elements of the array arrayName |
foreach varlist1 list1 ?varlist2 list2 ...? body
iterates body over all elements in the given lists, assigning each of the elements of the lists to the variables in the corresponging variable lists. Empty strings are used for missing elements (if a list is shorter than the others). |
format string ?arg1 arg2 ...?
generates a formatted string in the same way as the ANSI C sprintf procedure |
global var1 ?var2 ...?
declares the given global variables inside a proc |
help
lists of all the help subjects and pages under the current help subject |
help ?
shorthand for help help. Displays help on the help facility. |
help subject
displays all of help pages and lower level subjects (if any exist) under the subject subject |
help helppage
display the specified help page |
helpcd
return to the top-level of the help tree |
helpcd subject
change the current help subject |
helppwd
displays the current help subject |
if expr1 ?then? body1 elseif expr2 ?then? body2 elseif ... ?else? ?elsebody?
evaluates expr1 as an expression. If it does not yield 0, false or no, the script body1 is executed, else the optional elseif clauses and the optional else clause are regarded and the corresponding body is executed. |
incr var ?increment?
increments the value stored in var by the integer increment (default 1) |
interp option ?arg1 arg2 ...?
creates a new Joy interpreter that co-exists with the creating interpreter in the same application. See help /joy/control/interp for details on the various options. |
intersect list1 list2
returns the (sorted) logical intersection of two lists |
intersect3 list1 list2
returns a list containing three sorted lists: the first contains the elements of list1 that are not in list2, the second contains the logical intersection of the two lists and the third contains the elements of list2 that are not in list1 |
iset ivar
inside a skill implementation, reads the value of instance variable or property instance variable ivar |
iset ivar value
inside a skill implementation, sets the value of instance variable or property instance variable (creates a property instance variable when no instance variable of that name exists) |
join list ?joinString?
returns a list created by joining all elements of list together separated by joinString (defaulting to a space character) |
lappend var ?element1 element2 ...?
appends the given elements to the list stored in the variable var |
lassign list var1 ?var2 ...?
assigns the successive elements list to the specified variables. If there are more variable names than fields, the remaining variables are set to the empty string. If there are more elements than variables, a list of the unassigned elements is returned. |
lcontain list element
returns 1 if element is a list element of list, 0 otherwise |
lempty list
returns 1 if list is empty (i.e. an empty string or a string only containg spaces), 0 otherwise |
lindex list index
returns the index'th element of list (index 0 meaning the first element, end meaning the last element) |
linsert list index element1 ?element2 ...?
returns a list by inserting the given elements just before the index'th elementh of list (index 0 meaning the first element, end meaning the last element) |
list ?arg1 arg2 ...?
returns a list containg the given arguments as elements |
llength list
returns the number of elements of list as a decimal string |
lmatch ?option? list pattern
search the elements of list returning a list of all elements matching pattern. The pattern matching option may be -exact for exact matching, -glob for glob-style matching and -regexp for regular expressions. |
loop var first limit ?increment? body
looping command similar to the for statement, but faster and easier to code when the beginning and ending values as well as the increment are fixed known values. |
lrange list index1 index2
returns a list containg the index1'th through the index2'th elements of list, inclusive (0 meaning the first element, end meaning the last element) |
lreplace list index1 index2 ?element1 element2 ...?
returns a list with the index1'th through the index2'th elements of list, inclusive (0 meaning the first element, end meaning the last element) deleted and optionally replaced with the given elements |
lrmdups list
returns a sorted list with all duplicates removed |
lsearch ?option? list pattern
returns the index of the first element of list that matches pattern or -1 if there is no match. The pattern matching option may be -exact for exact matching, -glob for glob-style matching and -regexp for regular expressions. |
lsort ?options? list
returns list in sorted order. Available options are -ascii (default), -integer, -real and -command command for controlling the comparison of two elements and -increasing (default) respectively -decreasing for controlling the sorting order. |
lvarcat var list1 ?list2...?
concatenates the elements of the given lists to the end of the list stored in var |
lvarpop var ?indexExpr? ?string?
deletes the element indexed by the expression indexExpr (defaulting to 0) from the list stored in var and optionally replaces this element with string |
lvarpush var string ?indexExpr?
string is inserted before the element indexed by the expression indexExpr (defaulting to 0) in the list stored in var |
max num1 ?num2 ...?
returns the maximum of the given numeric values |
min num1 ?num2 ...?
returns the minimum of the given numeric values |
objc:arrayFromList list ?-nullObj nullObj?
converts a Joy list of ids into an NSArray. Occurrences of [ItkObjCNullObj] in the list are replaced with nullObj |
objc:call addr retType argTypes ?args ...?
calls the C function pointed to by addr |
objc:deallocTrace obj script
executes the Joy command script when the object obj (which is passed as first argument to script) gets deallocated |
objc:declare type symbol
declares an extern C variable symbol of the given type and links it to a Joy variable called symbol |
objc:declare type {name symbol}
declares an extern C variable symbol of the given type and links it to a Joy variable called name |
objc:declare type {name addr}
declares an extern C variable of the given type at address addr and links it to a Joy variable called name |
objc:declare returnType symbol argTypes
declares a plain C function symbol with the given returnType and argTypes and makes it accessible as a Joy command called symbol |
objc:declare returnType {name symbol} argTypes
declares a plain C function symbol with the given returnType and argTypes and makes it accessible as a Joy command called name |
objc:declare returnType {name addr} argTypes
declares a plain C function at address addr with the given returnType and argTypes and makes it accessible as a Joy command called name |
objc:decode encoding
decodes an Objective-C type encoding into a Joy type definition |
objc:define macro value
defines a macro constant analogous to the C preprocessor statement #define |
objc:delPtr addr
frees the memory pointed to by addr |
objc:encode ?-skipqualifiers? type
encodes a Joy type definition into an Objective-C type encoding. If -skipqualifiers is specified, the resulting encoding will be stripped of any leading type qualifier (such as field names), to guarantee that the first character is a type specifier. |
objc:expandType type
expands type into a form that consists of primitive types only |
objc:foreach var obj script
iterates the variable var over object obj executing the Joy code script. The container object obj must implement the objectEnumerator message such as NSArray, NSDictionary and NSSet do. |
objc:funcPtr name
returns the address of the C function name |
objc:iVarPtr obj name
returns the address of Objective-C instance variable name of object obj |
objc:info args obj ?+|-? sel
returns a list of the arguments of the object obj's selector sel (only if implemented in Joy). Specify + or - to distinguish between class and instance methods (default is -). |
objc:info body obj ?+|-? sel
returns the Joy code of the object obj's selector sel |
objc:info classes ?-all? ?-subclassof class? ?pattern?
returns a list of all classes known to the Objective-C runtime. If the glob-style pattern is specified, only those with a matching name are returned. If -subclassof is specified only subclasses of class are returned, including indirect subclasses if -all is given. |
objc:info ids ?-all? ?-class? ?-instanceof class? ?pattern?
returns a list of all objects known to Joy. If the glob-style pattern is specified, only those with a matching name are returned. If -class is given, only class and meta-class objects will be returned. If -instanceof is specified, only members of class are returned, including indirect members if -all is given. |
objc:info ivars ?-all? ?-class? obj ?pattern?
returns a list of all instance or class variables of the object obj that match the optional glob-style pattern. If -all is given, variables inherited from ancestor classes are included in the list; if -class is given, class variables are returned, else instance variables. |
objc:info macros ?pattern?
returns a list of all macro constants known to Joy. If the glob-style pattern is specified, only those with a matching name are returned. |
objc:info methods ?-all? ?-class? obj|-protocol protocol ?pattern?
returns a list of all methods of the class or object obj or the protocol protocol whose selectors match the optional glob-style pattern. If -all is given, methods inherited from ancestor classes or adopted protocols are included in the list; if -class is given, class methods are returned, else instance methods. Each element of the returned list is a list where the first element is the return type, the second is the name of the selector and the remaining elements are the argument types. |
objc:info protocols ?-all? ?obj|-protocol protocol? ?pattern?
returns a list of the names of all protocols that match the optional glob-style pattern. If either obj or protocol is given, it returns only those which are adopted by the class or object obj or the protocol protocol. If -all is given, protocols adopted indirectly (by a superclass or adopted protocols) are also included in the list. |
objc:info typedefs ?pattern?
returns a list of all typedefs known to Joy. If the glob-style pattern is specified, only those with a matching name are returned. |
objc:info version
returns Joy's version number |
objc:isNullObj obj
return 1 if obj equals [ItkObjCNullObj], 0 otherwise |
objc:isType type
return 1 if type is a type currently known to Joy, 0 otherwise |
objc:isValue value type
return 1 if value is a valid value of type type, 0 otherwise |
objc:listFromArray ?-nullObj nullObj? id
converts an NSArray into a Joy list of ids. Occurrences of nullObj in the array are replaced with [ItkObjCNullObj] |
objc:loadMacros file
loads macro constant definitions from the file named file |
objc:loadTypedefs file
loads typedef definitions from the file named file |
objc:newClass class superClass ?iVars?
adds a subclass of superClass with the name class and the additional instance variables iVars to the Objective-C runtime. iVars is a list with Joy type specifications as odd-numbered elements and instance variable names as even-numbered elements. |
objc:newProtocol name ?-protocols protocols? ?skills?
declares a new protocol with the given name that adopts the given list of protocols and implements the given skills (only prototypes, no bodies!). |
objc:newPtr type
allocates memory for type type and returns the pointer |
objc:offsetPtr addr offset ?type?
returns addr + offset * size, where size is the size of addr's type if type is not specified, otherwise the size of type. void or no type has size 1. |
objc:peek ?-trust? addr ?type?
returns the value stored at the pointer addr. If type is not specified, addr's type is used for the conversion. The option -trust tells Joy to automatically register any ids in the data structure pointed to by addr. |
objc:protocol name
returns the protocol object with the given name (analogous to @protocol(name) in Objective-C). |
objc:poke addr value ?type?
stores value at the pointer addr. If type is not specified, addr's type is used for the conversion. |
objc:sizeof type
returns type's size in bytes. |
objc:teach objlist ?-protocols protocols? skills
adds skills to the objects or classes in the list objlist, overriding any existing methods or skills. If -protocols is given, Joy will then check for each element of objlist and protocols if the object or class implements all skills required by the protocols, and, if yes, make it adopt the protocols. The new Joy code can be called from Joy as well as from Objective-C. |
objc:typedef type name
defines a new type analogous to the C typedef statement |
objc:typeOfPtr ptr
returns the target type of the pointer ptr |
objc:uncaughtException id
raises the uncaught NSException id. Should only be used in extreme cases (if at all). |
objc:undef macro
undefines the macro constant macro analogous to the C preprocessor statement #undef |
objc:unteach objlist ?skills?
removes skills from the objects or classes in the list objlist. Previous implementations will reappear. skills is a list containing selectors, optionally preceded by + or - (default is -). If skills is not given, all Joy skills are unteached. |
objc:varPtr name ?type?
returns the address of an extern C variable, optionally type-casted to type *. |
proc name args body
creates a Joy procedure name with an argument list args (any existing procedure with the same name will be replaced). The procedure may then be called using the syntax name arg1 arg2 ... |
puts ?-nonewline? ?channelId? string
if channelId is stdout, or unspecified, prints string into the interpreter window (if called interactively) or into the console window (if called by the application); else prints string to the Tcl channel channelId. |
random limit
returns an integer pseudo-random number between 0 and limit-1 |
random seed ?seedval?
resets the pseudo-random number generator to a state derived from seedval or a state derived from the current system state if no seedval is given |
regexp ?-indices? ?-nocase? regExp string ?matchVar? ?subMatchVar ...?
determines whether the regular expression regExp matches part of string and return 1 if it does, 0 otherwise. The optional variable matchVar will be set to the part of string that matches all of regExp, the additional variables will be set to the the that parts of string that match the subsequent parenthesized subexpression within regExp. If the switch -indices is given, two-elemental index lists are stored instead of substrings, if -nocase is given, the matching is case-insensitive. |
regsub ?-all? ?-nocase? regExp string subSpec var
matches the regular expression regExp against string and copies string to var, replacing the first matching part of string with subSpec. The characters & or \0 inside subSpec are replaced by the matching part of string, the characters \n are replaced with the part of string that matches the n-th parenthesized subexpression of regExp (n being a decimal digit). If -all is given, all matching parts of string are considered, if -nocase is given, the matching is case-insensitive. |
rename oldName newName
renames a command |
replicate string countExpr
Returns string, replicated the number of times indicated by the expression countExpr |
return ?-code code? ?-errorinfo info? ?-errorcode code? ?string?
returns immediately from the current procedure with string as the return value (defaulting to an empty string). See help /joy/control/error for details about the -code, -errorinfo and -errorcode options. |
scan string format var1 ?var2 ...?
parses fields from string in the same way as the ANSI C sscanf procedure and returns the number of conversions performed or -1 if there was no conversion. |
set var
returns the value of a variable (if it doesn't exist an error occurs). var may have the form arrayName(elementName). |
set var value
sets the value of a variable (creates it, if it doesn't already exist) |
source fileName
takes the contents of the specified file and passes it to the Joy interpreter as a text script. |
source -rsrc resourceName ?fileName?
sources a script from a TEXT resource with the name resourceName. If fileName is not given, all open resource files are searched. Works only on HFS and HFS+ filesystems. |
source -rsrcid resourceId ?fileName?
sources a script from a TEXT resource with the id resourceId. If fileName is not given, all open resource files are searched. Works only on HFS and HFS+ filesystems. |
split string ?splitChars?
returns a list created by splitting string at each character that is in the string splitChars. The splitChars are not elements of the returned list. If splitChars is empty, string is splitted into single characters, if it is omitted, the original string is returned. |
string compare string1 string2
compares two strings in the same way as the C strcmp procedure, returning -1, 0 or 1. You should use the NSString class instead of Joy strings if you need correct Unicode handling. |
string first string1 string2
returns the index of the first character of string2 where the first occurrence of substring string1 starts or -1 if string1 is not a substring of string2 |
string index string charIndex
returns the charIndex'th character of string or an empty string if charIndex is out of range |
string last string1 string2
returns the index of the first character of string2 where the last occurrence of substring string1 starts or -1 if string1 is not a substring of string2 |
string length string
returns a decimal string giving the number of characters in string |
string match pattern string
returns 1 if pattern matches string, 0 otherwise. Matching is done similar as in the C-shell, i.e. the wildcards * and ? are allowed and a range may be given in brackets. |
string range string first last
returns a substring of string ranging from the character indexed by first to the character indexed by last, inclusive (0 meaning the first character, end meaning the last character) |
string tolower string
returns string with all upper case letters converted to lower case |
string toupper string
returns string with all lower case letters converted to upper case |
string trim string ?chars?
returns string with all leading or trailing occurrences of chars (default " \t\n\r") removed. |
string trimleft string ?chars?
returns string with all leading occurrences of chars (default " \t\n\r") removed. |
string trimright string ?chars?
returns string with all trailing occurrences of chars (default " \t\n\r") removed. |
string wordend string index
returns the index of the character of string just after the end of the word containing the character at index index |
string wordstart string index
returns the index of the first character in the word containing the character at index index of string |
subst ?-novariables? ?-nocommands? ?-nobackslashes? string
performs variable, command and backslash substitution on string and returns the result. If any of the options is given, the corresponding substitutions are not performed. |
switch ?option? string pattern1 body1 ?pattern2 body2 ...?
switch ?option? string {pattern1 body1 ?pattern2 body2 ...?}
matches the argument string against each of the patterns in order and executes the body following the first pattern that matches. The pattern default matches any string. The pattern matching option may be -exact for exact matching, -glob for glob-style matching and -regexp for regular expressions. |
time script ?count?
evaluates script count times (default 1) and returns a string describing the average amount of elapsed time (not CPU time) per iteration |
trace variable var ops script
arrange for script to be executed whenever the variable var is accessed. ops contains a string specifying the access (r for read, w for write and u for unset). script is called with three parameters: the name of the variable, the element name if it is an array variable (empty string if not) and string specifying what kind of access happened. |
trace vdelete var ops script
removes a variable trace |
trace vinfo var
returns a list of all variable traces set on the variable var |
translit inrange outrange string
returns string with the characters occurring in inrange translated to the corresponding characters in outrange. The ranges maybe character strings or ranges with a minus sign. |
union list1 list2
returns the (sorted) logical union of two lists (any duplicates are removed) |
unset name1 ?name2 ...?
removes the given variables (also array elements or whole arrays). |
uplevel ?level? arg1 ?arg2 ...?
concatenates all its arguments and evaluates the concatenation as a Joy command in the variable context indicated by level (defaulting to 1). If level is an number it gives the relative distance up the procedure calling stack, if it consists of a # sign followed by a number if gives the absolute level in the calling stack (#0 meaning the top-level where only global variables will be visible). |
upvar ?level? otherVar1 myVar1 ?otherVar2 myVar2 ...?
arranges for local variables in the current procedure to refer to variables in an enclosing procedure or to global variables. |
while test body
executes the script body as long as the expression test does not yield 0, false or no. |
Targets (inside skill implementations)
former |
messages $self, but uses the implementation of the selector that would have been used just before the currently executing implementation was added |
objc
like former, but neglecting all methods implemented in Joy |
super
starts looking for an implementation in $self's superclass (or its class, if the currently executing skill was taught to an instance. |
Back to Joy tutorial table of contents .