词法与大小写

这一页讲字符级别的规则：哪些 token 在意大小写、注释和字面量怎么读、section 的内容怎么被切成语句。 大部分内容不会让人意外。真正需要记住的是三点 —— 大小写敏感性矩阵、宽容到有点危险的数字转换，以及 制表符的坑。

大小写敏感性

顶层块关键字是整门语言里唯一大小写敏感的 token。 其余所有类关键字的东西都忽略大小写匹配。

所以 shader(Name="X") 和 SHADER(Name="X") 都是语法错误，而 properties = { … }、settings { domain = "ui"; } 和 Shader(name="X") 都能被接受。

关键字匹配还要求右侧词边界：关键字后面的字符不能是字母、数字或 _。正是这条规则让 ShaderFunction 不会被当成 Shader，ShaderLayerBlend 不会被当成 ShaderLayer。

语法概览

<token> := <identifier> | <keyword> | <string-literal> | <numeric-text> | <punctuation>

<identifier>     := { <letter> | _ } { <letter> | <digit> | _ }…
<qualified-name> := <identifier> :: <identifier>
<string-literal> := " { <character> | \<escape> }… "
<punctuation>    := { | } | ( | ) | [ | ] | ; | = | , | . | :: | #

空白和注释可以出现在任意两个 token 之间，除此之外没有意义。

空白

引擎认定为空白的任何字符都能分隔 token：空格、制表符、回车、换行以及其他 Unicode 空白字符。换行在 声明语法里没有任何语法作用 —— 只有面向行的处理才关心它： import 指令、Graph 体内的 #Region 指令，以及诊断的行号。

注释

• 块注释不嵌套。 /* a /* b */ c */ 在第一个 */ 处结束，后面的 c */ 又变回代码。
• 未闭合的块注释会被静默接受。 只有 /* 没有 */ 会吞掉文件剩余部分，且不产生任何诊断。相比之下 未闭合的 { 块会失败于 Unterminated block.
• 注释在声明语法的每个位置都被同样识别，包括统计 {}、()、[] 嵌套时，所以注释里的花括号或引号 永远不会让块失衡。
• 在 Properties、Settings、Outputs、Layout 和类型化参数 section 里切分语句之前，还会再做一次 文本级去注释。那一遍是感知字符串的，并且保留终止行注释的那个换行，所以行号不会错位。
• 声明解析器不会去掉 Graph 体里的注释。 Graph 块中的注释原样和函数体一起存下来，之后交给表达式 分词器处理。
• 声明层面没有 # 预处理器。#Region / #EndRegion 只在 Graph 体内被识别 —— 见 Layout 与 #Region。

标识符

没有长度上限，而且没有任何关键字对标识符是保留的：叫 Shader、Graph 或 float 的属性、变量、 参数、函数都不会被拒绝。至于这个名字之后能不能解析成功，那是它所处上下文的事。

Inputs、Outputs、Results 和 Layout 调用里的声明名字有更严的检查：整个去空白后的 token 必须 符合标识符规则。Properties 里的名字只要求非空，所以 Properties { float 1Bad = 0; } 能解析通过 —— 它只是永远无法从 Graph 里被引用。

带命名空间的名字用 ::，例如 Common::ApplyTint。见 函数。

名字净化

名字进入生成的 HLSL 时会被净化：A–Z a–z 0–9 _ 之外的每个字符变成 _，开头是数字则加一个 _ 前缀， 连续的 __ 塌缩成一个，结果为空或全是下划线时变成 DreamShaderSymbol。

Common::ApplyTint   →   Common__ApplyTint   →   Common_ApplyTint

正是这次塌缩，让 Common::ApplyTint 和顶层的 Common_ApplyTint 在生成代码里撞名。

字符串字面量

带引号的值以 " 开始，到下一个未转义的 " 结束，读入时完成反转义。反斜杠总是吞掉紧随其后的那个字符， 所以 \" 永远不会终结字面量。

任何可以写引号的地方 —— settings 值、元数据值、属性值、参数值 —— 引号都是可选的。原始文本先被去掉 首尾空白，只有当结果至少两个字符长、且首尾都是 " 时才剥掉引号。所以 Domain = UI; 和 Domain = "UI"; 等价。

没有数字转义。\0、\xNN、\uNNNN 都落进"其他字符"那一行，所以 \0 得到 0，\x41 得到 x41。

Graph 表达式语法使用同样的五个转义和同样的透传规则；区别是那里未闭合的字符串会在输入结束时静默闭合， 而不是报错。

数字字面量

声明语法和 Graph 表达式语法在这里并不一致，这个差异是常见的意外来源。

声明语法

声明语法没有数字 token。值以原始文本捕获，只有当某个消费者要一个数字时才转换。

向量字面量的形式故意写得很松。第一个 ( 和最后一个 ) 界定分量，而 ( 之前的文本被完全忽略 —— float3(1,0,0)、vec3(1,0,0)、(1,0,0) 和 Nonsense(1,0,0) 解析结果完全一样。内部按 , 切分且 不跟踪嵌套，所以某个分量里再嵌一层调用就会切错。每个分量可以是数字，也可以是 true / false。

未填充时的默认值是 (0, 0, 0, 1)。

Graph 表达式语法

在 Graph 块里，数字是真正的 token。

只有当后缀后面的字符不是字母、数字或 _ 时后缀才会被消费，而且它不进入 token 文本：0.55f 就是 数字 0.55。因为只消费一个后缀，1.0ul 会被读成数字 1.0 后面跟标识符 ul。

表达式分词器接受这些单字符 token：( ) , . + - * / =，外加双字符的 ::。

语句切分

section 的内容是一串以 ; 分隔的语句。

• ; 只在圆括号深度 0 且方括号深度 0 时才分隔语句，字符串字面量内部永远不分。
• 通用切分器不跟踪花括号。Properties 有自己的感知花括号的遍历器，才让 Group("…") { … } 生效； 其余每个 section 都把 { 当普通字符。
• 空语句被丢弃，所以多余的 ;; 无害。
• 最后一条语句即使没有终止符也会被提交 —— 块内最后一个 ; 是可选的。
• section 闭合 } 之后的 ; 是可选的，section 名和它的块之间的 = 也是可选的 since 1.5.0。

随后有三种切分器把一条语句拆成几部分，它们对"什么算空白"的看法并不一致：

参数列表按 , 切分，深度和字符串跟踪规则相同，所以不带引号的属性值里不能含 , 或 )：Root=Game 可以，Name=Foo(1,2) 不行。

示例

// 顶层声明之前的行注释。
Shader(Name="Materials/M_Comments")
{
    /* 跨多行的
       块注释。 */
    Settings = {
        Domain = "UI";        // 行尾注释
        ShadingModel = Unlit; // 引号可选
    }

    Properties {
        // Properties 的类型和名字之间可以用任意空白。
        ScalarParameter Rough = 0.5 [Group="Surface"; Slider(0, 1)];
        vec3            Tint  = vec3(1.0, 0.4, 0.1);
        float           Fudge = 1.0f;   // 解析为 1.0 —— 后缀被忽略，不是被拒绝
    }

    Outputs {
        vec3 Color;                     // 这里必须是字面空格
        Base.EmissiveColor = Color
    }                                   // 块内最后一个 ';' 可省略

    Graph {
        vec2 UV = UE.TexCoord(Index = 0);
        Color = vec3(Rough, Rough, UV.x) * Tint;
    }
}

诊断

只有以 near index {Index} 结尾的消息才带位置，诊断映射器才能把它变成文件、行、列。见 import 与命名空间。

继续阅读