Lingo in a Nutshell

Lingo’s Skeletal Structure

This section covers the bones on which you’ll hang the flesh of your Lingo program. A handful of Lingo commands and functions control program structure and execution. Each line of Lingo is executed in order, unless the Lingo itself changes the flow. Lingo detours to execute any handler names it encounters, as shown in detail under "Nested Handlers" in the earlier section, "Handlers and Scripts.” A detour taken to execute another handler is known as a subroutine call in most languages. Refer to Chapter 1, How Director Works in Director in a Nutshell regarding the difference between Lingo’s program flow and the movement of the Score’s playback head.

Comments

Although Lingo tells Director what to do, the Lingo code is ultimately written and maintained by humans (or programmers, anyway). Lines starting with two hyphens (--) are comments that Director ignores; they do not increase the execution time. Adding comments to someone else’s code is a great way to make sure you understand what it does.

I place comments before the code they describe, although some people place them afterward, which seems patently absurd to me. Comments should give a preview, not a postmortem.

Always describe the big picture:

Include comments at the top of your handler to describe its purpose. Describe what the handler does and why. Describe the data stored in major variables, such as lists, and which global variables the code uses.

Use comments liberally, even when you are the only programmer:

Your own comments will help you immensely if you have to fix a bug six months later, or they’ll help the next poor slob who has to maintain your code when you take a better job.

Write comments that complement, not simply reiterate, the programming code:

Your comments should explain what the code is doing at the conceptual level, not the syntactical level. A comment such as "Set x to zero" is useless. Use informative comments like "Reset the user’s game score.” Assume that the person reading your comments understands Lingo’s basic operation. Don’t document how Lingo itself works; document what your code accomplishes.

“Comment out” temporary changes or tests:

gComments can exist on separate lines or at the end of a line following other Lingo commands. Anything following a comment character will be ignored until the next carriage return. Lingo does not have a way to create multiline comments, as in C, but you can use the continuation character or use more double-hyphens on subsequent lines.

Example 1-17. Comments

-- This is a Lingo comment on its own line

set x = 1 -- This is a Lingo comment at the end of a line-- Here's a "commented out" command that is ignored
-- set x = 1

-- To create a multiline comment in Lingo,-- begin each line with its own comment delimiter
--
-- This is a multiline comment by virtue of the ¬,continuation character at the end of the previous line-- Beware!  The last line is part of the comment-- by virtue of the continuation character ¬
set x = 1

This example demonstrates appropriate comments.

on resetHighScores
   -- This handler clears the high score chart
  global gHighScoreList

   -- Reset the list holding the top scores
    -- and the winners' names
  deleteAll gHighScoreList

  -- Clear the on-screen high score winners chart
  set the text of field "HighScore" = EMPTY

  -- Reset the sprites displaying the highest score
  repeat with i = 12 to 20
    set the member of sprite i = member "BigZero"
  end repeat
end

To comment or uncomment your code:

Manually add or delete two hyphens (--) at the beginning of one or more lines of code.

Use the Comment and Uncomment buttons in the Script window’s button bar (see Figure 3-3) to comment or uncomment the currently highlighted line(s).

Use Cmd-Shift-> and Cmd-Shift-< (Mac) or Ctrl-Shift-> and Ctrl-Shift-< (Windows) to comment or uncomment the currently highlighted line(s). (These are available under Director 4’s Text menu.) Use the Comment and Uncomment options under the context-sensitive pop-up menu in the Script Window, Ctrl-click (Mac) or right click (Windows).

Tip

A good rule of thumb is one comment for every three lines of Lingo code. Use self-explanatory variable, symbol, and handler names to improve your code’s readability.

You can use the Lingo command nothing as a placeholder when you don’t want to execute any commands. Unfortunately, unlike comments nothing takes time for Lingo to “execute.”

Multi-line Code Structures

Lingo commands generally occupy a single line (that is, they end when a carriage return is encountered), but Table 1-3 shows Lingo statements that occupy more than one line. Each multi-line command begins with its own special keyword and is terminated by some variation of the end keyword. Director automatically indents the statements within the body of a multi-line command two additional spaces. If the indentation is wrong, something is wrong with your Lingo. The Lingo continuation character ¬ should only be used to break long lines, not to “join” the multiple lines that are part of a multi-line structure itself.

Tip

The multi-line code fragments shown as examples must be incorporated into a handler for testing; they will not work from the Message window.

Table 1-3. Multi-line Code Structures

Structure	Usage
[a]
[b]
[c]
[d]
¬ Created with Option-Return (Mac) or Alt-Enter (Windows)	Continues Lingo onto next line.
on handlerName{parameter1,parameter2,...} statements end {handlerName}[a]	Handler declaration.
if expression then statements else if expression then statements else statements end if	Executes Lingo conditionally depending if expression is TRUE or FALSE. See "If...Then Statements" later in this chapter and see Chapter 5, Data Types and Expressions.
case (expression) of value1: statements value2, value3: statements otherwise: statements end case	Executes Lingo when an expression matches one of the specified values (see "Case Statement" later in this chapter)
beginRecording statements endRecording[b]	Score recording.[c]
tell statements end tell	Window messaging.[d]
repeat while expression statements end repeat	Repeats until expression becomes FALSE
repeat with item in list statements end repeat	Cycles once through all the items in a list.
repeat with index = start to end statements end repeat	Repeats for a range of values increasing by 1.
repeat with index = last down to first statements end repeat	Repeats for a range of values decreasing by 1.
[a] 1 The handlerName following the end keyword is optional. Include it especially when concluding long handlers whose entirety is not visible in the Script window. [b] 2 Note that endRecording is one word whereas the other end commands are two words. [c] 3 See Chapter 3, The Score and Animation, in Director in a Nutshell. [d] 4 See Chapter 6, The Stage and Movies-in-a-Window, in Director in a Nutshell.

Common Handler Declaration Errors

All handlers start with the keyword on, followed by the handler name, and end with the keyword end. A script can contain multiple handlers, one after the other. Always end one handler before beginning the next one. Let Director’s auto-indentation be your guide.

Example 1-18. Handler Declarations

This is wrong:

on mouseUp
  statements

on mouseDown
   statements
end

This is right:

on mouseUp
   statements
end mouseUp

on mouseDown
   statements
end mouseDown

Note the optional use of the handler name after the end keyword. This is useful for making sure that you always have a matching end handlerName statement for each on handlerName statement. A handler declaration can also include parameters (not shown). Refer to "Parameters and Arguments" later in this chapter.

Common Multi-Line Structure Errors

Always terminate nested multiline structures from the inside out, as with nested parentheses.

Note the incorrect indentation in Example 1-19 caused by the end if incorrectly preceding the end repeat, and note how the multi-line structures incorrectly cross, rather than nest.

Example 1-19. Nested Multi-Line Structure Errors

Note the corrected indentation, and see how the multi-line structures nest neatly, rather than cross.:

Don’t use a continuation character ¬ improperly at the end of a line. Director automatically knows that the multiline command continues on the next line.

The following is wrong. You should not use the ¬ character in this case:

repeat with x = 1 to 7 ¬
  puppetSprite x, TRUE
end repeat

Here is an example of correctly using an ¬ character within the body of a multiline code structure to break a long line of Lingo.

repeat with x = 1 to 7
  set the member of sprite x = ¬
  member "Pinky and the Brain" of castLib "World Domination"
end repeat