diff --git a/docs/_pages/syntax.md b/docs/_pages/syntax.md index fe825fda..595a4804 100644 --- a/docs/_pages/syntax.md +++ b/docs/_pages/syntax.md @@ -219,3 +219,57 @@ end ``` The default iteration order for tables is specified to be consecutive for elements `1..#t` and unordered after that, visiting every element; similarly to iteration using `pairs`, modifying the table entries for keys other than the current one results in unspecified behavior. + +## String interpolation + +Luau adds an additional way to define string values that allows you to place runtime expressions directly inside specific spots of the literal. + +This is a more ergonomic alternative over using `string.format` or `("literal"):format`. + +To use string interpolation, use a backtick string literal: + +```lua +local count = 3 +print(`Bob has {count} apple(s)!`) +--> Bob has 3 apple(s)! +``` + +Any expression can be used inside `{}`: + +```lua +local combos = {2, 7, 1, 8, 5} +print(`The lock combination is {table.concat(combos)}.`) +--> The lock combination is 27185. +``` + +Inside backtick string literal, `\` is used to escape `` ` ``, `{`, `\` itself and a newline: + +```lua +print(`Some example escaping the braces \{like so}`) +--> Some example escaping the braces {like so} + +print(`Backslash \ that escapes the space is not a part of the string...`) +--> Backslash that escapes the space is not a part of the string... + +print(`Backslash \\ will escape the second backslash...`) +--> Backslash \ will escape the second backslash... + +print(`Some text that also includes \`...`) +--> Some text that also includes `... + +local name = "Luau" + +print(`Welcome to { + name +}!`) +--> Welcome to Luau! +``` + +### Restrictions and limitations + +The sequence of two opening braces {{"`{{`"}} is rejected with a parse error. +This restriction is made to prevent developers using other programming languages with a similar feature from trying to attempt that as a way to escape a single `{` and getting unexpected results in Luau. + +Luau currently does not support backtick string literals as a type annotation, so `` type Foo = `Foo` `` is invalid. + +Function calls with a backtick string literal without parenthesis is not supported, so `` print`hello` `` is invalid. diff --git a/docs/_posts/2023-02-02-luau-string-interpolation.md b/docs/_posts/2023-02-02-luau-string-interpolation.md new file mode 100644 index 00000000..0bfa33a2 --- /dev/null +++ b/docs/_posts/2023-02-02-luau-string-interpolation.md @@ -0,0 +1,33 @@ +--- +layout: single +title: "String Interpolation" +--- + +String interpolation is the new syntax introduced to Luau that allows you to create a string literal with expressions inside of that string literal. + +In short, it's a safer and more ergonomic alternative over `string.format`. + +Here's a quick example of a string interpolation: + +```lua +local combos = {2, 7, 1, 8, 5} +print(`The lock combination is {table.concat(combos)}. Again, {table.concat(combos, ", ")}.`) +--> The lock combination is 27185. Again, 2, 7, 1, 8, 5. +``` + +String interpolation also composes well with the `__tostring` metamethod. + +```lua +local balance = setmetatable({ value = 500 }, { + __tostring = function(self) + return "$" .. tostring(self.value) + end +}) + +print(`You have {balance}!`) +--> You have $500! +``` + +To find out more details about this feature, check out [Luau Syntax page](/syntax#string-interpolation). + +This is also the first major language feature implemented in a [contribution](https://github.com/Roblox/luau/pull/614) from the open-source community. Thanks [Kampfkarren](https://github.com/Kampfkarren)!