Lexical Structure

Defined elsewhere

• boolean-literal
• floating-literal
• integer-literal
• null-literal
• string-literal

Boolean Literals

Syntax

  boolean-literal::
    true
    false

Semantics

The type of a boolean-literal is bool. The values true and false represent the Boolean values True and False, respectively.

Examples

$done = false;
computeValues($table, true);

Integer Literals

Syntax

  integer-literal::
    decimal-literal
    octal-literal
    hexadecimal-literal
    binary-literal

    decimal-literal::
      nonzero-digit
      decimal-literal   digit

    octal-literal::
      0
      octal-literal   octal-digit

    hexadecimal-literal::
      hexadecimal-prefix   hexadecimal-digit
      hexadecimal-literal   hexadecimal-digit

    hexadecimal-prefix:: one of
      0x  0X

    binary-literal::
      binary-prefix   binary-digit
      binary-literal   binary-digit

    binary-prefix:: one of
      0b  0B

    digit:: one of
      0  1  2  3  4  5  6  7  8  9

    nonzero-digit:: one of
      1  2  3  4  5  6  7  8  9

    octal-digit:: one of
      0  1  2  3  4  5  6  7

    hexadecimal-digit:: one of
      0  1  2  3  4  5  6  7  8  9
            a  b  c  d  e  f
            A  B  C  D  E  F

    binary-digit:: one of
        0  1

Constraints

The value of an integer literal must be representable by its type.

Semantics

The value of a decimal integer literal is computed using base 10; that of an octal integer literal, base 8; that of a hexadecimal integer literal, base 16; and that of a binary integer literal, base 2.

The type of an integer-literal is int.

Using a twos-complement system, can the smallest negative value (-9223372036854775808 for 64 bits) be represented as a decimal integer literal? No. Consider the expression -5. This is made up of two tokens: a unary minus followed by the integer literal 5. As such, there is no such thing as a negative-valued decimal integer literal in Hack. Instead, there is the non-negative value, which is then negated. Literals written using hexadecimal, octal, or binary notations are considered to have non-negative values.

Examples

$count = 10      // decimal 10

0b101010 >> 4    // binary 101010 and decimal 4

0XAF << 023      // hexadecimal AF and octal 23

Floating-Point Literals

Syntax

  floating-literal::
    fractional-literal   exponent-partopt
    digit-sequence   exponent-part

  fractional-literal::
    digit-sequenceopt . digit-sequence
    digit-sequence .

  exponent-part::
    e  signopt   digit-sequence
    E  signopt   digit-sequence

  sign:: one of
    +  -

  digit-sequence::
    digit
    digit-sequence   digit

Defined elsewhere

• digit

Constraints

The value of a floating-point literal must be representable by its type.

Semantics

The type of a floating-literal is float.

The constants INF and NAN provide access to the floating- point values for infinity and Not-a-Number, respectively.

Examples

$values = array(1.23, 3e12, 543.678E-23);

String Literals

Syntax

  string-literal::
    single-quoted-string-literal
    double-quoted-string-literal
    heredoc-string-literal
    nowdoc-string-literal

Defined elsewhere

• double-quoted-string-literal
• heredoc-string-literal
• nowdoc-string-literal
• single-quoted-string-literal

Note: By conventional standards, calling heredoc-string-literals and nowdoc-string-literals) literals is a stretch, as each is hardly a single token. And given the variable substitution permitted in double-quote-string-literals, they are not really literals either.

Semantics

A string literal is a sequence of zero or more characters delimited in some fashion. The delimiters are not part of the literal's content.

The type of a string literal is string.

Single-Quoted String Literals

Syntax

  single-quoted-string-literal::
    ' sq-char-sequenceopt  '

  sq-char-sequence::
    sq-char
    sq-char-sequence   sq-char

  sq-char::
    sq-escape-sequence
    \opt   any member of the source character set except single-quote (') or backslash (\)

  sq-escape-sequence:: one of
    \'  \\

Semantics

A single-quoted string literal is a string literal delimited by single-quotes ('). The literal can contain any source character except single-quote (') and backslash (\), which can only be represented by their corresponding escape sequence.

A single-quoted string literal is a c-constant.

Examples

'This text is taken verbatim'

'Can embed a single quote (\') and a backslash (\\) like this'

Double-Quoted String Literals

Syntax

  double-quoted-string-literal::
    " dq-char-sequenceopt  "

  dq-char-sequence::
    dq-char
    dq-char-sequence   dq-char

  dq-char::
    dq-escape-sequence
    any member of the source character set except double-quote (") or backslash (\)
    \  any member of the source character set except "\$efnrtvxX or octal-digit

  dq-escape-sequence::
    dq-simple-escape-sequence
    dq-octal-escape-sequence
    dq-hexadecimal-escape-sequence
    dq-unicode-escape-sequence

  dq-simple-escape-sequence:: one of
    \"   \\   \$   \e   \f   \n   \r   \t   \v

  dq-octal-escape-sequence::
    \   octal-digit
    \   octal-digit   octal-digit
    \   octal-digit   octal-digit   octal-digit

  dq-hexadecimal-escape-sequence::
    \x  hexadecimal-digit   hexadecimal-digitopt
    \X  hexadecimal-digit   hexadecimal-digitopt

  dq-unicode-escape-sequence::
    \u{  codepoint-digits  }

  codepoint-digits::
     hexadecimal-digit
     hexadecimal-digit   codepoint-digits

Defined elsewhere

• hexadecimal-digit
• octal-digit

Semantics

A double-quoted string literal is a string literal delimited by double-quotes ("). The literal can contain any source character except double-quote (") and backslash (\), which can only be represented by their corresponding escape sequence. Certain other (and sometimes non-printable) characters can also be expressed as escape sequences.

An escape sequence represents a single-character encoding, as described in the table below:

Within a double-quoted string literal, except when recognized as the start of an escape sequence, a backslash (\) is retained verbatim.

Within a double-quoted string literal a dollar ($) character not escaped by a backslash (\) is handled using a variable substitution rules described below.

The \u{xxxxxx} escape sequence produces the UTF-8 encoding of the Unicode codepoint with the hexadecimal number specified within the curly braces. Implementations MUST NOT allow Unicode codepoints beyond U+10FFFF as this is outside the range UTF-8 can encode (see RFC 3629). If a codepoint larger than U+10FFFF is specified, implementations MUST error. Implementations MUST pass through \u verbatim and not interpret it as an escape sequence if it is not followed by an opening {, but if it is, implementations MUST produce an error if there is no terminating } or the contents are not a valid codepoint. Implementations MUST support leading zeroes, but MUST NOT support leading or trailing whitespace for the codepoint between the opening and terminating braces. Implementations MUST allow Unicode codepoints that are not Unicode scalar values, such as high and low surrogates.

A Unicode escape sequence cannot be created by variable substitution. For example, given $v = "41", "\u{$v}" results in "\u41", a string of length 4, while "\u{0$v}" and "\u{{$v}}" contain ill-formed Unicode escape sequences.

Variable substitution

The variable substitution accepts the following syntax:

    string-variable::
        variable-name   offset-or-propertyopt

    offset-or-property::
        offset-in-string
        property-in-string

    offset-in-string::
        [   name   ]
        [   variable-name   ]
        [   integer-literal   ]

    property-in-string::
        ->   name

Defined elsewhere

• expression
• integer-literal
• name
• variable-name

After the variable defined by the syntax above is evaluated, its value is converted to string according to the rules of string conversion and is substituted into the string in place of the variable substitution expression.

Subscript or property access defined by offset-in-string and property-in-string is resolved according to the rules of the subscript operator and member selection operator respectively. The exception is that name inside offset-in-string is interpreted as a string literal even if it is not quoted.

If the character sequence following the $ does not parse as name then the $ character is instead interpreted verbatim and no variable substitution is performed.

A double-quoted string literal is a c-constant if it does not contain any variable substitution.

Examples

$x = 123;
echo ">\$x.$x"."<"; // → >$x.123<
// -----------------------------------------
$colors = array("red", "white", "blue");
$index = 2;
echo "\$colors[$index] contains >$colors[$index]<\n";
  // → $colors[2] contains >blue<
// -----------------------------------------
class C {
    public $p1 = 2;
}
$myC = new C();
echo "\$myC->p1 = >$myC->p1<\n";  // → $myC->p1 = >2<

Heredoc String Literals

Syntax

  heredoc-string-literal::
    <<<  hd-start-identifier   new-line   hd-char-sequenceopt  new-line hd-end-identifier  ;opt   new-line

  hd-start-identifier::
    name

  hd-end-identifier::
    name

  hd-char-sequence::
    hd-char
    hd-char-sequence   hd-char

  hd-char::
    hd-escape-sequence
    any member of the source character set except backslash (\)
    \  any member of the source character set except \$efnrtvxX or
octal-digit

  hd-escape-sequence::
    hd-simple-escape-sequence
    dq-octal-escape-sequence
    dq-hexadecimal-escape-sequence
    dq-unicode-escape-sequence

  hd-simple-escape-sequence:: one of
    \\   \$   \e   \f   \n   \r   \t   \v

Defined elsewhere

• dq-hexadecimal-escape-sequence
• dq-octal-escape-sequence
• dq-unicode-escape-sequence
• name
• new-line

Constraints

The start and end identifier must be the same. Only horizontal white space is permitted between <<< and the start identifier. No white space is permitted between the start identifier and the new-line that follows. No white space is permitted between the new-line and the end identifier that follows. Except for an optional semicolon (;), no characters—not even comments or white space—are permitted between the end identifier and the new-line that terminates that source line.

Semantics

A heredoc string literal is a string literal delimited by "<<< name" and "name". The literal can contain any source character. Certain other (and sometimes non-printable) characters can also be expressed as escape sequences.

A heredoc literal supports variable substitution as defined for double-quoted string literals.

A heredoc string literal is a c-constant if it does not contain any variable substitution.

Examples

$v = 123;
$s = <<<    ID
S'o'me "\"t e\txt; \$v = $v"
Some more text
ID;
echo ">$s<";
→ >S'o'me "\"t e  xt; $v = 123"
Some more text<

Nowdoc String Literals

Syntax

  nowdoc-string-literal::
    <<<  '  hd-start-identifier  '  new-line  hd-char-sequenceopt   new-line hd-end-identifier  ;opt   new-line

Defined elsewhere

• hd-char-sequence
• hd-end-identifier
• hd-start-identifier
• new-line

Constraints

No white space is permitted between the start identifier and its enclosing single quotes ('). See also §§.

Semantics

A nowdoc string literal looks like a heredoc string literal except that in the former the start identifier name is enclosed in single quotes ('). The two forms of string literal have the same semantics and constraints except that a nowdoc string literal is not subject to variable substitution.

A nowdoc string literal is a c-constant.

Examples

$v = 123;
$s = <<<    'ID'
S'o'me "\"t e\txt; \$v = $v"
Some more text
ID;
echo ">$s<\n\n";
→ >S'o'me "\"t e\txt; \$v = $v"
Some more text<

The Null Literal

  null-literal::
    null

Semantics

There is one null-literal value, null.

A null-literal has the null type.

Operators and Punctuators

Syntax

  operator-or-punctuator:: one of
    [   ]    (   )   {    }   .   ->   ++   --   **   *   +   -   ~   !
    $   /   %   <<   >>   <   >   <=   >=   ==   ===   !=   !==   ^   |
    &   &&   ||   ?   ??   :   ; =   **=   *=   /=   %=   +=   -=   .=   <<=
    >>=   &=   ^=   |=   ,   @   ::   =>   ==>   ?->   \   ...    |>   $$

Semantics

Operators and punctuators are symbols that have independent syntactic and semantic significance. Operators are used in expressions to describe operations involving one or more operands, and that yield a resulting value, produce a side effect, or some combination thereof. Punctuators are used for grouping and separating.