Overview

This chapter introduces the syntax of the Curl® language. It covers a number of topics, including:

Basic syntactic elements, such as Literals, Expressions, and Operators.
Structural and control elements, such as Code Blocks, Conditionals and Loops, and Procedures and Arguments.
Additional language elements such as Exceptions, Macros, and Memory Management.

Basic Syntax

This section provides an overview of some basic elements of the Curl language, including:

Text
Reserved Characters
Comments
Expressions
Verbatim Strings

Text

Summary:

The Curl® Runtime Environment displays any text that appears in the top level of a Curl language source file.
Whitespace is collapsed.
A line with no text causes subsequent text to be displayed in a new paragraph.

The simplest element in an applet written in the Curl® language is text. When you include text in a Curl applet, the browser displays that text. If you include the text without using Curl language text formats, it will be displayed in the default font and point size. It treats spaces in the same manner as HTML does, by collapsing spaces that appear between words. In other words, if a number of consecutive spaces appear between words, the spaces are collapsed and only one space is displayed in the browser. This principle of collapsing spaces also applies to tab characters and line breaks. However, if a line with no text appears in a Curl applet, the runtime stops collapsing the whitespace and creates a new line for the text that follows. This will result in a paragraph break, if more text follows.

The principle of collapsing whitespace means if you do not use Curl language text formats, the indentation and spacing that appear in a Curl applet are not displayed in the browser. The following example shows how the runtime handles text in a Curl applet. Observe also that words may be wrapped onto new lines if you resize the window.

Example: Displaying Unformatted Text in an Applet

Four score and seven years ago,
our fathers brought forth on this continent
a new nation,
conceived in liberty
and dedicated to the proposition
that all men are created equal.

Now we are engaged in a great civil war,
testing whether that nation,
or any nation so conceived and so dedicated,
can long endure.

Reserved Characters

Summary:

The reserved characters in the Curl language are: {, }, \, and |.
To use a reserved character as literal text, place the escape character (\) immediately before it.
Other escape sequences include \n for newline, \r for carriage return, \t for tab, and \ for a non-breaking space.
Use \uXXXX or \UXXXXXXXX to specify any character by its Unicode hexadecimal value.

In the Curl language, certain characters have a special meaning. For example, the Curl language uses the curly braces ({}) to enclose expressions to be evaluated. Such characters are called reserved characters. If you type a reserved character in your text, the runtime could misinterpret the text, with unintended results. The following table lists the Curl language reserved characters:

Reserved Character	Description
{	Left curly brace (Unicode 007B)
}	Right curly brace (Unicode 007D)
\	Backslash (Unicode 005C)
\|	Vertical bar (Unicode 007C)

To use a reserved character as literal text, you must place the escape character immediately before the reserved character. The backslash character (\, or reverse solidus) is the escape character. Thus the character sequences \{, \}, \|, and \\, can be used to insert left curly brace, right curly brace, vertical line, and backslash into text. For example:

Example: Using Reserved Characters in Text

To include the \{, \}, \\|, and \\ characters in text, use the \\ character to "escape" them from their special interpretation.

Be careful not to include a space between the escape character and the reserved character. If you do, the runtime will interpret the escape character plus the following space as a special character combination, instead of associating the escape character with the reserved character that follows the space. (An escaped space character is interpreted as a "hard" space that is not collapsed with other whitespace when it is displayed; it can also be placed between two words to prevent a line break.)

You can also use the escape character (\) to indicate characters that do not appear on the keyboard. The following table lists some useful escape sequences. (For a complete list of escape sequences, see the Character Literals section.)

Escape Sequence	Description
\n	Newline character
\r	Carriage return character
\t	Tab character
\ (blank space)	Non-breaking space character
\{	Left curly brace character
\}	Right curly brace character
\\	Backslash character
\\|	Vertical bar character
\uXXXX	Any character, where XXXX is the Unicode hexadecimal value of the character. Unicode values greater than 0xFFFF cannot be represented using this sequence.
\UXXXXXXXX	Any character, where XXXXXXXX is the Unicode hexadecimal value of the character.

You can use Unicode escape sequences to display any character or symbol included in the fonts installed on the end-user's computer. For example:

Example: Using Unicode Escape Sequences

'\u0041' should be the same as 'A'.

See the Code Charts section of the Unicode Consortium website for the Unicode values of many classes of special characters and symbols.

Comments

Summary:

The Curl language provides four types of comments:

End-of-line comments: All text between || and the end of the line is treated as a single-line comment.
Multi-line comments: All text between |# and #| is treated as a comment.
Tagged comments: All text between |tag-name# and #tag-name| is treated as a comment.
Length-specified comments: The number of characters in a comment can be used in place of a tag-name to enclose a sequence of totally arbitrary characters.

A comment is text that the Curl® Runtime Environment (RTE) does not interpret and does not display. The text of a comment appears only in the Curl language source file. Comments are useful for including information of interest to the person that is working on the file. There are a number of ways of indicating comments in the Curl language.

End-of-line Comments

The simplest form of comment begins with two successive vertical bars (||) and terminates at the end of the current line, without including the newline character. You can use this type of comment to include information on a line by itself or at the end of a line of code. These end-of-line comments (also known as trailing comments) have the following syntax:

|| comment-text

where comment-text is the text of the comment. For example:

Example: Using End-of-line Comments

A comment can be on a line by itself, \|\| A comment on a line by itself or it can be at the end \|\| A comment on the same line as code of a line.

The characters that signify the end of the line are not part of the comment. You should be aware of this when you include a comment in text. In text without markup, you can use a blank line to create a new paragraph of text. If the blank line or the preceding line contains a comment, the characters that signify the end of the line are not part of the comment and count toward creating the necessary blank line for a new paragraph. This is illustrated in the example shown above.

Multi-line Comments

Another form of comment begins with a vertical bar followed by a number symbol (|#) and terminates with a number symbol followed by a vertical bar (#|). This form of comment is called a multi-line comment because it makes it easy to include multiple lines of information in one comment. However, you can also use this type of comment to include a comment in the middle of a line of code. These comments use the following syntax:

|# comment-text #|

where comment-text is the text of the comment. For example:

Example: Using Multi-line Comments

A comment can be \|# Here is a comment #\| placed within a line of code, \|# A comment that spans multiple lines #\| or it can span multiple lines.

Note that this form of the comment consumes only the characters between |# and #|. It does not consume the characters that signify the end of the line. This means that, in the example above, there are end-of-line characters at the ends of the first and seventh lines of code. This, in turn, means that there is a paragraph break between the display of the first and eighth lines.

A common use of multi-line comments is to comment out an existing section of code by enclosing it within a comment. The process of commenting out code is commonly used by developers. You can comment out code to temporarily remove the code from the file. This is particularly useful when debugging code. For example, one of the arguments in the following function call is commented out:

{foo |#arg1=val1,#| arg2=val2}

And, in the following code, an entire procedure declaration, including a || comment, is commented out:

|#
    || A procedure that indicates if two arguments are equal.
    {define-proc public foo {arg1:any=val1, arg2:any=val2}:bool
        {return arg1 == arg2}
    }
#|

Tagged Comments

A third form of comment has the following syntax:

Syntax:

|tag-name# comment-text #tag-name|

where:

tag-name	is a valid Curl language identifier.
comment-text	is the text of the comment.

|tag-name# comment-text #tag-name|

Valid identifiers can be of any length, must begin with either a letter or an underscore, and may contain only letters, digits, hyphens (-), underscores (_), and question marks (?). (See the Identifiers section for more information about Curl identifiers and naming conventions.)

This form of comment is most useful when you want to comment out a section of source code that might itself include shorter comments of any type. By using a unique new tag, you avoid the risk of your comment terminating abruptly because a different end-of-comment sequence is encountered earlier.

For example:

Example: Using Tagged Comments

This text surrounds a tagged comment
|test#
    Here is an end-of-line comment: || END-OF-LINE COMMENT

    Here is a comment that |# MULTILINE
    COMMENT #| spans multiple lines.

    And here |other-tag# ANOTHER TAGGED COMMENT #other-tag| is
    a tagged comment with a different tag.
#test|
that itself contains assorted comments.

Length-specified Comments

If a comment is automatically generated and might contain arbitrary characters, you may not be able to guarantee that any pre-chosen tag can be used to terminate every possible comment. By using a length-specified comment, you avoid having to write code that scans automatically-generated comments for unexpected closing comment character sequences.

In a length-specified comment, the opening and closing comment symbols specify the number of characters in the comment, as shown below:

Syntax:

|num-chars# comment-text #num-chars|

where:

num-chars	is the number of characters in the comment, not including the character sequences that open and close the comment.
comment-text	is the text of the comment.

For example:

Example: Using a Length-Specified Comment

Here is some text \|20# please#\|&#@\|ignore #20\| surrounding a length-specified comment.

In practice, if the content of the comment is generated by the computer at run time, you would also use the computer to count up the number of characters.

Expressions

Summary:

Expressions are essentially the Curl language commands.
Most expressions are surrounded by { and }.
When the runtime encounters an expression, it evaluates the expression.
The RTE evaluates all subexpressions in the expression in order, from left to right.
Most expressions produce a value.
The value produced by a top-level expression is displayed in the browser.

Expressions are essentially the Curl language commands. Much of the remainder of this guide describes the various types of expressions that you can include in your files. Most expressions in the Curl language are surrounded by the left curly brace ({) and the right curly brace (}) characters.

The number of curly braces surrounding an expression indicates the level of the code. An expression in a Curl language source file that is not contained within another expression is considered to be a top-level expression. For example, a procedure definition is a top-level expression. An expression within a top-level expression is not a top-level expression; it is one level deeper. For example, a local variable declaration within a procedure is not top-level code. If a top-level expression produces a value, that value is displayed in the browser. The following code shows some expressions:

|| Text...
This is some text.

|| The variable definition (that is, the let expression)
|| is top-level code.  The VBox instantiation is not
|| top-level code because it is an expression within
|| the curly braces for the let expression.
{let my-box:VBox = {VBox "Hello "}}

|| The procedure definition is top-level code.
{define-proc {my-procedure}:void
    || However, the code in the procedure definition
    || is not top-level code.  It is one level deeper.
    {my-box.add "World"}
}

|| Text with some top-level code.  The value expression
|| is top-level code.
The first public release of the Curl language was in the year {value x}.

The following example includes a comment, some text, and a Curl language expression. The expression in this example is a call to the sqrt procedure. (Like many programming languages, the Curl language includes many convenient features, such as the sqrt procedure.) The sqrt procedure takes a value that you supply and returns the square root of that value.

Example: How Expressions are Interpreted

\|\| Calling a built-in math procedure The square root of 4 is {sqrt 4}.

In an expression in braces, the name of the procedure must immediately follow the left curly brace. The value or values that you supply to the procedure follow the name of the procedure, and the right curly brace indicates the end of the expression. When the runtime encounters the expression in this example, it calls the sqrt procedure, passing the value supplied to the procedure. The RTE evaluates all subexpressions in the expression in order, from left to right. It then displays the value that the procedure returns. In general, when the runtime encounters a top-level expression, it evaluates the expression and displays the value of the expression.

The following example uses a Curl language expression that formats text. The bold text format displays text in boldface. In this expression, the name of the text format immediately follows the left curly brace. The text to which you want to apply the text format appears between the name of the text format and the right curly brace. When the runtime encounters this expression, the compiler displays the text with the desired formatting applied.

Example: Using a Curl Language Expression to Format Text

\|\| Text that includes a text format. Here is some {bold bold} text.

To find more information about text format expressions, including an introductory tutorial, see the Text Formatting.

Using Variables

Summary:

Use a let expression to create a variable and assign an initial value to it.
Use a set expression to assign a new value to an existing variable.
let and set expressions do not produce values.

In your files, you will often want to create variables. A variable is a way to store a value in memory. Each variable has a name that you can use to access its value or to assign a new value to it. To create a variable and give it an initial value, you use a let expression:

{let x = 13}  || x is a new variable with the value 13

You can also change the value of a variable, using the set expression:

{set x = 200}  || now the value of x is 200

See the section on Variables for a much more detailed discussion of Curl language variables.

Using value and do Expressions

Summary:

value executes one or more Curl language expressions and produces the value of the last expression, if any.
do executes one or more of Curl language expressions, but does not produce a value.
let and set expressions within value and do expressions do not need curly braces around them.

When you want to display the value of a variable within text, you cannot simply use the name of the variable, because the RTE treats the variable name as additional text and just displays the name, not its value. To obtain the value of a variable, use the value expression:

Example: Using value to Display a Variable

|| Define a variable called current-floor and give it an
|| initial value of 13.
{let current-floor = 13}

|| If you do not use the {value ...} expression, the runtime
|| interprets the variable name as text.
current-floor

|| If you use a top-level {value ...} expression, the
|| value of the variable is displayed.
{value current-floor}

A value expression can also include more than one Curl language expression. By convention, each subexpression starts on a new line. The value expression executes each of its subexpressions in order and produces the value of the last one. For example:

Example: Using value with a Sequence of Expressions

{value
    || Define a variable called current-floor and give it
    || an initial value of 13.
    let current-floor = 13

    || Add one to the value of current-floor.
    set current-floor = current-floor + 1

    || Note that this value is not displayed because it is
    || not the last expression in the value expression.
    current-floor

    || Add one more to the value of current-floor.
    set current-floor = current-floor + 1

    || Display the value of current-floor.
    current-floor
}

A do expression is like a value expression in that it can contain a sequence of one or more Curl language expressions to be evaluated, one after another. We call such a sequence of expressions a block of code, or a code block.

Unlike a value expression, however, a do expression does not produce any value. Therefore, you would use it to execute a sequence of subexpressions when the last subexpression does not produce any value that you want to have displayed.

Example: Using do

{do || try changing this to "value" instead

    || Define a variable called current-floor with
    || an initial value of 13.
    let current-floor = 13

    || Add one to the value of current-floor.
    set current-floor = current-floor + 1

    || Add one more to the value of current-floor.
    set current-floor = current-floor + 1

    || This expression produces the new value of current-floor,
    || but it will not be displayed unless you change the
    || outer expression to be a "value" expression.
    current-floor
}
|| Uncommenting the following line will cause an error, since
|| the variable current-floor is undefined outside of its block.
|| {value current-floor}

However, if you create a variable in a code block as in the example above, it will only be preserved in memory for the duration of that block. So you cannot display its value in later top-level code or in another code block. You can test this rule as well in the example above.

In the previous two examples, the lines

let current-floor = 13

and

set current-floor = current-floor + 1

weren't enclosed in curly braces, although it would not have been an error to do so. Definition and assignment expressions using let and set, which occur very frequently in Curl source code and do not produce a value, follow a special rule of Curl syntax: any let or set statement inside a code block does not have to be enclosed in curly braces. In top-level text, however, the curly braces are always required; without them, let and set expressions would be displayed as text instead of being evaluated.

See the section on Code Blocks for more information about code blocks.

Operator Expressions

Summary:

The usual arithmetic operators, including parentheses, can be used in Curl language source code.
Operator expressions always produce a value.
Operator expressions are never enclosed in curly braces.
The value of an operator expression can be displayed in top-level text by including it in a value expression.

Operations in the Curl language such as addition, subtraction, multiplication, and division, are indicated with the usual operator symbols +, -, *, and /, written between two expressions representing the values to be operated on. Parentheses can be used to control the order in which components of complex operator expressions are evaluated, as shown below:

(3 + 4) * (8 - 5)

In the example above, a space has been left blank on either side of each arithmetic operator. This is the recommended style. When the symbol - is used to subtract two expressions, surrounding spaces are required, because the same symbol '-' in different contents may represent either subtraction, negation, or a hyphen within a variable name:

10 - 3  || subtraction operation whose value is 7
10 -3   || two numbers evaluated, last value is -3
10-3    || two numbers evaluated, last value is -3
10- 3   || causes a syntax error
a-b     || causes a syntax error if no variable "a-b" is defined

Each operator expression produces a value, but arithmetic expressions should never be enclosed in curly braces as Curl prefix expressions are. For example:

sum1 - sum2    || is a legal arithmetic expression
{sum1 - sum2}  || is not a legal arithmetic expression

However, if an operator expression appears in top-level source code, it will be treated as text to be displayed rather than as an operation to be performed. If you want to evaluate an operator expression and display the result within top-level text, you can enclose it in a value expression. For example:

Example: Evaluating an Operator Expression in Top-level Text

The value of 2 * 1024 is {value 2 * 1024}.

You can also include an operator expression as the last expression in a top-level value block in an applet. Only the result of the last expression in the block will be displayed, as shown in the following example:

Example: Evaluating an Operator Expression within a Code Block

{value \|\| Define four variables, each with an initial value. let a = 5 let b = 1 let c = 4 let d = 2 \|\| Compute and display the following value: (a * d) - (b * c) }

See the section on Operators for a detailed survey of Curl language operators.

Verbatim Strings

Summary:

Use verbatim strings for text that the runtime does not interpret.
Within top-level code, the runtime displays the contents of the verbatim string without interpretation.
Within a text format, the runtime displays the contents of the verbatim string without interpretation and applies the text format.
Within code, the runtime treats the verbatim string as a string of characters.

The Curl runtime normally interprets all expressions in curly braces and special character sequences in Curl language source files, even in ordinary or quoted text. For example:

Example: Curl Expressions are Evaluated within Text and Quoted Strings

Curly braces signal expressions to be {italic interpreted},
even within quotation marks:
"Act now! {bold deeds are called for}"

You can use escape characters (\\) to change how individual characters
are interpreted, but the escape sequences are still displayed differently
than they are written:
"Act now! \{bold deeds are called for\}"

If you want to include text in a Curl source file that should not be interpreted by the runtime, you can use a verbatim string.

Verbatim strings contain text that the runtime does not interpret. That is, the runtime does not check for reserved characters or expressions in verbatim strings. In some programming languages, verbatim strings are referred to as raw text or superliteral strings. A special character sequence must surround a verbatim string. Within a verbatim string, the only character sequence that the runtime checks for is the special character sequence that ends the verbatim string. There are three types of verbatim strings in the Curl language:

Regular Verbatim Strings
Tagged Verbatim Strings
Length-specified Verbatim Strings

Regular Verbatim Strings

Regular verbatim strings have the following syntax:

|" text "|

where text is the text of the verbatim string. The following example shows how reserved characters in a verbatim string are not interpreted:

Example: Reserved Characters in a Verbatim String Are Not Interpreted

\|"To include the {, }, \|, and \ characters in text, use the \ character to "escape" them from their special interpretation."\|

And the following example shows how expressions (actually, text formats in this case) in a verbatim string are not interpreted:

Example: Expressions in a Verbatim String Are Not Interpreted

\|"{tiny If you have the winning number, we'll say} You have won {big color="red", one million dollars!}"\|

Tagged Verbatim Strings

To include the character sequences that denote regular verbatim strings within a verbatim string (that is, to include |" or "| within a verbatim string), use a tagged verbatim string. Tagged verbatim strings have the following syntax:

|tag-name" text "tag-name|

where tag-name is a valid Curl language identifier and text is the text of the verbatim string, possibly containing another verbatim string. (For information about valid Curl language identifiers, see the Identifiers section.) For example:

Example: Using Tagged Verbatim Strings

\|test"Check out the following verbatim string... \|"To include the {, }, \|, and \ characters in text, use the \ character to "escape" them from their special interpretation."\|"test\|

Length-specified Verbatim Strings

If you are using code to generate verbatim strings automatically, it might be more convenient to use length-specified verbatim strings. In a length-specified verbatim string, you specify the number of characters in the verbatim string. By using a length-specified verbatim string, you avoid having to write code that scans automatically-generated verbatim strings for unexpected closing verbatim string character sequences. Length-specified verbatim strings have the following syntax:

|num-chars" text "num-chars|

where num-chars is the number of characters in the verbatim string and text is the text of the verbatim string. num-chars does not include the character sequences that open and close the verbatim string. For example:

Example: Using Length-specified Verbatim Strings

\|15"{ \ \| ( ) \| ? }"15\|

Using Verbatim Strings

A text format is a special type of expression that allows you to display and format text. If you use a verbatim string within a text format, the contents of the verbatim string are formatted for display, without being interpreted. For example:

Example: Using a Verbatim String in a Text Format

{bold \|" {italic Here is a bold {italic verbatim} string. } "\|}

The example above also shows that when verbatim text is displayed, extra space between words or paragraphs is collapsed and words are wrapped between lines as in ordinary text. See the section More about pre to learn how to preserve whitespace and line breaks in text, independently of suspending interpretation by the runtime.

If you use a verbatim string within code, the runtime treats the verbatim string as it treats a string of characters, except that it does not interpret the characters.

Example: Using a Verbatim String within Code

|| Define a procedure that takes a string of characters
|| and returns the string.
{define-proc {display-string x:String}:String
    {return x}
}

|| Call the procedure for a verbatim string.
{display-string |"{italic verbatim}"|}

Copyright © 1998-2019 SCSK Corporation. All rights reserved.
Curl, the Curl logo, Surge, and the Surge logo are trademarks of SCSK Corporation. that are registered in the United States. Surge Lab, the Surge Lab logo, and the Surge Lab Visual Layout Editor (VLE) logo are trademarks of SCSK Corporation.