第一个程序与程序结构

本章导读

第 1 章我们把工具装好了，还跑通了一行 print。但从"能跑一行"到"会写一个程序"之间，隔着一组基础规则：程序从哪里开始执行？语句怎么结束？注释怎么写？名字怎么起？

本章逐条讲清这些问题。学完后你应该能看懂任何一个 xlang 源文件的整体结构，知道每一行代码为什么在那个位置、以那种形式书写。这些规则在全书每一章都会用到，是名副其实的"地基"。

2.1 源文件与编码

xlang 源文件约定两条：

• 扩展名是 .xl；
• 内容按 UTF-8 编码处理。

UTF-8 意味着源文件里可以直接出现中文——不止字符串里可以，标识符也可以（2.6 节会专门演示）。用任何现代编辑器（VS Code、记事本均可）保存时选择 UTF-8 编码即可，这也是当今绝大多数编辑器的默认编码。

2.2 程序入口 main

和 C 家族语言一样，xlang 程序有一个明确入口：main 函数。标准形态是：

func main(...) as int
    print("程序启动")
    return 0
end

逐部分拆解：

• func：声明一个函数的关键字；
• main：函数名。main 是约定俗成的入口名，编译器会特殊对待它；
• (...)：可变参数，表示"接收命令行传进来的所有参数"，函数体内通过内置名字 arg 访问；
• as int：返回类型是整数；
• return 0：返回 0 表示程序正常结束；
• end：函数体结束。xlang 不用大括号，所有块结构都用 end 收尾。

返回值就是进程退出码。这是可以实测验证的：

约定和 C 完全一致：0 表示成功，非 0 表示某种失败。写脚本工具时，调用方就靠这个码判断成败。

命令行参数去哪了

第 1 章提过 xl run 可以用 -- 把参数传给程序。参数经由 ... 进入 arg，实测：

func main(...) as int
    println("参数个数:", arg.length)
    for a in arg
        println("参数:", a)
    end
    return 0
end

两个新知识点顺带预告：for ... in ... end 是遍历循环（第 9 章）；arg.length 取数组长度（第 16 章）。现在只需注意一个细节：arg 的第一个元素是脚本路径本身，真正的用户参数从第二个开始——这和 C 的 argv[0] 传统一脉相承。

2.3 顶层语句与 main

第 1 章的 hello.xl 没有 main 也能跑，因为 xlang 允许在文件顶层直接书写可执行语句。那么顶层语句和 main 同时存在时，谁先谁后？实测：

print("顶层语句 1")
print("顶层语句 2")

func main(...) as int
    print("main 函数内")
    return 0
end

输出顺序说明规则：先执行顶层语句，再调用 main。同时注意 print 不换行，三句话挤在了一起——想每句一行请用 println。

这个"顶层先行"的特性非常实用：脚本类程序往往不需要 main，写完语句就能跑；而当程序长大、需要退出码和参数处理时，再加上 main 也不冲突。

2.4 语句分隔

xlang 里结束一条语句有两种方式：

• 换行——最常用，一行一条语句；
• 分号 ;——把多条语句写在同一行时使用。

int a = 1
int b = 2; int c = 3          // 同一行两条语句，用分号
int d = (1 +
         2)                     // 括号内部换行不结束语句
println(a, b, c, d)

第三条规则很重要：()、[]、{} 内部的换行不会结束语句。长表达式、长参数列表可以放心折行，编译器知道括号没合上、语句还没完。

反过来，同一行写两条语句而不加分号是语法错误——这是本章"常见错误"的第 1 个坑。

2.5 三种注释

xlang 有三种注释，用途各不相同。

单行注释 //

从 // 到行尾都是注释，可独占一行，也可跟在代码后面。

块注释 /* ... */，支持嵌套

// 单行注释
/* 多行注释
   /* 嵌套的注释 */
   仍然注释 */
print("ok")  // 行尾注释

嵌套是 xlang 块注释区别于 C 的重要一点：C 的 /* */ 不能嵌套（第一个 */ 就收尾），注释掉一段本身含块注释的代码时会出错；xlang 会数配对，内层 /* */ 闭合后外层依然有效，实测上面的文件正常输出 ok。注释整块代码时只管首尾各包一层即可。

文档注释 #doc ... #end

写在函数（或类）前面的结构化文档，不只是给人看——它会进入编译器的语义校验：

#doc
desc:
    把两个整数相加。
param a:
    第一个加数。
param b:
    第二个加数。
return value:
    两数之和。
example:
    ```xlang
    print(add(1, 2))
    ```
#end
func add(int a, int b) as int
    return a + b
end

print(add(1, 2))

支持的字段：desc:（功能描述）、param 名字:（参数说明）、return 名字:（返回值说明）、note:（备注）、example:（示例）。字段内容按缩进收集多行文本；example: 里的代码围栏只作为文档文本保存，不会被当作代码解析。

2.6 标识符规则

标识符就是你在代码里起的名字：变量名、函数名、类型名。规则如下：

• 由字母、数字、下划线组成，不能以数字开头；
• 大小写敏感：Name 和 name 是两个不同的名字；
• 支持 UTF-8 标识符——中文可以直接做变量名、函数名；
• 不能使用关键字（保留字）。

int 年龄 = 18
string 名字 = "小明"
println(名字, 年龄)
int camelCase = 1     // 驼峰
int snake_case = 2    // 下划线
int _private = 3      // 下划线开头
println(camelCase, snake_case, _private)

大小写敏感意味着 print 必须小写——写成 Print 编译器会报"未声明的标识符"（见常见错误坑 3）。

xlang 的关键字全集如下，混个眼熟即可，后面每章都会用到其中一批：

另外还有三个上下文相关的名字：self、base、create——它们在类里才有特殊含义（第 21 章），普通场景可以当普通名字用。而 object 不是保留字，它只是标准库注入的一个基础类名。

2.7 程序结构与 import

把本章零件组装起来，一个典型 xlang 源文件的结构是：

// 1. import 区（需要扩展库时）
import pkg.math

// 2. 声明区：常量、变量、函数、类型
const int LIMIT = 100

func helper(int x) as int
    return x * 2
end

// 3. 顶层可执行语句（可选）
println("add_one(6) =", pkg.math.add_one(6))

// 4. main 入口（可选，与顶层语句共存时最后执行）
func main(...) as int
    return 0
end

四个区域没有强制顺序要求，但按"import → 声明 → 语句 → main"组织可读性最好。

import 是本章唯一的"预告"：标准库默认全部可用，不需要 import（所以 print 拿来就用）；import 引入的是扩展库（package）。上面示例中的 pkg.math 就是发行包 extlibs 目录里自带的一个示例扩展库，这段代码笔者在发行包根目录实测输出：

现在只要建立概念："import 把外部包的能力引进来"。扩展库的查找规则、版本管理和如何编写自己的 package，是第 35 章的主题。

深入细节

⚠️ 常见错误

以下报错均为真实输出。

本章小结

复习题

编程练习