add number to container
Number yields an integer, a number, or a complex. Container yields a container containing an integer, a number, or a complex.
+add 3 to it ++
+add amount to total ++
The add command adds the value of number to the value of container and leaves the result in container. The value in the container must be an integer, a number, or a complex and is replaced with the new value.
The following example sums a line-delimited list of numbers and prints the result.
++on printSum numberList + put 0 into total + repeat with count = 1 to the number of lines ¬ + in numberList + add line count of numberList to total + end repeat + put total +end printSum ++
subtract, multiply, divide, +, sum
answer question with reply or reply or reply at point
answer list promptText with list at point
answer file promptText of type fileType or fileType or fileType at point
answer folderdirectory promptText at point
answer diskvolume promptText at point
Question, reply, promptText, and fileType yield strings. List yields a list. Point yields a point.
+answer "Which is the way the world ends?" with "Bang" or "Whimper" ++
+answer file "Pick a file:" ++
The answer command displays a prompt to the user with up to three possible responses. The last response appears as the default response to the prompt. If no possible responses are specified, a single possible response will be presented with the text "OK." The script waits until one of the possible responses is chosen. The chosen response is placed in the local variable it.
The answer list command displays a prompt to the user with a list of any number of possible responses. The script waits until one of the possible responses is selected. The chosen response is placed in the local variable it and the result is set to "OK". If the prompt is dismissed without choosing a response, empty is placed in it and the result is set to "Cancel".
The answer file command displays a prompt to the user asking to select a file. The script waits until a file is selected. The path of the selected file is placed in the local variable it and the result is set to "OK". If the prompt is dismissed without selecting a file, empty is placed in it and the result is set to "Cancel".
The answer folder or answer directory command displays a prompt to the user asking to select a folder. The script waits until a folder is selected. The path of the selected folder is placed in the local variable it and the result is set to "OK". If the prompt is dismissed without selecting a folder, empty is placed in it and the result is set to "Cancel".
The answer disk or answer volume command displays a prompt to the user asking to select a disk or volume. The script waits until a volume is selected. The path of the selected volume is placed in the local variable it and the result is set to "OK". If the prompt is dismissed without selecting a volume, empty is placed in it and the result is set to "Cancel".
The exact presentation of the prompts is left to the implementation. OpenXION presents a stylized text-based prompt, or a plain text-based prompt if the -p option is given. A GUI-based system, like HyperCard, will present an appropriate dialog box. The at parameter gives a preferred location for this dialog box.
+on chooseColor + answer "Which color do you prefer?" with "Red" or ¬ + "Blue" or "Yellow" + if it is "Red" then answer "You picked red." + else if it is "Blue" then answer "You picked blue." + else if it is "Yellow" then answer "You picked yellow." +end chooseColor ++
There is no way for a script to respond to a prompt by itself, so do not use answer in a script intended to run unattended.
HyperTalk does not support the answer list, answer directory, answer disk, or answer volume forms, or the at parameter. However, the Power Tools stack has the ShowList XFCN that inspired the answer list command and HyperTalk itself has an answer program form that OpenXION does not.
ask question with defaultAnswer at point
ask password clear question with defaultAnswer at point
ask file promptText with fileName at point
ask folderdirectory promptText with fileName at point
Question, defaultAnswer, promptText, and fileName yield strings. Point yields a point.
+ask "Who needs this kind of grief?" with "Not me." ++
+ask password "Please enter your password:" ++
+ask file "Save this file as:" with "Untitled-1" ++
The ask command displays a prompt to the user and allows the user to type a response. The optional defaultAnswer parameter specifies a response that initially appears. The prompt appears with "OK" and "Cancel" choices as well. The script waits until a response is typed and one of the choices is selected. If the "OK" choice is selected, the typed text is placed in the local variable it and the result is set to "OK". If the "Cancel" choice is selected, empty is placed in it and the result is set to "Cancel".
The ask password command hides the response from the user as it is being typed and hashes the response using the Atkinson hash (see the hash function). The hashed response can be stored somewhere to be compared to a later response to ask password if, for example, you want the user to be able to protect data they enter.
The ask password clear command hides the response from the user as it is being typed, but does not hash the response.
The ask file command displays a prompt to the user asking for the location and name of a new file. The optional fileName parameter specifies a file name that initially appears. The script waits until a file name is entered. The file path is placed in the local variable it and the result is set to "OK". If the prompt is dismissed without entering a file name, empty is placed in it and the result is set to "Cancel".
The ask folder or ask directory command displays a prompt to the user asking for the location and name of a new folder or directory. The optional fileName parameter specifies a folder name that initially appears. The script waits until a folder name is entered. The directory path is placed in the local variable it and the result is set to "OK". If the prompt is dismissed without entering a folder name, empty is placed in it and the result is set to "Cancel".
The exact presentation of the prompts is left to the implementation. OpenXION presents a stylized text-based prompt, or a plain text-based prompt if the -p option is given. A GUI-based system, like HyperCard, will present an appropriate dialog box. The at parameter gives a preferred location for this dialog box.
The ask password command is not recommended for cryptographic purposes because the Atkinson hash algorithm is easily brute-forced. Instead, use the ask password clear command, then hash the cleartext password using a more secure hash algorithm.
The ask file, ask folder, and ask directory commands do not actually create the selected file or folder. The script must create the file or folder itself.
There is no way for a script to respond to a prompt by itself, so do not use ask in a script intended to run unattended.
HyperTalk does not support the ask folder or ask directory forms, or the at parameter.
beep number times
Number yields a non-negative integer.
+beep 5 ++
+beep twice ++
The beep command causes the computer to beep the specified number of times. If no number is given, the computer beeps once.
HyperTalk does not support the times keyword. It can be left off without changing the command's behavior.
close object
close applicationPath
close documentPath within applicationPath
Object yields an object with an appropriate I/O manager. DocumentPath and applicationPath yield file paths to a document file and an application file, respectively.
+ The close command, when given an object with an appropriate I/O manager (e.g., a file or URL), closes an object previously opened with the open command.
If the parameter to the close command does not have an appropriate I/O manager or is not an object, or if the with or in parameter is given, the close command closes an open application or document. OpenXION currently only supports this on Mac OS X.
To close an open application or document, OpenXION's security settings must allow the FILE_LAUNCH security key. To close an object with an I/O manager, any security keys required are determined by the I/O manager; see the documentation for the I/O manager itself (e.g., file or URL). If the required security key is denied, a script error will be triggered.
convert container from format and format to format and format
Format is one of the following: date, short date, abbreviated date, long date, English date, short time, abbreviated time, long time, English time, seconds, or dateItems.
+convert line 1 of steve from date to dateItems ++
+convert bill from date and time to dateItems ++
+convert andy to seconds ++
+convert first line of steve to long date and short time ++
The convert command gets a date or time and converts it from a particular format, if specified, to a particular format. This command works with either the local date format or the U.S. date format.
If the first parameter to the convert command is a container, the converted date or time is placed in that container. If the first parameter is not a container, the converted date or time is placed in the local variable it.
A script that needs to work with dates and times should convert them to the seconds or dateItems format before working on them. This avoids problems that may occur when running the script in a different locale. The seconds and dateItems formats are the only ones guaranteed to be recognized in any locale.
The following example prints tomorrow's date in the short format regardless of the current locale:
++on printTomorrow + get the date + convert it to dateItems + add 1 to item 3 of it + convert it to short date + put it +end printTomorrow ++
create object
create a new objectType
Object yields the descriptor of the object to be created. ObjectType is the name of an object type.
++create folder "My Files" ++
+create file "MyTemp" ++
The create command creates an object that did not previously exist. The object is created to match the given descriptor if possible. The newly-created object is placed in the local variable it.
HyperTalk only supports the creation of two kinds of objects, menus and stacks. HyperTalk does not support the new or a new forms, and does not put the newly-created object into it.
delete object
Object yields the descriptor of the object to be deleted.
+delete line 1 of steve ++
+delete char 1 to 5 of line 4 of bill ++
+delete file "MyTemp" ++
The delete command deletes an object or removes a chunk from a container.
The following example finds and deletes a name from a line-delimited list of names:
++on zapaName + put "Maller\nCalhoun\nWinkler" into list + ask "Delete which name from the list?" with empty + repeat with count = the number of lines in list ¬ + down to 1 + if it is line count of list then ¬ + delete line count of list + end repeat + put list +end zapaName ++
Using the delete command to delete a chunk is not the same as using put empty into with the same chunk. For example, if you delete a line with a statement like:
+delete line 4 of myText ++
you delete the line break as well as the text; what was previously the fifth line becomes the fourth. The following statement leaves the line break in line 4:
++put empty into line 4 of myText ++
HyperTalk only supports the deletion of chunks, menus, menuItems, and parts (buttons and fields).
dial number with modem command
Number and command yield strings.
+dial steve -- steve is a variable containing a phone number ++
+dial "555-1212" ++
+dial "555-1212" with modem ++
+dial "555-1212" with modem "ATS0=0S7=1DT" ++
Without the with modem keyword, the dial command plays the dial tones for the given phone number. With some land-line telephones, you can hold the handset against your computer's speaker while the dial command is executing to dial the given phone number. The volume of the generated tones is controlled by the dialingVolume property.
With the with modem keyword, the dial command will dial the given phone number using a modem attached to a communications port. If no modem command is specified, the default is "ATDT". The communications port used is determined by the dialingPort property. There is a one-second delay between opening the communications port and issuing the command, and a delay between issuing the command and closing the port determined by the dialingTime property.
The dial command is synchronous: it will not return until it has finished dialing. (This is different from the play, speak, and tone commands, which are asynchronous.)
OpenXION will use RXTX (gnu.io package) or the Java Communications API (javax.comm package) to communicate with the modem, whichever is available. If neither package is available, dial will do nothing but set the result to an error message.
To use the with modem keyword, OpenXION's security settings must allow the TELEPHONY security key. If the required security key is denied, a script error will be triggered.
dialingVolume, dialingTime, dialingPort, serialPorts
divide container by number rounding roundingMethod
Number yields an integer, a number, or a complex. Container yields a container containing an integer, a number, or a complex. RoundingMethod is up, down, or to, toward, or towards zero, infinity, nearest, even, ceiling, or floor.
+divide total by 3 ++
+divide line 3 of steve by 10 ++
The divide command divides the value of container by the value of number and leaves the result in container. The value in the container must be an integer, a number, or a complex and is replaced with the new value.
If a roundingMethod is given, the result is rounded to an integer. The following table shows the correspondences among the various roundingMethods, rounding functions, and division operators:
+rounding parameter |
+function | +operator | +java.math.RoundingMode |
+
|---|---|---|---|
to ceiling |
+ceil |
++ | CEILING |
+
to floor |
+floor |
+div / mod |
+FLOOR |
+
up / to infinity |
+aug |
++ | UP |
+
down / to zero |
+trunc |
+quot / rem |
+DOWN |
+
to nearest |
+round |
++ | HALF_UP |
+
to even |
+rint |
++ | HALF_EVEN |
+
See the ceil, floor, aug, trunc, round, and rint functions for descriptions of how these rounding methods work.
The following example prints the percentage represented by a fraction of two numbers passed in as parameters:
++on percent steve, bill + divide steve by bill + put trunc(steve * 100) & "%" +end percent ++
HyperTalk does not support the rounding keyword.
add, subtract, multiply, /, div
get expression
Expression yields any value.
++get the short name of file 1 ++
+get 2+3 ++
+get the date ++
The get command puts the value of any expression into the local variable it. That is, get expression is the same as put expression into it.
This page describes the commands supported by HyperTalk.
+addansweraskbeepcloseconvertcreatedeletedialdividegetmultiplyopenplayputreadsetsortspeakstopsubtractwaitwritemultiply container by number
Number yields an integer, a number, or a complex. Container yields a container containing an integer, a number, or a complex.
+multiply Subtotal by Tax ++
+multiply steve by bill ++
+multiply line 3 of andy by 25 ++
The multiply command multiplies the value of container by the value of number and leaves the result in container. The value in the container must be an integer, a number, or a complex and is replaced with the new value.
The following example adds 6 percent to each item in a list:
++on taxMe + put "12.45,15.00,150.00,76.95,10.00,14.95,19.87" into taxables + repeat with count = 1 to the number of items in taxables + multiply item count of taxables by 1.06 + end repeat + put taxables +end taxMe ++
open object as method
open applicationPath
open documentPath within applicationPath
Object yields an object with an appropriate I/O manager. Method yields the name of an I/O method. DocumentPath and applicationPath yield file paths to a document file and an application file, respectively.
+ The open command, when given an object with an appropriate I/O manager (e.g., a file or URL), opens an object for reading or writing. If the object is a file and the file does not exist, the file I/O manager creates it.
If the parameter to the open command does not have an appropriate I/O manager or is not an object, or if the with or in parameter is given, the open command launches an application or document. The open command without a with or in parameter first looks for applications, then documents. The open command with a with or in parameter opens the file documentPath with the application applicationPath regardless of what application would normally open the file. In OpenXION, the locations searched for applications and documents are determined by the applicationPaths and documentPaths properties, respectively. In HyperTalk, the locations searched for applications and documents are determined by the global variables Applications and Documents.
The following example opens a file, reads a line of data from it, then closes the file:
++on printALine + open file "MyFile" + read from file "MyFile" + put it + close file "MyFile" +end printALine ++
The following example opens a URL with the user's default web browser:
++on myLink + open url "http://www.openxion.org" +end myLink ++
The following example opens a URL and reads its contents:
++on readURL + open URL "http://www.openxion.org/" as "text" + read from URL "http://www.openxion.org/" until eof + put it + close URL "http://www.openxion.org/" +end readURL ++
The following example queries the user for a document and application before executing the open command:
+on openSomething + answer file "Select a document:" + if it is not empty then + put it into doc + answer file "Select an application:" + if it is not empty then open doc with it + end if +end openSomething ++
If the open applicationPath or open documentPath with applicationPath form is used and the specified application or document cannot be found, the interpreter must present a prompt to the user asking them to select the appropriate file. To avoid this prompt, you can use the appPath, appFile, docPath, docFile, appOrDocPath, or appOrDocFile functions. If the function returns empty, then the application or document cannot be found.
To launch applications and documents, OpenXION's security settings must allow the FILE_LAUNCH security key. To open an object with an I/O manager, any security keys required are determined by the I/O manager (e.g., file or URL); see the documentation for the I/O manager itself. If the required security key is denied, a script error will be triggered.
HyperTalk does not support the as parameter or reading from or writing to URLs.
play instrument tempo tempo notes
play stop
Instrument and notes yield strings. Tempo yields a number.
+play "harpsichord" "ch d e f g a b c5w" ++
+play "music box" "c4e c dq c f eh" ++
+play "harpsichord" "c4 a3 f c4 a3 f c4 d c c c" ++
The play command plays the specified sequence of notes with the specified instrument using a MIDI synthesizer (in OpenXION) or sampled sounds (in HyperTalk). The tempo parameter specifies the number of quarter notes per minute; the default value is 120.
The play command in OpenXION uses an extended version of the scripted music notation originally found in HyperTalk. A sequence of notes is represented as a string with notes delimited by whitespace. Each note has the following format for a regular note:
noteName octave duration velocity effect
+or the following format for a rest:
+duration r
NoteName is a letter between A and G, which may or may not be followed by any number of # symbols, each of which raises the pitch a half step, or any number of b symbols, each of which lowers the pitch a half step. In OpenXION, noteName can also be one of the letters M, N, or P followed by the MIDI dollar value, for which 60 is middle C. NoteName is the only required part of a note string.
Octave is an integer specifying which octave the note belongs to. If the octave is not specified, the last octave specified is used. The default is 4, the octave starting with middle C.
+ (Middle C corresponds to the note string C4 or B#3. The note one half step below middle C is B3 or Cb4. 440 Hz corresponds to the note string A4.)
Duration is one of the following letters:
+w |
+whole note | +
h |
+half note | +
q |
+quarter note | +
e |
+eighth note | +
s |
+16th note | +
t |
+32nd note | +
x |
+64th note | +
o |
+128th note | +
which may or may not be followed by any number of . symbols, each of which multiplies the duration by 1.5 to create a dotted note, or any number of 3 symbols, each of which divides the duration by 3 to create a triplet note. (In OpenXION, you can use any digit 2 through 9 to divide the duration by that value. Also in OpenXION, duration can be the letter d followed by the duration in MIDI ticks. OpenXION uses 64 ticks per quarter note.) If the duration is not specified, the last duration specified is used. The default is q, the duration of a quarter note.
Velocity is an extension provided by OpenXION not found in HyperTalk. It may be any of the following strings:
+fff |
+triple forte (velocity 127) | +
ff |
+fortissimo (velocity 112) | +
f |
+forte (velocity 96) | +
mff |
+(velocity 88) | +
mf |
+mezzo forte (velocity 80) | +
m |
+(velocity 72) | +
mp |
+mezzo piano (velocity 64) | +
mpp |
+(velocity 56) | +
p |
+piano (velocity 48) | +
pp |
+pianissimo (velocity 32) | +
ppp |
+triple piano (velocity 16) | +
Velocity can also be the letter v followed by the velocity of the note from 0 to 127. If the velocity is not specified, the last velocity specified is used. The default is fff or 127.
Effect is another extension provided by OpenXION not found in HyperTalk. It is one or more of the following characters:
+, |
+The note is stopped a few MIDI ticks before it normally would be, creating a stoccato effect. | +
* |
+ The note keeps playing after its duration has passed. This can be used to start a fermata. (This overrides the effect of any , or any preceding !.) |
+
! |
+ Stops a note previously started by * after the duration has passed. This can be used to end a fermata. If the note is not already playing, this is equivalent to a rest. (This overrides the effect of any preceding *.) |
+
+ |
+Starts the next note at the same time as this note, creating a chord. | +
If effect is not specified, no effects are applied.
+ If the note string contains an r, it is a rest and only the duration can be specified.
The play command is asynchronous: it will return immediately while the sound keeps playing in the background. If there is already sound playing on the current soundChannel, the next sound to be played will be added to a queue. The play stop form of the play command will stop playing any sound on the current soundChannel. The stop sound command will stop all currently-playing and pending sounds on all soundChannels.
Early versions of HyperTalk limited the length of the note string to 254 characters. OpenXION and later versions of HyperTalk do not limit the length of the note string.
+ In HyperTalk, the play command accepted note strings that were left unquoted, and this was often done. For example:
+play harpsichord c4 a3 f c4 a3 f c4 d c c c ++
OpenXION will also accept unquoted note strings, but this is highly discouraged. You cannot use any special symbols (such as #, ., or +) in an unquoted note string, and if one of the notes in an unquoted note string turns out to also be the name of a constant or variable, the value of the constant or the contents of the variable will be played instead of the intended note.
put expression intobeforeafter container with propertyName propertyValue
PropertyName is the name of a property.
++put "Hello" into steve ++
+put empty into it ++
+put it ++
+put "Tom" into first word of theName ++
+put "." after first character of last word of bill ++
+put steve + bill into andy ++
+put the date into myDate ++
The put command without a container specified presents the given value to the user in an implementation-defined way. OpenXION prints the given value to standard output. HyperCard puts the given value into the message box.
The put command with a container copies the given value into container. The before and after prepositions specify that the given value should be inserted before or after the existing contents, respectively, instead of completely replacing the existing contents. The with keyword allows you to set a property of the new contents.
If the specified container is a variable name but the variable has not been created yet, a new local variable is created with that name.
+ The only property HyperTalk supports for the with keyword is menuMessage.
read from object at offset for length until data
Object yields an object with an appropriate I/O manager. Offset yields an integer identifying the position where reading starts. Length yields a non-negative integer identifying the length of data to be read. Data yields the last data to be read.
+read from file "MyData" at 4 for 20 ++
+read from file "MyData" until tab ++
+read from file "MyData" at -20 until eof ++
The read command reads from the specified object, which must be opened already with the open command, into the local variable it. Reading starts at the specified offset or, if no offset is specified, from where the last read or write left off. A negative offset indicates an offset from the end of the file, while a positive offset indicates an offset from the beginning of the file. Reading continues until either the specified data is read, or the specified length of data is read, whichever occurs first. If neither is specified, reading continues until the end of a line (if the text I/O method is used) or the end of file (if the binary I/O method is used).
HyperTalk uses only the first character of data to find a stopping point. OpenXION uses the whole data.
+HyperTalk converts null characters to spaces when reading. OpenXION refuses to do such an unspeakable thing.
+set the propertyName ofin object to propertyValue
PropertyName is the name of a property.
++set the name of file "Untitled" to "MyFile" ++
+set itemDelimiter to ":" ++
The set command changes the specified property. If the object to which the property belongs is not specified, the interpreter is assumed.
Some properties cannot be changed with the set command. These exceptions are noted in the documentation for the properties themselves.
sort container direction sortType by expression
Direction is ascending or descending. The default is ascending. SortType is text, numeric, dateTime, or international. The default is text. Expression is any expression.
+sort lines of steve by last word of each ++
+sort items of bill descending numeric by word 2 of each ++
+sort lines of steve ascending ++
+sort items of bill dateTime ++
+sort andy ++
+sort it numeric ++
The sort command will sort chunks of a string, elements of a list, bytes of a binary, or child objects of an object that supports sorting.
The ascending direction sorts in normal, ascending order, while the descending direction sorts in reverse, descending order.
The text sort type sorts by the Unicode code points of the characters in a string. The international sort type sorts using the current locale's collation rules. The numeric sort type sorts strings that look like numbers as numbers rather than strings. The dateTime sort type sorts strings that look like dates as dates rather than strings.
The by keyword sorts based on the values of the expression. The item being sorted is represented by the variable each.
speak phrase with gender voicewith voice voice
Phrase and voice yield strings. Gender is male, female, or neuter.
The speak command speaks the specified phrase using a text-to-speech synthesizer. If the voice is specified, the phrase will be read using the specified voice. Otherwise, the default voice is used.
The speak command is asynchronous: it will return immediately while the speech keeps playing in the background. If there is already text being spoken, the next text to be spoken will be added to a queue. The stop speech command will stop all current and pending speech.
HyperTalk and OpenXION running under Mac OS use the speech synthesizer built in to Mac OS. OpenXION running under other platforms will use JSAPI (Java Speech API), if available. If JSAPI is not available, speak will do nothing but set the result to an error message.
stop sound
stop speech
stop tone
The stop sound command immediately stops all current and pending sound started or queued by the play command on all soundChannels. To stop sound on the current soundChannel only, use the play stop form of play.
The stop speech command immediately stops all current and pending speech started or queued by the speak command.
The stop tone command immediately stops all current and pending tones started or queued by the tone command on all toneChannels.
HyperTalk does not have a tone or stop tone command.
subtract number from container
Number yields an integer, a number, or a complex. Container yields a container containing an integer, a number, or a complex.
+subtract 2 from it ++
+subtract steve from bill ++
The subtract command subtracts the value of number from the value of container and leaves the result in container. The value in the container must be an integer, a number, or a complex and is replaced with the new value.
wait untilwhile condition
wait for number unit
Condition is an expression that always yields true or false. Number yields an integer or a number. Unit is one of the following: nanoseconds, microseconds, milliseconds, seconds, ticks, minutes, hours, nanosecond, microsecond, millisecond, second, tick, minute, or hour.
The wait command causes the interpreter to pause before executing the rest of the script. The wait until form will pause until the specified condition becomes true. The wait while form will pause until the specified condition becomes false. The wait for form will pause for the specified length of time.
If no unit is specified, the wait command assumes ticks, defined as sixtieths of a second.
The wait command causes a busy wait—the interpreter keeps running in an infinite loop, checking the specified condition or the elapsed time since the command began executing. Although you can specify a length of time as short as a nanosecond, there is absolutely no guarantee on how long the wait will actually be. The wait command cannot be used for thread synchronization or real-time applications.
HyperTalk only supports seconds, ticks, second, and tick for the unit.
write data to object at offset
Object yields an object with an appropriate I/O manager. Offset yields an integer.
+write address to file "MyFile" ++
+write "first line" & newline & "second line" to file "TwoLiner" ++
+write steve to file "MyFile" at -15 ++
The write command copies the specified data to the specified object, which must be opened already with the open command. Writing starts at the specified offset or, if no offset is specified, from where the last read or write left off. A negative offset indicates an offset from the end of the file, while a positive offset indicates an offset from the beginning of the file.
In HyperTalk, in OpenXION 1.2 or later, and according to the XION Scripting Language Standard, if you write to a file without specifying an offset and without having previously read from, written to, or truncated the file, the file will automatically get truncated before the data is written. Otherwise, the file will not be automatically truncated and any data that was not overwritten will remain.
+ OpenXION 1.0 and 1.1 did not automatically truncate files, requiring the use of the truncate command before writing to files. This was a bug, not a feature, and was fixed in OpenXION 1.2.
do script as scriptingLanguage
The do statement causes the XION interpreter to execute the specified string as an XION script. The string is executed as though it were inserted in place of the do statement.
The as scriptingLanguage form causes the XION interpreter to execute the specified string as a script in some other scripting language. HyperTalk supports AppleScript as well as any OSA-compliant scripting component. OpenXION supports AppleScript on Mac OS X, VBScript on Windows, and bash, Perl, PHP, Python, and Ruby on Mac OS X and other systems other than Windows. The XION Scripting Language Standard does not require support for any particular external language; only support for the syntax.
To execute arbitrary XION code, OpenXION's security settings must allow the DO_AND_VALUE security key. To execute code in other scripting languages, OpenXION's security settings must allow the EXTERNAL_SCRIPTS security key. If the required security key is denied, a script error will be triggered.
if condition then
statementList
else
statementList
end if
The else keyword is part of the if control structure. See the description for if for details.
In OpenXION 1.3 and later, the else keyword can also be part of the repeat control structure. See the description for repeat for details.
end structure
The end keyword marks the end of an object type, on, function, repeat, if, switch, tell, or try structure.
If an end statement is used outside its corresponding structure, a script error is triggered.
on, function, repeat, if, exit, pass
exit repeatifswitchtelltry
exit handlerName
exit to object with error errorMessage
HandlerName is the name of the handler containing the exit statement. Object yields the interpreter. ErrorMessage yields any string.
The exit statement sends control to the end of the specified structure, ending execution of the control structure. Any statements not yet executed in the specified control structure are ignored, and execution continues after the end of the control structure. The exit handlerName form ends execution of an on or function structure.
The exit to object form causes the currently executing script to stop executing. No more statements are executed after an exit to object, ever. The with error parameter allows extra information to be passed back to whatever initiated the execution of the script. OpenXION currently ignores this parameter.
If an exit statement is used outside its corresponding structure, a script error is triggered.
on, function, repeat, if, end, pass
function functionName parameterList
statementList
end functionName
The function keyword identifies a function handler. Function handlers are written to define your own functions. Functions defined with function handlers must be called using parentheses rather than the the, of, or in keywords.
When a function called functionName is evaluated, the XION interpreter checks the script of the topmost object in the hierarchy to see if it has a corresponding function handler also called functionName. If it does, the function handler executes, and the function call is sent no further (unless the script has a pass statement). If the object has no handler named functionName, the interpreter passes the function call to the next object in the hierarchy.
The statements in a handler execute until an end, exit, pass, return, or throw keyword is reached. The return value of a function handler becomes the value of the function where the function was originally called.
The optional parameterList allows the function handler to receive some values sent along with the function call. This list is a series of local variable names separated by commas, each optionally followed by a data type and/or default value:
+variableName as dataType is defaultValue
When the handler executes, each value is put into the parameter variable that appears in the corresponding position. If no value is specified for a parameter variable, the default value for that parameter variable (or empty if no default value is specified) is put into that parameter variable.
The default data type of a parameter if none is specified is string. Other data types, particularly variant, may behave in a manner incompatible with HyperTalk, but that may be desirable.
User-defined functions are always followed by parentheses. Unlike built-in functions, user-defined functions cannot be called with the, of, or in.
HyperTalk does not support as or is in the parameter list. All parameter variables in HyperTalk are implicitly declared as string with a default value of empty.
In HyperTalk, handlers may not be nested; that is, a handler may not appear in the middle of another handler. In OpenXION, handlers can be nested. The nested handlers will only be accessible from within the handler in which they appear.
+global variableList
VariableList is a series of one or more variable names separated by commas, each optionally followed by a data type and/or initial value:
+variableName as dataType is initialValue
The global keyword declares a given variable name as a global variable whose contents are available to any invocation of any handler in any object. If the variable has not already been declared or used, it is created to hold a value of the specified data type and initialized to the specified initial value. If the variable has been declared or used before, its contents remain unchanged.
Changing the value of a global variable anywhere changes its value everywhere. The global keyword must be used in each handler or script in which the global variable is used.
The following table illustrates the four different variable scopes, global, local, shared, and static:
global |
+is accessible to | +any | +invocation of | +any | +handler in | +any | +object | +
shared |
+is accessible to | +any | +invocation of | +any | +handler in | +this | +object | +
static |
+is accessible to | +any | +invocation of | +this | +handler in | +this | +object | +
local |
+is accessible to | +this | +invocation of | +this | +handler in | +this | +object | +
The default data type if none is specified is string. Other data types, particularly variant, may behave in a manner incompatible with HyperTalk, but that may be desirable.
The initial value of a variable, if not specified, is empty.
HyperTalk does not support as or is in the variable list. All variables in HyperTalk are implicitly declared as string with a default value of empty.
if condition then statement else statement
if condition
then statement else statement
if condition
then statement
else statement
if condition then
statementList
else statement
if condition then
statementList
else
statementList
end if
Condition yields true or false.
The if structure tests for the specified condition and, if the condition is true, executes the statement or series of statements that follow. If the condition is false and an else keyword is specified, the if structure executes the statement or series of statements that follow the else keyword instead.
This page describes the control structures supported by HyperTalk.
+doelseendexitfunctionglobalifnextonpassrepeatrepeat forrepeat untilrepeat whilerepeat withreturnsendthennext repeat
next case
+repeat 20 + put random(9) into tempVar + if tempVar mod 2 = 0 then next repeat + put tempVar +end repeat ++
+switch x +case 1 + next case +case 2 + next case +case 3 + put "x is 1, 2, or 3" +case 4 + put "x is 4" + next case + put "this is never printed" +case 5 + put "x is 4 or 5" +default + put "x is something else" +end switch ++
The next repeat statement sends control to the top of the next iteration of the loop. Any statements not yet executed in the current iteration are ignored.
The next case statement sends control to the next case clause of a switch structure, regardless of the value associated with the case clause. Any statements not yet executed in the current case are ignored.
If a next statement is used outside its corresponding structure, a script error is triggered.
HyperTalk does not support switch, therefore it does not support next case.
on messageName parameterList
statementList
end messageName
The on keyword identifies a message handler. Message handlers are written to define your own commands or modify or redefine what happens in response to a built-in command.
When a message called messageName is sent to an object, the XION interpreter checks that object's script to see if it has a corresponding message handler also called messageName. If it does, the object responds according to that handler, and the message is sent no further (unless the script has a pass statement). If the object has no handler named messageName, the interpreter passes the message to the next object in the hierarchy.
The statements in a handler execute until an end, exit, pass, return, or throw keyword is reached. The return value of a message handler, if any, is accessible through the built-in function result.
The optional parameterList allows the message handler to receive some values sent along with the message. This list is a series of local variable names separated by commas, each optionally followed by a data type and/or default value:
+variableName as dataType is defaultValue
When the handler executes, each value is put into the parameter variable that appears in the corresponding position. If no value is specified for a parameter variable, the default value for that parameter variable (or empty if no default value is specified) is put into that parameter variable.
The default data type of a parameter if none is specified is string. Other data types, particularly variant, may behave in a manner incompatible with HyperTalk, but that may be desirable.
HyperTalk does not support as or is in the parameter list. All parameter variables in HyperTalk are implicitly declared as string with a default value of empty.
In HyperTalk, handlers may not be nested; that is, a handler may not appear in the middle of another handler. In OpenXION, handlers can be nested. The nested handlers will only be accessible from within the handler in which they appear.
+pass handlerName
pass to object
HandlerName is the name of the handler containing the pass statement. Object yields a variant able to respond to messages.
The pass statement ends execution of the handler and sends the entire message or function call that initiated execution of the handler to the next object in the hierarchy.
The pass to form ends execution of the handler and sends the entire message or function call that initiated execution of the handler to the specified object instead. The statement pass to interpreter will send the message or function call to the interpreter, bypassing the hierarchy completely, resulting in the execution of a built-in command or the evaluation of a built-in function.
Unlike the send and tell structures, pass never returns to the handler or script containing the pass statement.
HyperTalk does not support the pass to form.
repeat forever
statementList
end repeat
repeat for number times
statementList
lastlythenelse
statementList
end repeat
Number yields a non-negative integer specifying how many times the loop is executed.
+put zero into x +repeat forever + add 1 to x + put x + if x is ten then exit repeat +end repeat ++
+put one into x +repeat 10 + put x + add 1 to x +end repeat ++
+put one into x +repeat 10 times + put x + add 1 to x +end repeat ++
The repeat structure without a number causes all the statements inside to execute in a loop until an exit, pass, return, or throw keyword is reached. The repeat structure with a number causes all the statements inside to execute in a loop with the specified number of iterations.
In OpenXION 1.3 and later, the statements under a lastly, then, or else keyword inside a repeat structure will be executed when the loop ends, unless the loop has ended because of an exit, pass, return, or throw.
repeat until, repeat while, repeat with
repeat forever
statementList
end repeat
repeat for number times
statementList
lastlythenelse
statementList
end repeat
Number yields a non-negative integer specifying how many times the loop is executed.
+put zero into x +repeat forever + add 1 to x + put x + if x is ten then exit repeat +end repeat ++
+put one into x +repeat 10 + put x + add 1 to x +end repeat ++
+put one into x +repeat 10 times + put x + add 1 to x +end repeat ++
The repeat for structure without a number causes all the statements inside to execute in a loop until an exit, pass, return, or throw keyword is reached. The repeat for structure with a number causes all the statements inside to execute in a loop with the specified number of iterations.
In OpenXION 1.3 and later, the statements under a lastly, then, or else keyword inside a repeat structure will be executed when the loop ends, unless the loop has ended because of an exit, pass, return, or throw.
repeat until, repeat while, repeat with
repeat until condition
statementList
lastlythenelse
statementList
end repeat
Condition is an expression that always yields true or false.
+put one into x +repeat until x > 10 + put x + add 1 to x +end repeat ++
The repeat until structure causes all the statements inside to execute in a loop repeated as long as the condition is false. The condition is checked following each iteration of the loop. The statements inside are executed at least once.
In OpenXION 1.3 and later, the statements under a lastly, then, or else keyword inside a repeat structure will be executed when the loop ends, unless the loop has ended because of an exit, pass, return, or throw.
repeat, repeat for, repeat while, repeat with
repeat while condition
statementList
lastlythenelse
statementList
end repeat
Condition is an expression that always yields true or false.
+put one into x +repeat while x <= 10 + put x + add 1 to x +end repeat ++
The repeat while structure causes all the statements inside to execute in a loop repeated as long as the condition is true. The condition is checked preceding each iteration of the loop. The statements inside are not executed if the condition is false at the beginning of the loop.
In OpenXION 1.3 and later, the statements under a lastly, then, or else keyword inside a repeat structure will be executed when the loop ends, unless the loop has ended because of an exit, pass, return, or throw.
repeat, repeat for, repeat until, repeat with
repeat with variable = start to finish step increment
statementList
lastlythenelse
statementList
end repeat
repeat with variable = start down todownto finish step decrement
statementList
lastlythenelse
statementList
end repeat
Variable is a variable name or an expression yielding a variable name. Start, finish, increment, and decrement yield numbers.
+repeat with x = 1 to 10 + put x +end repeat ++
The repeat with structure causes all the statements inside to execute in a loop in which variable contains the value start at the beginning of the loop and is incremented by increment (or decremented by decrement) with each iteration of the loop. Execution ends when variable contains the value finish. If no increment (or decrement) is given, it is assumed to be 1.
In OpenXION 1.3 and later, the statements under a lastly, then, or else keyword inside a repeat structure will be executed when the loop ends, unless the loop has ended because of an exit, pass, return, or throw.
Variable can be any expression as long as it yields a valid variable name. In the following example, the variable actually used is called a:
+put "a b c" into x +repeat with word 1 of x = 1 to 10 + put a +end repeat ++
HyperTalk does not support the downto keyword. Use down to instead.
HyperTalk does not support the step keyword, and only allows integer values. XION allows any real numeric value.
repeat, repeat for, repeat until, repeat while
return expression
The return statement ends execution of the handler and sets the return value of the message or function call.
When it appears within a message handler (on structure), the return statement places the value of expression into the built-in function result. The value of the result function is valid only immediately after a command executes; each new statement resets the result.
When it appears within a function handler (function structure), the return statement dictates the returned value of the function. The returned value replaces the function in the calling statement.
User-defined functions are always followed by parentheses. Unlike built-in functions, user-defined functions cannot be called with the, of, or in.
send message to object withwithout reply
Object yields a variant able to respond to messages.
The send statement sends a message directly to a particular object. Unlike the pass statement, send returns to the handler or script containing the send statement after the message has been intercepted.
To send a message to the interpreter, OpenXION's security settings must allow the DO_AND_VALUE security key. If the required security key is denied, a script error will be triggered.
if condition then
statementList
end if
The then keyword is part of the if control structure. See the description for if for details.
In OpenXION 1.3 and later, the then keyword can also be part of the repeat control structure. See the description for repeat for details.