Syntax supported so far:

Note that words in <angle brackets> are non-literals (i.e. replace that with something else) and things in [square brackets] are optional (i.e. you can leave them away).

1.0	STRUCTURES:

	1.1	CONDITIONALS:

		if <expression> then
			<commands>
		[else
			<commands>]
		end if
	  or
		if <expression>
		then
			<commands>
		[else
			<commands>]
		end if

		(one-line if-then statements are not supported yet)

	1.2	LOOPS:

		1.2.1	WHILE LOOPS:
			repeat while <expression>
				<commands>
			end repeat
			
			This will loop as long as <expression> evaluates to TRUE.
		
		1.2.2	COUNTED LOOPS:
			repeat with <varName> = <startNum> [down] to <endNum>
				<commands>
			end repeat
			
			This will loop from <startNum> to <endNum> as long as
			the latter is larger or the same as the former. The loop
			counter's value will be stored in a variable of name
			<varName>. If the optional "down" keyword is specified,
			the loop will count down instead of up, and <endNum>
			must be less than or equal to <startNum>. All numbers
			must be integers.
			
			Note that opposed to HyperCard, the variable <varName>
			really *is* the counter. That means that if you change
			the counter, you will change the behaviour of the loop.
			_HyperCard_ keeps an internal counter which it simply
			copies to the counter variable each time through the
			loop.
	
	1.3	MESSAGE HANDLERS:
		
		on <handler name> <param1>, ... , <paramN>
			<commands>
		end <handler name>

		A handler name may consist solely of alphanumeric characters and
		the underscore character. See also 8.1 on valid handler names.
		
	1.3	FUNCTION HANDLERS:
		
		function <function name> <param1>, ... , <paramN>
			<commands>
		end <function name>
		
		A handler name may consist solely of alphanumeric characters and
		the underscore character. See also 8.1 on valid handler names.

		(If you set the proper compiler flag, Joker will not distinguish
		between functions and handlers, and will allow calling a function
		with handler syntax and vice versa, and will complain about a
		function and a handler having the same name inside a script)

2.0	COMMANDS:

	2.1	ASSIGNMENT:

		put <expression> into <container>
		set [the] <propertyName> to <expression>

	2.1	OUTPUT:

		put <expression>
		
		(appends to console window)
	
	2.2	RETURN:
	
		return [<value>]
		
		This command sets the return value of a function or message handler. It also
		causes the handler to exit at this point, i.e. any commands following a return
		instruction are ignored. If the <value> parameter is omitted, the instruction
		is considered identical to "return empty".
	
	2.3	MESSAGE HANDLER CALL:
		
		<handler name> <param1>, ... , <paramN>
		
		The result of the message handler is stored in the local variable "the result".
		It defaults to an empty string but can be changed using the "return" command.
			
	2.4	GLOBAL DECLARATION:
		
		GLOBAL <global name>
		
		This global will now be useable like any other variable and exists until
		the program quits.
	
	2.5	MATHEMATICAL INSTRUCTIONS:
		
		add <number> to <container>
		subtract <number> from <container>
		multiply <container> by <number>
		divide <container> by <number>
	
	2.6	TEXT MANIPULATION:
		
		replace <pattern> through <newString> in <text>
	
	2.7	QUOTED STRING LITERAL:
		
		"string"
		
		If a line begins with a quoted string literal, it is considered to be
		equal to a line that contains this string literal preceded by the "put"
		command. I.e. you can write '"foo" into myVar' instead of 'put "foo"
		into myVar'

	2.8 DELETE:
		
		delete <object|chunk>
		
		Deletes the specified object or clears the specified chunk of a value.
		
	2.9 DEFINE:
		
		define [the] <propertyName> of <object>
		
		Add a user property to an object.
	
	2.10 DO:
		
		do <string>
		
		Executes the commands in the string <string>.

3.0 MATHEMATICAL OPERATORS:
	
	Currently, the mathematical operators only perform integer maths. Joker can convert
	strings to floating point values, but when doing maths they are turned into integers.
	
	3.1	ADDITION:
	
		<value> + <value>
	
	3.2	SUBTRACTION:
		
		<value> - <value>
	
	3.3	DIVISION:
		
		<value> / <value>
	
	3.4	MULTIPLICATION:
		
		<value> * <value>
	
4.0	BOOLEAN OPERATORS:

	4.1	EQUALITY:
		
		<value> = <value>
	
	4.2	INEQUALITY:
		
		<value> <> <value>
	
	4.3	GREATER THAN:
		
		<value> > <value>
	
	4.4	LESS THAN:
		
		<value> < <value>
	
	4.5	GREATER THAN OR EQUAL:
		
		<value> >= <value>
		
	4.6	LESS THAN OR EQUAL:
		
		<value> <= <value>

5.0	STRING OPERATORS:
	
	5.1	CONCATENATION
		
		<value> & <value>
		
		Converts both values to strings and concatenates them.
	
	5.1	PADDED CONCATENATION
		
		<value> && <value>
		
		Converts both values to strings and concatenates them, inserting a space
		in between.

6.0	VALUES:
	
	6.1	INTEGER:
		
		<integer>
	
	6.2	QUOTED STRING:
	
		"<string>"
		
		A quoted string literal may span several lines.
		
		If the appropriate compiler option is turned on, quoted string literals
		may contain escape sequences. An escape sequence is indicated by a
		backslash followed by a single character and allow embedding special
		characters that would otherwise require using the concatenation operator
		and a constant. Supported characters in escape sequences are:
		
			n	-	newline
			r	-	return
			l	-	linefeed
			q	-	quote
			t	-	tab
			\	-	(use this to produce a single backslash)
		
		Behaviour when using any other characters after a backslash is undefined.
		When escape sequences are on, returns are replaced with spaces unless you
		explicitly request a new line using \n, \r or \l. Tabs at the beginning
		of a line will also be ignored.
	
	6.2	UNQUOTED STRING LITERAL:
	
		<string>
		
		(This can be turned off by setting the appropriate compiler option). An
		unquoted string literal may not contain any whitespace nor escape
		sequences.
		
		If you set the appropriate compiler option, unquoted string literals will
		be handled as if they were variables into which you have already put their
		name. This implies that if you use such a variable as a loop condition and
		change its value in the loop, the next time the loop condition is evaluated
		you will compare not to the constant but to a variable of that name.
	
	6.2 CONSOLE:
		
		For retrieval (that is, read-only):
		stdIn
		standardInput
		(Standard Input is not yet hooked up for JokerLib)
		
		For display (that is, set-only):
		stdOut
		standardOutput
	
	6.3	CONSTANT
		
		return		-	The return character (ASCII 13).
		null		-	The null character (ASCII 0).
		cr			-	The return character, again.
		lineFeed	-	The line feed character (ASCII 10).
		lf			-	The line feed character, again.
		newline		-	The default character for line breaks on this platform.
		tab			-	The tab character (ASCII 9).
		colon		-	The colon character (:).
		quote		-	The quote character (")
	
	6.4	VARIABLE
		
		<variable name>
		
		You declare a variable by putting something into it. Note that undeclared
		variables might be interpreted as string literals.
		
		6.4.1	THE RESULT
			There is also a special variable, "the result", which holds the
			return value of handler calls and is accessed using:
			
				the result
				
			Note that you should not assign values to "the result". Instead, use the
			"return" command if you need to specify the currently running message
			handler's return value.
		
		6.4.2	THE ITEMDELIMITER
			Another special variable, "the itemDelimiter", lets you set the character
			used as the separator character for the "item" chunk type. This defaults
			to comma, but you can use any other character.
			
			This will be turned into a property in a future version of Joker.
	
	6.5	BOOLEAN
		
		true
		
	  or
		
		false
	
	6.6	CHUNK
		
		<chunkType> <startIndex> [to <endIndex>] of <value>
		
		Where chunkType can be either WORD, CHAR, CHARACTER, ITEM or LINE.
		The item delimiter defaults to "," but you can change the special
		variable "the itemDelimiter" to any other single character to be used.
	
	6.7	COUNTING CHUNKS
		
		the number of <chunkType>s of <expression>
		
		Returns the number of characters, items, lines or words in the string
		representation of the expression passed.
	
	6.8	ARRAY
		
		element <index> of <value>
		entry <index> of <value>
		
		Where index is a string that uniquely identifies one array element. Value
		must be a variable or another array expression, i.e. elements may contain
		other elements if desired, allowing the use of multi-dimensional arrays.
	
	6.9	FUNCTION CALL
		
		<handler name>( <param1>, ... , <paramN> )
		
		The result of the function handler call is used as its value. It defaults
		to the empty string, but by using the "return" command inside the function
		it can be changed.
		
		Joker knows a number of built-in functions that can also be called using this
		syntax:
		
		offset( <pattern>, <text> [, <startOffs>] )
			This function returns the position of the first character of the first
			occurrence of the string <pattern> in the string <text>. Optionally,
			you can specify a starting offset (zero-based) that causes this function
			to look for the first occurrence of <pattern> after the specified starting
			offset. <startOffs> defaults to zero.
		bitAnd( <numA>, <numB> )
			This function performs a bitwise AND on its parameters and returns the
			result of that operation.
		bitOr( <numA>, <numB> )
			This function performs a bitwise OR on its parameters and returns the
			result of that operation.
	
	6.10	ONE-ARGUMENT FUNCTION CALLS
		
		[the] <function name> of <param1>
		
		Calls a built-in one-argument function with one parameter. Currently
		supported are:
		numToChar	- Takes an ASCII value and returns the corresponding character.
		charToNum	- Takes a character and returns the corresponding ASCII value.
		numToHex	- Turns a decimal integer into a hexadecimal string.
		hexToNum	- The reverse of numToHex.
		numToShort	- Turns an integer into a two-byte short word in binary form.
		numToLong	- Turns an integer into a four-byte long word in binary form.
		shortToNum	- The reverse of numToShort.
		longToNum	- The reverse of numToLong.
		bitNot		- Performs a bitwise NOT on an integer.
		keys		- Returns a return-delimited list of all indices of an array.
		param		- Takes the number of a parameter and returns its value.
		length		- Returns the number of characters in the string passed in param1.
		checksum	- Calculates a checksum from a string.
	
	6.11	URL
	
		url <URL string>
		
		You can use remote or local URLs here, if your platform supports remote URLs
		(the generic ANSI platform doesn't). On the Macintosh, there's also a special
		URL protocol supported to handle accessing the Macintosh resource-fork:
		rsrc://<filepath>/TYPE/<id>
		Where <filepath> is a search path like you would pass it to file:// URLs,
		TYPE is a four-character resource type (case-sensitive!) and <id> is the
		ID number of the resource.
		URLs also have a "files" property that lists all files/folders or resources
		in the specified folder/file. For the rsrc:// protocol, if you're using the
		files property, leave away the type and ID parts of the URL.
	
	6.12	POINT:
		
		<horz>,<vert>
		
		Where <horz> is the coordinate across (x) and <vert> goes down (y). Each
		coordinate of a point must be an integer.
	
	6.13	COLOR:
		
		<red>,<green>,<blue>
		
		Where each is a positive integer from 0 to 65535.
	
	6.14	RECTANGLE
		
		<left>,<top>,<right>,<bottom>
		
		Where <left>,<top> is a point describing the rectangle's upper left corner and
		<right>,<bottom> is a point describing the rectangle's lower right corner.

7.0	MISCELLANEOUS:
	
	7.1	ONE-LINE COMMENT:
		
		-- comment
		
		If a "--" operator occurs anywhere on a line (except in a quoted string constant),
		everything up to end of the line (but not including the line break) is skipped by
		the tokenizer. There may be commands before the "--" on a line, but anything after
		it (except the line break terminating the line) will be considered part of the
		comment and will be ignored.
		
	7.2	MULTI-LINE-COMMENT:
		
		(* comment *)
		
		Whenever the tokenizer encounters "(*" on a line in a script, it will ignore
		anything (including line breaks) on that line up to (and including) the next
		"*)". There may be commands before the "(*" on a line as well as after the
		"*)".
	
	7.3	LINE CONTINUATION:
		
		\
		
		Usually, a command in HyperTalk spans exactly one line, ending at the line
		break. However, if you put a backslash at the end of a line, this will cause
		the next line break character after it to be ignored, thus allowing you to
		stretch out a very complex command over several lines. Currently, everything
		(including comments) between the backslash and the following line break will
		be ignored by the tokenizer, but you should not rely on this behaviour.

8.0	ADDITIONAL INFORMATION:
	
	8.1	IDENTIFIERS:
		Although you can define identifiers (variable, handler and function names) in Joker
		that begin with a colon or a period character, or some other nonprintable character
		that is not considered as whitespace, you should not do so. Identifiers that
		consist of any letters other than alphanumeric characters and the underscore are
		reserved for internal use by the Joker engine.
		
		
		
(c) Copyright 1999-2001 by M. Uli Kusterer, all rights reserved.