Lib.rs

快速入门

由于 spor 是用 rust 编写的，所以您可以使用cargo:

$ cargo build

在您可以使用 spor 将元数据锚定到文件之前，您需要使用init命令初始化一个仓库

$ spor init

这与git init非常相似。它在您的当前目录中创建一个名为.spor的新目录，这是 spor 保存所需信息的地方。

现在您可以创建锚点。假设您有一个文件,example.py，如下所示

# example.py


def func(x):
    return x * 2

您可以通过指定起始偏移量和锚定宽度将元数据锚定到第 4 行（函数定义），如下所示

$ echo "{\"meta\": \"data\"}" | spor add example.py 32 12 10

您不需要将元数据管道到add命令。如果不这样做，spor 将弹出一个编辑器，让您在那里输入元数据。

最后的 10 指定了我们用于更新锚点的“上下文”代码的大小。

这将将字典{meta: data}与代码 return x * 2 关联。您可以使用list命令初始化一个仓库

$ spor list example.py
example.py:32 => {'meta': 'data'}

查看此元数据。元数据可以是任何有效的 YAML。spor 不会查看数据，因此您完全可以根据自己的意愿决定将其放在哪里。

动机

我创建这个工具的主要动机来自我对突变测试工具 Cosmic Ray 的工作。CR 用户需要能够指定其源代码中不应突变的部分，或者仅以特定方式突变的部分。而不是让他们在源代码中嵌入这些处理指令，我认为让他们使用单独的元数据文件这样做会更干净、更整洁。

特性

spor 需要以下功能支持

1. 向源文件中的特定文本范围添加/编辑/删除元数据
2. 查询现有元数据
3. 在可能的情况下自动更新元数据，或者在无法更新时报告错误
4. 提供更新元数据的“更新”功能

设计需要同时考虑到人类用户（即他们可能需要不时手动处理元数据）以及程序化用户。我相信设计会随着我们的进展而演变，所以我打算一开始尽量保持其简单和明确。

理想情况下，spor 应该能在任何编程语言（实际上，任何文本文档）上运行，尽管它的初始目标是 Python 源代码。

测试

使用 cargo 运行测试

$ cargo test

注释

“锚定”这个领域并不新鲜，我们需要关注一些现有的工作。

• Bielikova, Maria. "Metadata Anchoring for Source Code: Robust Location Descriptor Definition, Building and Interpreting"