3.1 – Lexical Conventions

Lua is a free-form language. It ignores spaces and comments between lexical elements (tokens), except as delimiters between two tokens. In source code, Lua recognizes as spaces the standard ASCII whitespace characters space, form feed, newline, carriage return, horizontal tab, and vertical tab.

Names (also called identifiers) in Lua can be any string of Latin letters, Arabic-Indic digits, and underscores, not beginning with a digit and not being a reserved word. Identifiers are used to name variables, table fields, and labels.

The following keywords are reserved and cannot be used as names:

  1.      and       break     do        else      elseif    end
  2.      false     for       function  goto      if        in
  3.      local     nil       not       or        repeat    return
  4.      then      true      until     while

Lua is a case-sensitive language: and is a reserved word, but And and AND are two different, valid names. As a convention, programs should avoid creating names that start with an underscore followed by one or more uppercase letters (such as _VERSION).

The following strings denote other tokens:

  1.      +     -     *     /     %     ^     #
  2.      &     ~     |     <<    >>    //
  3.      ==    ~=    <=    >=    <     >     =
  4.      (     )     {     }     [     ]     ::
  5.      ;     :     ,     .     ..    ...

A short literal string can be delimited by matching single or double quotes, and can contain the following C-like escape sequences: ‘\a‘ (bell), ‘\b‘ (backspace), ‘\f‘ (form feed), ‘\n‘ (newline), ‘\r‘ (carriage return), ‘\t‘ (horizontal tab), ‘\v‘ (vertical tab), ‘\\‘ (backslash), ‘\"‘ (quotation mark [double quote]), and ‘\'‘ (apostrophe [single quote]). A backslash followed by a line break results in a newline in the string. The escape sequence ‘\z‘ skips the following span of whitespace characters, including line breaks; it is particularly useful to break and indent a long literal string into multiple lines without adding the newlines and spaces into the string contents. A short literal string cannot contain unescaped line breaks nor escapes not forming a valid escape sequence.

We can specify any byte in a short literal string, including embedded zeros, by its numeric value. This can be done with the escape sequence \x*XX*, where XX is a sequence of exactly two hexadecimal digits, or with the escape sequence \*ddd*, where ddd is a sequence of up to three decimal digits. (Note that if a decimal escape sequence is to be followed by a digit, it must be expressed using exactly three digits.)

The UTF-8 encoding of a Unicode character can be inserted in a literal string with the escape sequence \u{*XXX*} (with mandatory enclosing braces), where XXX is a sequence of one or more hexadecimal digits representing the character code point. This code point can be any value less than 231. (Lua uses the original UTF-8 specification here, which is not restricted to valid Unicode code points.)

Literal strings can also be defined using a long format enclosed by long brackets. We define an opening long bracket of level n* as an opening square bracket followed by n equal signs followed by another opening square bracket. So, an opening long bracket of level 0 is written as [[, an opening long bracket of level 1 is written as [=[, and so on. A closing long bracket is defined similarly; for instance, a closing long bracket of level 4 is written as ]====]. A long literal* starts with an opening long bracket of any level and ends at the first closing long bracket of the same level. It can contain any text except a closing bracket of the same level. Literals in this bracketed form can run for several lines, do not interpret any escape sequences, and ignore long brackets of any other level. Any kind of end-of-line sequence (carriage return, newline, carriage return followed by newline, or newline followed by carriage return) is converted to a simple newline. When the opening long bracket is immediately followed by a newline, the newline is not included in the string.

As an example, in a system using ASCII (in which ‘a‘ is coded as 97, newline is coded as 10, and ‘1‘ is coded as 49), the five literal strings below denote the same string:

  1.      a = 'alo\n123"'
  2.      a = "alo\n123\""
  3.      a = '\97lo\10\04923"'
  4.      a = [[alo
  5.      123"]]
  6.      a = [==[
  7.      alo
  8.      123"]==]

Any byte in a literal string not explicitly affected by the previous rules represents itself. However, Lua opens files for parsing in text mode, and the system’s file functions may have problems with some control characters. So, it is safer to represent binary data as a quoted literal with explicit escape sequences for the non-text characters.

A numeric constant (or numeral) can be written with an optional fractional part and an optional decimal exponent, marked by a letter ‘e‘ or ‘E‘. Lua also accepts hexadecimal constants, which start with 0x or 0X. Hexadecimal constants also accept an optional fractional part plus an optional binary exponent, marked by a letter ‘p‘ or ‘P‘.

A numeric constant with a radix point or an exponent denotes a float; otherwise, if its value fits in an integer or it is a hexadecimal constant, it denotes an integer; otherwise (that is, a decimal integer numeral that overflows), it denotes a float. Hexadecimal numerals with neither a radix point nor an exponent always denote an integer value; if the value overflows, it wraps around to fit into a valid integer.

Examples of valid integer constants are

  1.      3   345   0xff   0xBEBADA

Examples of valid float constants are

  1.      3.0     3.1416     314.16e-2     0.31416E1     34e1
  2.      0x0.1E  0xA23p-4   0X1.921FB54442D18P+1

A comment starts with a double hyphen (--) anywhere outside a string. If the text immediately after -- is not an opening long bracket, the comment is a short comment, which runs until the end of the line. Otherwise, it is a long comment, which runs until the corresponding closing long bracket.