Get Started with OpenXION

English spoken here!
OpenXION is the English-like programming language based on Apple's HyperTalk.

No Installation!
Just download, unzip, & run!

For this tutorial, I will assume that you are working with a local installation of OpenXION with the xion file in a folder named OpenXION-1.1-dist in your Home folder. For simplicity, all scripts and text files we create in this tutorial should be saved to that same folder. If you have a customized installation, are running from a USB drive, or built OpenXION from sources, please make the appropriate corrections to any path names shown here.

This is an interactive tutorial. I assume you have downloaded or installed xion and have it available to follow along with the example. But please don't feel restricted to the examples provided here. As you work through the tutorial, experiment with your own code ideas.

Let's Go!

Our first step is to open the Terminal application (a.k.a. shell, Command Prompt, xterm, konsole).  We will enter the command to change directories cd ~/OpenXION-1.1-dist Then press the return key to execute the command. If you get a "no such file or directory" error, double check your path.

From now on, I won't tell you press the return key after each line of code. Saying "execute" implies that you must press the return key to execute it.

Then execute: ls Your OpenXION-1.1.jar file should be listed.
Now execute (note that xion is all lower-case): xion You should see a single right arrow prompt like this: > You are now working inside of XION. If you ever need to quit XION, just execute exit or quit. You can open XION again anytime by following the above steps.
Let's execute our first XION command: put "Hello world" XION responds with: Hello world In programming talk, put is called a command. It has many uses, one of which is to print something to the command line. Printing to the command line is also known as the standard output.

Now let's see if XION knows math. Execute: 3 + 2 * 12 XION responds with: 27 Is that what you expected? Now try: ( 3 + 2 ) * 12 XION says: 60 What just happened? We used the same numbers but got two different answers?
All computer languages have operator precedence and order of execution rules that defines how it goes about reading and executing any line of code. In the example above(where the result was 27), we can see that the * operator has a higher precedence than +, so the multiplication was done before the addition.

Of course, we could try to learn all of these rules, but there is a much easier solution. We simply use parentheses to tell OpenXION how we want it to execute out code. OpenXION will always execute parenthesized code first.
Compare these two lines of code which use the same numbers and operators: put 3 + 30 / 2 + 1
put ( ( 3 + 30 ) / ( 2 + 1 ) ) In the second example we told xion that we wanted 3 + 30 and 2 + 1 calculated before the division took place.

Similar use of parentheses to clarify exactly how we want our code executed is used extensively in OpenXION scripting. Keep this in mind and consider using parentheses anytime you get unexpected results or if xion complains that it doesn't understand what you think is perfectly legal syntax.

Two Ways to Use OpenXION

If you execute xion from the command line like this: xion XION starts in interactive mode where you can enter commands one line at a time. This is very convenient and a good way to experiment with the language. Unfortunately, when you quit XION, it forgets everything you've done.

When working interactively, you will sometimes need to extend a line or block of code over multiple lines.
Use a single backslash ( \ ) to continue a line of code onto the following line: put "now is the time for all good men to come \
to the aid of their parties" You will note that the usual > prompt will turn into a - indicating your are continuing the statement.
Use a double backslash ( \\ ) for multi-line statements such as needed in functions, handlers, repeat loops, etc.
on doThis\\
put "hello from xion"\\
end doThis

For normal programming you will want to work in and save your programs to a script file. Script files are plain text files saved with any name you like and an .xn extension, e.g. hello.xn. Then you simply run your script in the Terminal: xion hello.xn This allows you to keep both the Terminal open, and your script file open in a text editor, and work interactively between them. Just remember to save your work in the text editor so the Terminal is executing any changes you make.

Variables

Note for experienced programmers: OpenXION variables do not require declaration or initialization prior to use and variables are not type-specific. Any variable can contain any type of data and be freely changed.

One of the most powerful features of programming languages is variables. Variables are named containers that we store values in. They are kind of like shoeboxes; we can put stuff into them and then take that stuff out and put something else in.

Variables can be named anything you like but should be limited to alpha characters and the underscore "_". Perhaps an example is worth 1000 words: Unlike other languages, OpenXION does not require you to declare variable before you use them, and variables can contain any type of data at anytime. For example: put 25 into mySuperDuperVariable
put "hello again" into mySuperDuperVariable
put the date into mySuperDuperVariable
put "joe" into aName
put "Bozo the clown" into someOtherName
put 13 into a
put 12 into b
put a + b The first line of the code above tells OpenXION to put the value 25 into the variable mySuperDuperVariable. If mySuperDuperVariable already exists, its value will now be 25. If it doesn't exist, it will be created with a value of 25. Whenever we use mySuperDuperVariable in an expression, OpenXION will know instead use the number 25. Try the following two lines of code: put 25 into myVar
put myVar + 10

If we look at lines 1, 2, and 3 in our first example, we see that we changed mySuperDuperVariable from containing a number to a text string and finally to a date. And in lines 4 & 5 we created two new variables with text. The amount of text in a variable is only limited by computer's memory.

Finally in lines 6 & 7 we create two variables containing numbers and in line 8 add them together. Had we wanted, we could create a new variable using a calculation, such as: put a + b into c

Of course, just because we can name variables anything we want doesn't mean that we should. It is best to get into the habit of using variable names that are descriptive of their contents. In an address book program, using names like firstName, lastName, and address will make your code easier to read than simply using x, y, and z.

As we progress through the tutorial, you will see how we use variables in myriad ways that really show off their power.

IT

it is a very special word in OpenXION. it is a built-in variable which always contains the results of the last executed expression. In turn, it is available for use in your scripts.
Execute these lines of code in xion to see what we mean: put 20 into a
put it
put 30 into b
put it
get a + b
put it
put it + it * it The special variable it is used extensively in OpenXION programs because it alleviates the need to create a lot of variables to hold the results of the last statement execution.

OpenXION is not Case Sensitive

In OpenXION, character case does not matter. You can name a variable MyPets and later refer to it as mypets and OpenXION will know you are talking about the same thing. Similarly, built-in functions such as appPath and dateItems are not case sensitive.

Comments

You can include comments in your code. Comments are notes, which are ignored by the OpenXION interpreter, but are often useful to remind yourself or others about the intended code logic. You can also use comments to include copyright, version info, etc. The -- operator is used to indicate a comment. Any text after -- to the end of the line is ignored by OpenXION. -- My Amazing Program
-- by John Q Coder.
-- Version 1.1, Mar 16 2010

put "Hello from John Q Coder!" -- this is a comment too In the above example, the only part of that program which will be executed is "put "Hello from John Q Coder!".

Data Types

The term data type refers to the various types of data a computer program needs to handle, e.g. numbers, dates, characters, strings, etc. In many program languages knowing and declaring data types is critically important, but in OpenXION most data type conversion are handled automatically as long as you realize that you often can't perform operations on mixed data types, for example:
    — you can't perform math operations on a mix of number and strings.
    — you can't perform date operations on strings and numbers without conversion.
Most such exemptions are common sense, but if do find the need to commingle data types, check the documentation.

Although OpenXION has many built-in data types which you should eventually explore, that knowledge won't be critical for this tutorial.

Math

OpenXION has a wide range of constants, operators and functions for mathematical computation. Some of the simplest of these are the operators shown in this example:put 2 + 2 * 2 / 2 - 2which returns 2. The operators shown are for add, multiply, divide, and subtract, respectively.

There are also words that can be used to invoke these functions, such as: put 100 into aVar
add 100 to aVar
multiply aVar by 3
divide aVar by 10
subtract 34 from aVar
sum ( 2, 4, 6 )

Constants such as pi, six, and thirteen are also defined in OpenXION, so we can do: put pi * ten / nineteen

Likewise, many functions such as abs, average, exp, and factorial are at your disposal and described in the documentation.

Output

The put command is the primary output command. Put is also used to put a value into a container (variable), such as: put ( pi * 3 * 3 ) into area but in the absence of a container, such as: put ( pi * 3 * 3 )the answer goes to the standard output (command line).

Input

Ask and answer are the two most common commands to get user input. Ask lets the user type in a text response to a question, while answer requests the user to select from the offered choices. In all cases, the user's response is place in the itvariable.

The ask command: ask "Please enter your full name"
ask password "Please enter your password:"
ask file "Save this file as:" with "Untitled-1" Other options for ask include:
    — ask password -- conceals the user's response.
    — ask file -- requests the user to enter a file
    — ask folder -- requests the user to enter a folder path
    — ask directory -- request the user to enter a directory path
May other options for using ask and answer are explained in the documentation.

The answer command: answer "What are they serving for dinner in the math lab?" with "Pi" or "log" or "root"
answer list "What is your lucky number?" with 1,2,3,4,5,6,7,8,9,10 The answer command also provides options for asking for a file, folder, directory, disk, or volume.

Commands, Statements &: Expressions

In programming, we often use the terms commands, statements, and expressions. It is important to know what these terms mean. Commands are keywords built into OpenXION that invoke actions. Put, get, open, and read are all examples of commands. Generally commands will be the first word in line of code. Expressions are similar to phrases in English. It is a group of functions, variables, and operators that evaluate to a single value. Statements are similar to sentences in English. A statement is a complete line of code that OpenXION understands and can execute.

Let's look at this example: put word 1 of line 2 of theText into myWord In this example, put is the command, word 1 of line 2 of theText is an expression because it will evaluate to a single value, and the entire line is a statement.

Scripts & Script Files

As you might imagine, programming might get pretty cumbersome if you were limited to one single script file. OpenXION lets you break your programs into as many files as you like but still treat them as if they were a single script. This is done with the include and require commands in your script file: include getDate.xn
include getFileText.xn Using the above lines in a script causes the contents of getDate.xn and getFileText.xn to be available in the current script. For example, getFileText.xn may have several functions you have written to read text files.

As you will learn shortly, handlers and functions must appear in a script before they can be used. Putting them in a separate script file and using an include statement at the top of your main script will keep your program files shorter and more manageable.

Conditional Operators

Conditional operators are similar to math operators except they compare values and return true or false. They are also called boolean operators.

Here are some of the most common conditional operators with descriptions in the comment: =     -- equals
!=    -- not equal
>     -- greater than
<     -- less than
=>    -- equal or greater than, >= works the same
=<    -- equal or less than, <= works the same
Here are some examples with explanations in the comment on each line. 5 = 5                       -- true, 5 is equal to 5
aVar = bVar                 -- true if both variables contain the same value
7 is not less than 5        -- true
10 <> 10                    -- false, 10 is not greater or less than 10
17 => 10                    -- true, 17 is equal to or greater than 10
17 =< 10                    -- false, 10 is not equal or less than 10
Many more conditional operators are available in OpenXION with English synonyms for most.

Conditional Statements

Conditional statements are offered in either an ifstructure or switch structure. There are many variations of the if statement but we will look at the three most common: if [condition] then [code to execute if true]

if [condition] then
    [code to execute if true]
end if

if [condition] then
    [code to execute if true]
else
    [code to execute if false]
end if In all of the examples above, [condition] would be replaced with any valid comparison expression, such as varA = varB or varA > varB.
Line 1 shows the single line version of the if statement. This statement is only executed if [condition] is true.
Lines 3 - 5 are exactly the same as line 1 but may be considered more readable.
Lines 7 - 11 show a full if...then...else structure where line 8 is only executed if [condition] is true and line 10 is only exectuted if [condition] is false.

The switch statement works by choosing from a list of possible matching values: switch country
  case "Great Britain"
    [some code to execute if country = Great Britain]
  case "China"
    [some code to execute if country = China]
  case "United States"
    [some code to execute if country = United States]
  default
    [some code to execute if nothing else matches]
In this case country is a variable whose contents we want to match, but it could be a number variable as well.

Loops

Note that conditional structure like if and loops like repeat can be used together. In other words, an if statement can appear in a repeat loop and vice versa.

Lists

Lists can be placed into variables just like as other data: put (1, "hello", 365.9, the date, "world") into myList As you can see, lists are enclosed in parenthese. By default, list items are separated by a comma, but you can change this by setting the itemDelimiter property.

You access items in a list using the item property. put item 4 of myList
put item 2 of myList && item 5 of myList Or find out the number of items in a list: put item 2 of myList && item 5 of myList Which brings up new possibilities. For example, if we have a list of numbers: put (88.4, 96.4, 33.954, 2) into MyNumberList
put sum(myNumberList)
put max(myNumberList) Or we can use a repeat loop to iterate through the items in a list: repeat with x = 1 to the number of items in myNumberList
    put item x of myNumberList
end repeat

Functions & Handlers

A function is a block of code that can accept parameters (a.k.a. arguments) and returns a value.
Here is a very simple function: function addNumbers a, b
    return a + b
end addNumbers You would use this function in your code as follows: put addNumbers( 10, 20 ) Of course the real power of functions is to reduce complex tasks into a single reusable functions.

Both functions and handlers must appear before the code that calls them. This is one of the reasons that handlers and functions are often put into one or more separate script files. Buy doing so, a one line include or require statement at the beginning of your main script file will load them before the remaining code that needs to call them.

The difference between a function and a handler is subtle. You call a function to return a value, but you send a message to a handler to perform some tasks and it may or may not return a value. Often which you choose is matter of which seems the most convenient and logical.

If this is confusing, here's an related example. Imagine you are in your kitchen with two children. You notice the trash can is full so you ask Johnny to empty the trash. You are also working on a recipe that calls for 237 ml of water, so you ask Mary to convert 237 ml to ounces. Metaphorically Johnny is a handler; he was given a task and is expected to carry it out without further communication. On the other hand, Mary is a function because she is given some information and expected to return a value that you need to continue your work.

Above we saw a the addNumber() function, here is how we could get the same result using an addNumber handler on addNumber a, b
    put a + b
end addNumbers You would use this function in your code as follows: addNumbers 10, 20

And finally, here is how you can use handlers to write a complete program: put "Welcome to the handler."

on main
    put "I am in main"
    processA
end main

on processA
    put "I am in processA"
    finishMe
end processA

on finishMe
    put "I am in finishMe"
end finishMe

main

put "Program completed without errors." Notice that all of the handlers appear before main calls them. This program executes as follows:
    1. the first line prints "Welcome..."
    2. all of the on handlers are noted by OpenXION but skipped until it gets to main
    3. at line 18, the main message is sent to the on main handler (line 3).
    4. main prints a line, then calls the processA handler
    5. processA (line 8) prints a line, then calls the finishMe handler
    4. finishMe (line13) prints a line after which control returns to main, which is now complete.
    4. Line 20 prints "Program completed..." and the program exits.

Reading & Writing Files

Working with external files is a three step process; open the file, read from or write to the file, then close the file. Create a plain text file in your OpenXION directory and name it text.txt. Write a sentence of text in the file and then save it.

Now from within XION, execute: open file "text.txt"
read from file "text.txt" until eof
put it
close file "text.txt"You will note that when we read the file, the contents where place into it, then the put it statement prints the contents, and we closed the file. Note that eof means "end of file" so until eof tells xion we want to read the entire file contents.

You will want to explore the many options for read that allow for reading specific parts of a file. Just remember that working with files is always a three step process; open, read or write, close. If you work with files a lot, you could create your own readFile() and writeFile functions to combine the process in a single step.

Important Note: open file looks for the specified file to open, but if the file does not exist, it creates it.

CAUTION: Depending on the syntax you use, write will not overwrite the entire contents of the file. Put the following script into a script file named "writeTest.xn" and run it with the -s allow option xion -s allow writeTest.xn. open file "writeTest.txt"
write "now is the time" && newline && "for all good men..." to file "writeTest.txt"
read from file "writeTest.txt" at 0 until eof
put "--- Version 1" & newline & it
write "edited text" to file "writeTest.txt"
read from file "writeTest.txt" at 0 until eof
put "--- Version 2" & newline & it
write "more edits" to file "writeTest.txt" at 0
read from file "writeTest.txt" at 0 until eof
put "--- Version 3" & newline & it
close file "writeTest.txt"
To completely erase a file's contents before writing, use the truncate command: open file "writetest.txt"
truncate file "writetest.txt"
-- do your thing
close file "writetest.txt"

The Value Of

You might say that we saved the best until last, becaue value is certainly an interesting and powerful feature of OpenXION. In essence, it allows you to turn any text into executable code: put "the date" into myVar
put myVar
put the value of myVar And value can also be used as a function: put "sum(16, 22, 95)" into someVar
put someVar
put value(someVar) I will leave you that to ponder the possibilities.

Congratulations!

We sincerely hope that have found this tutorial helpful and now feel ready to explore the wonderful world of OpenXION. As a graduation gift, follow this link for final bonus lesson.