a collaborative web-based
programming environment

Getting Started

This tutorial describes how to create a Cologo project, and introduces some of the features of Cologo and the Cologo gadget. If you're new to Cologo, start here.

Starting a New Project

A Cologo project is a Google Spreadsheet with the Cologo gadget installed. The easiest way to create a new project is by copying the New Project template. To make a copy of the New Project template, click this link:

Start a New Project

This creates a new Google Spreadsheet set up for a Cologo project. If you do not yet have a Google account, or are not signed in with your Google account, you will be prompted to create an account or sign in.

The Cologo Gadget

Your new Cologo project has two main components: the spreadsheet containing your program and other data, and the Cologo gadget in which your program runs.

The project workspace: the spreadsheet and the Cologo gadget

The new project template contains one procedure, called main. When the Cologo gadget is opened for the first time, it looks for a procedure called main and runs it. In fact, it has already done so: The word "Hello!" appears in the gadget because the main procedure put it there, using the print instruction.

The Cologo gadget: the canvas, the text console, the command line and the button bar

The Cologo gadget has four areas:

Clicking the "run" button tells Cologo to perform the main procedure. Click it now. The word "Hello!" appears again in the text console.

You can also type commands in the command line. Click the command line, then type the following command and press Enter:

main

The command you typed appears in the text console, followed by the word "Hello!" printed by the procedure you called. Typing main in the command line is another way to perform the main procedure.

The text console remembers previous messages that were printed. You can use the scroll bar to the left of the console to view previous messages.

Enter the following 8 commands on the command line, pressing Enter after each one:

forward 40
right 90
forward 40
right 90
forward 40
right 90
forward 40
right 90

These commands draw a picture of a square on the canvas. This is an example of "turtle graphics." Imagine an invisible creature, the "turtle," sitting in the middle of the canvas, holding a pen. When you typed forward 40, the creature moved 40 tiny steps forward, drawing a line as it moved. When you typed right 90, the creature turned 90 degrees to the right. Performing these steps 4 times drew a square.

Tip: The command line remembers the commands you have entered previously. You can recall previous commands using the up and down arrow keys while editing the command line. You can edit a recalled command, and you can press Enter to execute it.

Try one more command at the command line:

clearscreen

The turtle drawing commands have shortcuts to save typing when experimenting on the command line. Instead of forward, you can type fd. rt and lt are right and left. cs is clearscreen.

Take a moment to experiment with the turtle commands using the command line.

Procedures

The commands forward, right, left, and clearscreen are built in to Cologo. They perform the primitive operations on the environment. These operations are known as "primitives." When you enter a primitive command on the command line, the corresponding primitive operation is performed.

main is not a primitive. main is a procedure, a set of instructions defined in the spreadsheet. When you enter a procedure name on the command line, the instructions for the procedure are performed, in order. This is known as "calling" the procedure. A procedure definition can include any number of calls to primitives and procedures.

The spreadsheet can define any number of procedures, each with a unique name. The main procedure gets special treatment: As you saw earlier, it is the procedure that is called when the gadget is opened for the first time, and it is called when you click the "run" button.

Let's take those instructions for drawing a square and put them in a procedure. Click on the cell in column A row 7. Type the word "square" followed by a colon, like this: square:

Using the cursor keys, move the cursor to column B row 8, then type forward. Move one cell to the right (C8), then type "40 (that's a double-quote, followed by the number 4, then the number 0). Continue in this way until your new procedure looks like the following:

square:
forward"40
right"90
forward"40
right"90
forward"40
right"90
forward"40
right"90
end

Note: We're using the double-quote mark (") before each number due to an unfortunate behavior regarding number values and spreadsheet gadgets. We won't go into the details here. Suffice it to say that "40 is another way to represent the number 40 in a Cologo program.

The update indicatorYou may notice that as you are typing values into the spreadsheet, a little blue dot flashes in the button bar of the gadget. This is the update indicator: It flashes whenever the spreadsheet updates the gadget with the latest data.

Click on the command line. If you haven't already done so, clear the canvas by entering the command clearscreen (or cs). Now enter the command square.

square is the procedure you just created, a set of 8 instructions. When you enter its name on the command line, Cologo performs the instructions.

Procedure Arguments

The forward primitive needs to know how many steps forward to move the turtle. On the command line, we told it to move 40 steps forward by typing forward, a space, and the number 40 on the command line: forward 40 In the square procedure, we did the same thing by typing forward in one cell, and "40 in the cell immediately to the right.

The number 40 in this example is an argument, a piece of information "passed" to the primitive to tell it more about what it ought to do. Many primitives accept arguments, such as forward or right. Some primitives do not need arguments, such as clearscreen.

Procedures can also accept arguments. Our square procedure draws a square whose sides are 40 turtle steps long. Let's modify the square procedure to take the size of the side of the square as an argument.

Select the cell to the right of the square: label (column B row 7), then enter: size For each of the forward instructions, replace "40 with :size—that's a colon (:) followed by the word "size". The final procedure looks like this:

square:size
forward:size
right"90
forward:size
right"90
forward:size
right"90
forward:size
right"90
end

The word :size next to the procedure label tells Cologo that the square procedure accepts one argument, and inside the procedure definition the value of that argument is known as :size. The colon is needed so Cologo knows you are referring to the argument value, and are not trying to call a procedure named "size".

Test the new procedure by entering the following commands on the command line:

clearscreen
square 40
square 30
square 20

The result is 3 squares, each of a different size.

Now try calling the square procedure without an argument:

square

Cologo prints an error message to the text console: "Not enough arguments passed to square, expecting 1, found 0" Without an argument, the new square procedure doesn't have enough information to draw a square: It needs to know how big to make the sides.

Words and Lists

This definition for the square procedure is rather long. Since it just repeats the same two commands four times, we can make it shorter using the repeat primitive.

The repeat primitive takes 2 arguments: the number of times to repeat something, and a list of instructions to repeat. To see this in action, type the following commands on the command line:

clearscreen
repeat 4 [forward 40 right 90]

To understand this example, let's first look at the two kinds of values in Cologo: words and lists.

A word is a simple string of characters, such as Hello! or 40. A word can represent a written word or phrase, a number, or even the special values true and false for answering yes-or-no questions (also known as Boolean values).

In Cologo code, a word is represented by a double-quote mark (") followed by the characters in the word, such as: "Hello! The double-quote mark tells Cologo that this is a word value, and is not an attempt to call a procedure named "Hello!". This is known as "quoting" the value. Number values are automatically quoted, so the double-quote mark is usually optional for numbers. (We use the mark in the spreadsheet code to prevent the spreadsheet from converting non-number cell values to numbers.)

A list is an ordered collection of values. Each value in a list can be a word or another list. A list can be empty.

In Cologo code, a list is represented by values surrounded by square brackets ([ and ]). Just as the double-quote indicates a quoted word, the square brackets indicate a quoted list. Every item inside the square brackets is automatically quoted, so words in brackets that are names of procedures do not call those procedures.

Let's look at the call to repeat again:

repeat 4 [forward 40 right 90]

As we mentioned, the repeat primitive takes 2 arguments. The first argument is the word 4, automatically quoted because it is a number. The second argument is a list containing 4 words: forward, 40, right and 90.

Notice that even though the forward 40 in the list looks like a call to the forward primitive, it isn't—not yet. The repeat procedure will take this list value and tell Cologo to perform the instructions it describes. Cologo can evaluate any list as if it were code. This is especially handy for control structures like repeat, where it is useful to pass around values that represent code.

Let's rewrite the square procedure to use repeat. Click and drag the cells for the square procedure and press the Delete key to delete it. Enter the new procedure definition as follows:

square:size
repeat4[
forward:size
right"90
]
end

In the spreadsheet, the square brackets for a quoted list get their own cells.

The arrangement of the cells inside the square brackets does not matter: As long as the cells in each line of the procedure are adjacent (no empty cells between two non-empty cells), the cells that define the procedure can be arranged any way you like. This example demonstrates the use of indentation to make the code easier to understand: The content of the loop is indented one cell to the right of the repeat statement.

Test the new procedure:

clearscreen
square 40

Getting Help

This website includes complete information about the Cologo language and the gadget. For convenience, the Cologo gadget includes a pop-up help feature to access reference information about the Cologo primitives.

To open the pop-up quick reference, click the "help" button (the blue question mark ?). You can also enter the command help on the command line.

Saving and Quitting

Google Spreadsheets saves your spreadsheet automatically as you edit your document. When you are done editing, click the "Save & Close" button to make sure your last few changes are saved.

Before you do, you might want to rename this project. It is currently named "Copy of My Cologo Project." Click on this name (just below the Google Docs logo), then enter a new name when prompted.

You can return to any of your Google Spreadsheets by visiting http://docs.google.com/.

Next Steps

This has been a very brief introduction to Cologo. There are several important features of the Cologo language not described here, and there are very many more primitives beyond the ones you've seen so far.

For more information, see the rest of the documentation. If you have any questions, feel free to ask them in the discussion group.