企业官网建设流程全解析

• 编程语言
• 编译器

导读

CoffeeScript 1.9.3 于 2015 年 5 月 27 日发布，是 1.9.x 系列的一个 bugfix 版本。本篇文章基于仓库中的 1.9.3 变更日志 展开，逐一解读该版本修复的隐式调用中对象首键插值问题、REPL 错误信息与若干交互缺陷、--bare编译下的 Source Map 修正（并顺带带来更小的 map 体积）、编译后块注释的格式改进，以及on/off/yes/no关键字的报错优化。读完本文，你将理解这些修复背后的词法、语法树与源码映射机制，并能对照 src/ 下的编译器源码定位每一处改动的实现细节。

版本背景与发布信息

• 发布日期：2015-05-27
• 版本号：1.9.3
• 上一个版本：1.9.2

仓库中每个版本变更日志的头部都通过releaseHeader函数统一生成发布信息，参见 0.1.0.md 等全部 changelog 文件：

releaseHeader('2015-05-27', '1.9.3', '1.9.2')

该函数声明了发布日期、当前版本号与上一版本号三个参数。1.9.3 属于 1.9.x 稳定分支的小版本，全部改动均为 bugfix 与错误处理改进，未引入新语法特性。

修复一：隐式调用中对象字面量首键的插值

Bugfix for interpolation in the first key of an object literal in an implicit call.

问题场景

CoffeeScript 允许省略调用括号（implicit call），例如：

console.log foo: "#{name}"

此时foo: "#{name}"会被解析为传给console.log的对象字面量。当对象字面量的第一个键本身包含字符串插值（interpolation）时，词法分析器（Lexer）在#与后续插值表达式之间切换词法状态的过程中会出现歧义：#既是插值起始标记，又是行注释起始标记。1.9.3 修复了在隐式调用语境下该首键插值无法被正确识别的 bug。

底层机制

CoffeeScript 的字符串插值由 src/lexer.coffee 负责，词法分析器通过一组按优先级排列的正则尝试匹配 token（见tokenize主循环，约 L65-L89）。插值发生时 Lexer 会进入interpolateString等内部状态，而对象字面量首键位置的 token 类型判定（IDENTIFIER、STRING还是其他）取决于前序 token 的上下文。

从源码结构看，词法分析器使用COFFEE_KEYWORDS与COFFEE_ALIASES判断标识符是否为关键字（见 src/lexer.coffee 中identifierToken相关逻辑，约 L121-L160），并在 token 前一个为关键字时将prev改写为IDENTIFIER。本版本修复的是该判定流程在"隐式调用 + 对象首键 + 插值"这一组合下的边界情况，确保{ "#{key}": value }这类写法无论位于调用列表何处都能稳定解析。

修复二：REPL 错误信息与交互细节

Fixed broken error messages in the REPL, as well as a few minor bugs with the REPL.

REPL 的实现位置

CoffeeScript 的交互式命令行（coffee -i或coffee无参数进入）由 src/repl.coffee 实现。它以 Node.js 内置的repl模块为基础，覆盖了自定义的eval函数：

• 将 Node REPL 对输入包裹的额外括号剥离（/^\(([\s\S]*)\n\)$/m）；
• 剥离新版 Node REPL 包裹的try { ... } catch结构（约 L17-L25）；
• 通过CoffeeScript.tokens分词、CoffeeScript.nodes构建 AST，再以bare: yes编译为 JavaScript 后在 VM 上下文中执行（约 L30-L65）。

错误信息修复

旧版本中，REPL 里出现语法错误时，由于错误对象缺少源码位置信息，打印出的报错往往无法定位到具体行，甚至显示为空白。1.9.3 引入updateSyntaxError来修正这个问题——在catch分支中调用它把源码文本与行号补写进错误对象：

catch err # AST's `compile` does not add source code information to syntax errors. updateSyntaxError err, input cb err

（src/repl.coffee 约 L66-L69）

updateSyntaxError定义于 src/helpers.coffee 约 L227 处。当错误对象已带位置时直接返回；否则将错误对象包装为带location数据的SyntaxError，并把 CoffeeScript 源码按行保存到错误的code属性中。这样 REPL 抛出的错误就能被正确格式化并指向具体源码行，与coffee命令行编译报错的行为保持一致。

其他交互修复

本版本还顺带修复了 REPL 的几个小缺陷，主要包括多行输入处理（addMultilineHandler，支持Ctrl-V切换多行模式，src/repl.coffee）与命令历史持久化（addHistory，写入~/.coffee_history，约 L129-L167）中的边界问题，例如历史文件截断时多出的半个行、首行空记录等。

修复三：--bare编译下源码映射（Source Map）修正

Fixed source mappings for tokens at the beginning of lines when compiling with the--bareoption. This has the nice side effect of generating smaller source maps.

--bare与源码映射的关系

默认情况下，CoffeeScript 编译产物会包裹在(function(){ ... }).call(this);的 IIFE 中；--bare选项去掉这层包装，直接输出顶层代码（常用于浏览器端直接执行或与其他模块体系配合）。这个差异会影响生成的 JavaScript 与原始 CoffeeScript 之间的行列对应关系。

修复内容

此前使用--bare编译时，位于输出行行首的 token的源码映射（source mapping）不准确。原因在于：非 bare 模式下，包装函数代码本身占据了若干偏移，编译器据此对生成位置做补偿；而在 bare 模式下没有这些偏移，位于行首的 token 的first_column补偿逻辑与实际生成位置存在偏差。

修复后，行首 token 的映射位置被正确记录。该修复同时带来一个附带收益：生成的 source map 更小。这是因为LineMap中按列存储映射（见 src/sourcemap.litcoffee），不再为错误的列位置重复写入冗余的 VLQ 段，mappings字符串长度随之缩短。

源码映射机制速览

Source Map 模块位于 src/sourcemap.litcoffee：

• LineMap：保存单行输出代码中每个列位置对应的[sourceLine, sourceColumn]；
• SourceMap：由多行LineMap组成，提供add（登记映射）与sourceLocation（反查原始位置）；
• generate：产出 v3 格式的 JSON 对象，mappings字段通过自定义的encodeVlq（Base64 VLQ 编码，src/sourcemap.litcoffee）生成紧凑字符串。

编译器入口 src/coffeescript.coffee 在options.sourceMap或options.inlineMap时生成 map，并可通过//# sourceMappingURL指令嵌入或外链（约 L54-L66 与 L167-L176）。此外，该文件还使用缓存的 source map 对运行时栈追踪进行反查，让报错堆栈指向 CoffeeScript 原始源码（约 L308-L315）。

命令行中使用方式：

coffee --bare --map file.coffee # 或 coffee -b -m file.coffee

修复四：编译后块注释（Block Comment）的格式改进

Slight formatting improvement of compiled block comments.

CoffeeScript 的块注释以### ... ###书写，编译后转为/* ... */。1.9.3 对转换后的排版做了小幅改进，使得多行块注释的输出更加整洁。

底层实现在 src/nodes.coffee 的HereComment类（约 L1604-L1636）：

# Comment delimited by `###` (becoming `/* */`). exports.HereComment = class HereComment extends Base compileNode: (o) -> multiline = '\n' in @content # Unindent multiline comments. They will be reindented later. if multiline indent = null for line in @content.split '\n' leadingWhitespace = /^\s*/.exec(line)[0] if not indent or leadingWhitespace.length < indent.length indent = leadingWhitespace @content = @content.replace /// \n #{indent} ///g, '\n' if indent ...

该版本改进主要体现在缩进处理上：多行块注释先统一去掉公共最小缩进，编译时再按当前输出层级重新缩进；同时保留注释内部的换行结构，使/* ... */的生成结果与源码缩进风格保持一致，避免输出中出现多余的空白行或错位缩进。

修复五：on/off/yes/no的错误信息优化

Better error messages foron,off,yesandno.

关键字别名机制

CoffeeScript 将yes/no/on/off作为布尔字面量的别名，与true/false等价。这一映射定义在 src/lexer.coffee 的COFFEE_ALIAS_MAP中：

COFFEE_ALIAS_MAP = and : '&&' or : '||' is : '==' isnt : '!=' not : '!' yes : 'true' no : 'false' on : 'true' off : 'false' COFFEE_ALIASES = (key for key of COFFEE_ALIAS_MAP) COFFEE_KEYWORDS = COFFEE_KEYWORDS.concat COFFEE_ALIASES

（src/lexer.coffee 约 L1241-L1253）

即COFFEE_KEYWORDS在'undefined', 'Infinity', 'NaN', 'then', 'unless', 'until', 'loop', 'of', 'by', 'when'的基础上追加了全部别名。

改进点

由于on、off、yes、no会被词法分析器改写为true/false，此前当用户将它们用作变量名或尝试赋值时，报错信息往往晦涩难懂（例如提示"unexpected identifier"）。1.9.3 改进了针对这四个词的错误信息。

词法层相关逻辑可见 src/lexer.coffee：

• 当别名作为标识符出现时，lexer 根据上下文决定是否将其改写为关键字（identifierToken中COFFEE_KEYWORDS判断，约 L143-L155）；
• 对不可赋值名称的统一判定在isUnassignable中（约 L1190-L1198），其中对JS_KEYWORDS/COFFEE_KEYWORDS输出 "keyword 'xxx' can't be assigned"、对保留字输出 "reserved word 'xxx' can't be assigned"。

优化后，当你写出以下代码：

on = 1 # 错误：keyword 'on' can't be assigned yes = true # 错误：keyword 'yes' can't be assigned

编译器会直接指出对应词属于 CoffeeScript 关键字/别名，并提示其不可赋值或不可作为函数名使用（后者对应 src/lexer.coffee 约 L210-L216 中get/set被误用时的报错分支，采用同样的"明确说明违规用法"的报错风格）。

如何验证这些修复

使用 REPL 验证错误信息

coffee coffee> yes = 1 # => Error: keyword 'yes' can't be assigned

验证 bare 模式 Source Map

coffee -b -m -c sample.coffee # 生成 sample.js 与 sample.js.map

对比 1.9.2 与 1.9.3 生成的sample.js.map中mappings字段长度，可观察到后者更短，且使用浏览器 DevTools /source-map库反查行首 token 时定位更准确。

验证块注释格式

### a b ###

编译后输出/*\n a\n b\n*/（缩进按公共前缀收敛、输出层级重排），多行结构得以保留。

小结

CoffeeScript 1.9.3 虽然只包含 bugfix，但覆盖了编译器管线的多个关键环节：词法分析（对象首键插值、关键字别名报错）、REPL 运行时（错误信息与交互）、代码生成与源码映射（--bare行首 token 映射、块注释排版）。这些改动共同提升了 1.9.x 分支在真实工程中的健壮性与可调试性。相关实现均可对照 src/lexer.coffee、src/repl.coffee、src/helpers.coffee、src/sourcemap.litcoffee 与 src/nodes.coffee 继续深入阅读。

• 编程语言
• 编译器