Organic - Free Range Org-Mode

Organic 是一个不使用 emacs 的 org-mode 解析器。

项目状态

此项目仍在进行 heavy 开发。在版本保持为 v0.1.x 的同时，API 将会经常变化。一旦达到 v0.2.x，我们将开始遵循 semver。

目前，Organic 解析大多数文档与官方 org-mode 解析器相同。目前的大部分开发工作都是在寻找解析器不同的文档并修复这些问题。

项目目标

• 我们的目标是与 emacs org-mode 解析器提供完美的兼容性。在这方面，任何在 Emacs 和 Organic 之间解析不同的文档都视为一个错误。
• 解析器应该有最少的依赖。
• 解析器应该在任何地方都可以使用。为了尽可能让 org 在更多的地方使用，此解析器应该让每个人在任何地方都可以使用。这意味着
  • 它必须有一个宽泛的许可证。
  • 它既可以编译成原生代码，也可以编译成 wasm。
  • 我们将调查编译成 C 库以供其他代码原生链接。这更多是一个项目的 maybe 目标。

项目非目标

• 由于这将大大增加代码的复杂性，此项目将不包括 elisp 引擎。任何需要 elisp 引擎的功能将不会实现（例如，Emacs 支持在文档中嵌入 eval 表达式，但此解析器将永远不会支持该功能）。
• 此项目仅限于 org-mode 的 解析器。这限制了其范围大致相当于 (org-element-parse-buffer) 的输出。它不会将 org-mode 文档渲染为其他格式，如 HTML 或 LaTeX。

项目 maybe 目标

• table.el 支持。目前我们支持 org-mode 表格，但 org-mode 还允许使用 table.el 表格。到目前为止，在 org-mode 文档中使用它们的似乎相当不常见，因此这是一个低优先级的功能。

支持的版本

本项目针对的是内置于organic-test docker镜像中的Emacs和Org-mode版本。这个版本比随Emacs 29.1一起发布的Org-mode版本更新。然而，解析器本身并不依赖于Emacs或Org-mode，所以这仅对运行与上游Org-mode比较的自动化测试时的开发目的有意义。

使用此库

待办：添加关于如何将Organic作为库使用的章节（这是本项目的预期用途）。这将在我们有更多API稳定性之后添加，因为目前库正在大力开发中。

开发

解析二进制程序

该程序接受org-mode输入，可以是stdin上的流式输入，也可以是作为参数传入的文件路径。然后使用Organic解析它们，并将结果输出到stdout。这个程序仅作为开发工具。示例

cat /foo/bar.org | cargo run --bin parse

cargo build --profile release-lto
./target/release-lto/parse /foo/bar.org /lorem/ipsum.org

比较二进制程序

该程序接受org-mode输入，可以是stdin上的流式输入，也可以是作为参数传入的文件路径。然后使用Organic和官方Emacs Org-mode解析器解析它们，并比较解析结果。这个程序仅作为开发工具。由于org-mode是一个不断变化的目标，建议通过docker运行，因为我们已将org-mode版本固定到特定修订。示例

cat /foo/bar.org | ./scripts/run_docker_compare.bash

./scripts/run_docker_compare.bash /foo/bar.org /lorem/ipsum.org

不建议，因为它不是通过docker运行的

cat /foo/bar.org | cargo run --features compare --bin compare

cargo build --profile release-lto --features compare
./target/release-lto/compare /foo/bar.org /lorem/ipsum.org

运行测试

本存储库有三个级别的测试：标准测试、自动生成的测试和外部文档测试。

标准测试

这些是常规的手写rust测试。可以使用以下命令运行

make unittest

自动生成的测试

这些测试从org_mode_samples目录中的文件自动生成，并且它们仍然与rust/cargo测试框架集成。对于该文件夹中的每个org-mode文档，都会生成一个测试，该测试将使用Organic和官方Emacs Org-mode解析器解析文档，然后比较解析结果。任何偏差都视为失败。由于org-mode是一个不断变化的目标，建议在docker内部运行这些测试，因为organic-test docker镜像已固定到org-mode的特定修订。可以使用以下命令运行

make dockertest

外部文档测试

这些测试的功能与自动生成的测试相同，但它们没有与rust/cargo测试框架集成，并且涉及比较存储在本存储库之外的外部org-mode文档的解析。这使我们能够在不将大量org-mode文档拉入本存储库的情况下测试远更多的org-mode输入文档。运行这些测试的推荐方式仍然是通过docker，因为它将org-mode和测试文档固定到特定的git修订。可以使用以下命令运行

make foreign_document_test

许可证

本项目以公共领域等效的0BSD许可证发布，然而，本项目有一些许可方式宽松的非公共领域等效依赖，它们需要包含其版权声明和/或许可证文本。我不是律师，这也不是法律建议，但据我了解，如果您分发静态链接此库的二进制文件，您将需要遵守它们的条款，因为它们的代码也将链接到您的二进制文件。