KL literal text

Sometimes when writing a program, it is necessary to include a piece of text that the program will use. The program might display the piece of text to the user, or store it in a file, or send it across a network, or some other action. The piece of text can be written directly into the source code by enclosing it in double quotation marks, for example:

```
"Hello, world!"

```

The quotation marks are not included in the actual/produced text. Text in double quotation marks is equivalent to a variable of the following type, a read-only reference to read-only constant-size text ("read-only" means capable of being read/used but not modified). "n" represents the size of the text (the size is related to the number of characters in the text).

```
ReadOnly[Ref[ReadOnly[ConstantSize[TText, n]]]]

```

Because the quoted text acts as a read-only text variable, the quoted text can be used with commands that accept text variables. For example, consider the "MText.Set" command. It sets the contents/value of a text variable to whatever text you want. It has 2 parameters. Both parameters are references to text variables.

The first parameter is the text variable to set, and the second parameter is some other text variable that the first text variable should be set to. In other words, the first parameter is the destination text variable, and the second parameter is the source text variable, and the source is copied into the destination. The type of the second parameter is:

```
Ref[ReadOnly[TText]]

```

And that type is compatible with the aforementioned type of quoted text. Therefore, it is possible to do the following:

```
var message, TText;
var greeting, TText;
MText.Set message, "Hello, world!";
MText.Set greeting, message;

```

Note how the quoted text is behaving like a read-only variable containing text.

In some other programming languages, the name "string" is used to mean text. In KL, the name "string" is NOT used. Using the name "string" for text does not make much sense. Call it what it is! Therefore in KL a variable containing text is called a text variable, not a string variable.

## Specifying Characters by Name

You might wonder, considering that a piece of text in the source code is required to be enclosed in quotation marks, what happens if you want a quotation mark to appear in the text? It is possible to do this, but the quotation mark in the text cannot be written directly (because a quotation mark would cause the compiler to end the quoted text sequence). Instead the quotation mark must be specified by name, not written directly.

In the following example, the compiler will replace each <quot> with a quotation mark character:

```
"Delete the file <quot>Bestiality.mpg<quot> permanently?"

```

Other characters can also be specified by name, such as the ampersand character (a character name listing is provided further ahead). The following 2 examples produce exactly the same text:

```
"Smith <amp> Wesson"
"Smith & Wesson"

```

The character names are case-sensitive. For example, "<AMP>" is invalid (there is a character named "amp" but no character named "AMP"). Also note that some characters exist in 2 versions, an uppercase version, and a lowercase version, and both versions have the same character name except with different capitalization. For example, <agrave> produces the lowercase "a" with grave mark (à), while <Agrave> produces the uppercase "A" with grave mark (À).

If you use a character name that is unknown to the compiler, the compiler will display an error message telling you that it does not recognize the character name. The following examples are all invalid:

```
"Invalid <nachos> character"
"Invalid <foo  bar> character"
"Empty char name <> test"
"Empty char name < > test"

```

The following characters cannot appear literally/directly in a quoted text sequence, because they would make the source code confusing, ambiguous, unreliable, or disruptive to the compiler. If you want one of these characters to be included in the produced text, you must specify it by name not literally.

The apostrophe character (also known as single quotation mark) can appear literally in a quoted text sequence enclosed in double quotation marks, without having to specify it by name. For example:

```
"Sorry I'm late, I'll leave early to make up for it."

```

Quoted text cannot directly include a line break in the source code. For example, the following is invalid:

```
"First line
Second line"

```

Instead the line break must be specified by name:

```
"First line<br>Second line"

```

Or using the concatenation feature (described ahead):

```
"First line<br>"
"Second line"

```

Concatenation

If there are multiple quoted text sequences with nothing between them other than whitespace, they are concatenated together with NO extra characters inserted between (the whitespace is ignored). For example:

```
"test" "ing"

```

Is equivalent to:

```
"testing"

```

Another example:

```
"pine"
"apple"

```

Is equivalent to:

```
"pineapple"

```

NOT to:

```
"pine<br>apple"

```

The main purpose of this concatenation feature is to allow long pieces of text to be written on multiple lines, without including those line breaks in the produced text, and without introducing ambiguity as to whether line breaks are to be included in the produced text. For example, a long paragraph can be written on multiple lines using this concatenation feature. This is useful to avoid a ridiculously long line when the source code is being displayed/edited in a text editor that is not using soft-wrapping.

Whitespace characters can be normal space, line break, or tab. The number of whitespace characters between the quoted text sequences can be zero or more.

## Comments in Quoted Text

The following is invalid, and is rejected by the compiler:

```
"test{comment}text"

```

Following is a valid way of having a comment inside quoted text, utilizing the aforementioned concatenation feature. 1 or more comments can appear between the quoted text sequences (with or without whitespace) without disrupting the concatenation.

```
"test"{comment}"text"

```

That is equivalent to:

```
"testtext"

```

Or if you wanted the curly brackets included in the produced text, then specify the curly bracket characters by name:

```
"test<lcbra>comment<rcbra>text"

```

Specifying Characters by Number

In a quoted text sequence in source code, characters can be specified literally, by name, or by number. Only some characters can be specified by name, and only some literally, but all can be specified by number. The following 3 examples produce exactly the same text:

```
"Smith <amp> Wesson"  {by name}
"Smith <#26> Wesson"  {by number}
"Smith & Wesson"      {literally}

```

To specify a character by number, it is the same as specifying a character by name except replace the name with a hash (#) followed by the Unicode number of the character in hexadecimal, with or without leading zeros. Only hexadecimal digits (0-9,A-F,a-f) are permitted after the hash (#). The number must have a minimum of 1 hexadecimal digit and a maximum of 8 hexadecimal digits (32 bits) including leading zero digits.

The following 2 examples produce exactly the same text, containing the Greek capital letter Omega:

```
"<Omega> watches are low-tech antiques."
"<#03A9> watches are low-tech antiques."

```

Usually characters are specified by name in preference to number, but if the compiler does not have a name for the desired character, then it must be specified by number instead.

Note that <#A9> (for example) does NOT mean insert a byte (8 bits) containing the value 0xA9. Rather it means insert the Unicode character number 0xA9 (in this case, 0xA9 is the Copyright character). The quoted text sequence "<#A9>" actually produces text 2 bytes in size, because in both the Unicode UTF8 and UTF16 text encodings, the Unicode character number 0xA9 is encoded using 2 bytes.

When a character is specified by number, the compiler inserts the character regardless of whether any actual character/symbol is assigned to that number (defined for that number) in the Unicode standard, and regardless of whether any font contains graphics for that character number.

The "null" character (character number zero) can be inserted using <#0>. Text variables are NOT null-terminated, therefore the presence of a null character in a text variable has no special effect. However, the text containing a null character might disrupt a program written in a programming language that does use null-termination (such as C/C++), if the text is transmitted/conveyed to that program.

## Literal Character Listing

Following is a complete listing of all characters that can appear literally/directly in a quoted text sequence in source code stored in a plain text file. Literally/directly meaning without specifying the character by name or number. All other Unicode characters (including latin alphabet characters with diacritical marks) must be specified by name or number.

## Character Name Listing

The following table lists all valid character names that can be used in KL source code. The "Number" column is the Unicode number of the character, in hexadecimal. All the character names are adopted from the HTML4 standard, except for the characters marked with "Not HTML".

All the character numbers are adopted from the Unicode standard. Unicode allows computers to consistently represent and exchange text in any of the world's writing systems and languages. Unicode defines more than 100 000 different characters, providing a standardized digital representation for each.