分析器接口

与 Exercism 网站的所有交互都是自动处理的。分析器的唯一职责是接收一个提交的解答，并返回一个状态和若干消息。

执行

• 分析器应当提供一个可执行的脚本。更多信息见 docker.md 文件。
• 脚本会接收三个参数：
  • 练习的 slug（例如 two-fer）。
  • 存放提交文件的目录路径（末尾带斜杠）。
  • 输出目录的路径（末尾带斜杠）。这个目录是可写的。
• 脚本必须把 analysis.json 文件写入输出目录。
• 脚本应当把 tags.json 文件写入输出目录。

允许的运行时间

每个提交的解答，分析器在 20 秒的时间窗口内可以获得 100% 的机器资源。 20 秒之后，进程会被中止，并报告超时。

输出格式

analysis.json

analysis.json 文件的结构应当如下：

{
  "summary": "This solution looks good but has a few points to address",
  "comments": [
    {
      "comment": "ruby.general.some_parameterised_message",
      "params": { "foo": "param1", "bar": "param2" },
      "type": "essential"
    },
    {
      "comment": "ruby.general.some_unparameterised_message",
      "params": {},
      "type": "actionable"
    },
    {
      "comment": "ruby.general.some_unparameterised_message"
    },
    "ruby.general.some_unparameterised_message"
  ]
}

summary（可选）

summary 字段是一段文本（不是 Markdown），用来概括输出结果。 它可能会写成像“你的提交的解答已经差不多了，只要再做两处小改动就好。”或者“代码写得很好，只是还有一点代码检查要做。”这样的话。 这段摘要会显示在网站上，位于评论的上方。

comments

comments 字段是一个评论数组，这些评论指向 exercism/website-copy 中的 Markdown 文档（更多信息见撰写分析器评论）。 数组中的每个值要么是一个指针字符串，要么是一个具有以下格式的 JSON 对象：

comment

指向 website-copy 中某个文件的指针字符串。

params（可选）

一个 JSON 对象，包含渲染时需要插值的所有参数。 例如，你可以在 Markdown 文件里写 Try %{variable_name} += 1 instead，然后把 params 设为 { "variable_name": "foo"}，这样 %{variable_name} 就会被替换成学员实际使用的那个变量。 使用带参数的文件时，务必对所有 % 进行转义，在它前面再加一个 %。 例如 Try aim aim for 100%% of the tests passing。

type（可选）

以下 type 值有效：

• essential：在学员处理这条评论之前，我们会软性阻止他们继续
• actionable：任何给出具体指示、帮助用户改进其提交的解答的评论
• informative：提供信息，但不一定期望学员采用的评论。例如在 Ruby 中，如果有人在 TwoFer 里用了字符串拼接，我们也会告诉他们字符串格式化的做法，但不建议说这是更好的选择。
• celebratory：告诉用户他们做对了某件事的评论，既可以是关于整个提交的解答的，也可以是关于某项技巧的。

没有 type 字段的评论默认是 informative 。

目前在本网站上，我们会对 essential 评论进行软性阻止，鼓励学员在把实践练习标记为完成之前先处理 actionable 评论（但概念练习不需要），而对 informative 或 celebratory 则不会建议任何操作。 不过将来我们可能会给其他类型加上 emoji 或指示图标，或者把它们分开归组。

tags.json

tags.json 文件的结构应当如下：

{
  "tags": [
    "construct:list",
    "paradigm:functional",
    "technique:higher-order-functions",
    "uses:List.unfold"
  ]
}

tags

tags 字段是一个字符串数组。 每个标签的格式为："<category>:<thing>"。

一些例子：

• "paradigm:functional"
• "technique:recursion"
• "construct:bitwise-and"
• "uses:DateTime.add_seconds"

标签可以用来标识一个提交的解答用到了哪些结构、技巧或范式。

更多信息见给提交的解答打标签。

调试

每次运行时 stdout 和 stderr 的内容都会被保存到文件中，之后可以查看。

你可以写一个 analysis.out 文件，放入你之后想查看的调试信息。

延伸阅读

在构建分析器之前，请先阅读我们的分析器指南。