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 NSStringstring 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 .