SSD - 简单服务和数据描述

关于 - SSD是什么？

首先，它应该是一种描述数据结构和服务的格式。此外，它还提供了处理上述格式的工具，从而简化了编写自定义代码生成器的过程。

历史 - 我为什么要做这个？

在我曾经工作的公司之一，我们用Delphi编程，我们需要序列化一些结构。要在Delphi中序列化内容，你需要手动构建对象，这非常容易出错，并且令人烦恼。所以我用D语言、SDLang和模板引擎编写了一个小的（闭源）代码生成器。

几个月后，很明显，模板引擎使得某些事情更难维护和推理。因此，我决定用C#重写整个程序。这次我使用了一个自定义解析器，以便允许更流畅的数据文件，并通过C# DLLs构建生成器。这样，如果你想的话，仍然可以使用模板引擎，将其嵌入到DLL中并使用它。

我被允许开源所有东西，除了我们内部使用的自定义代码生成插件。源代码可以在以下位置找到：https://github.com/hardliner66/codegenerator

我仍然不是很满意，因为使用代码生成器进行跨平台的方式仍然很复杂，需要mono。经过一段时间，我开始更多地使用Rust，并发现了WebAssembly，这促使我开始第三次尝试。这次的目标是允许插件用wasm编写，以便人们可以用他们熟悉的任何语言编写生成器。

最初我给这个项目命名为SSDCG，代表简单服务与数据描述格式和代码生成器。但这个名字有点难记，而且重点始终更多地放在统一的数据描述语言上，代码生成是这个语言的主要用途。

该项目已经超越了最初的目标，不仅支持WASM，还支持Rhai（脚本语言）和三种不同的模板引擎，它们都可以使用相同的数据模型。一旦你的模型编写完成，你可以选择最适合你需求的技术来从模型中生成你想要的内容。

数据格式也经历了很多变化，从旧版本发展到支持描述数据类型、枚举、导入、具有函数和事件的服务，以及所有这些上的自定义属性，以实现更多定制。它被设计得类似于简化的Rust，因为我个人非常喜欢它的语法，而且这是自然的选择，因为整个项目都是用Rust编写的。

注意：重大变更！

只要crate版本低于1.0.0，就应预期会有重大变更。

迄今为止的重大变更

功能

• 自定义描述语言（基本功能已完成，但还有一些东西仍然缺失）
  • 导入
  • 数据类型
  • 枚举
  • 服务
  • 自定义属性
    • 这些可以用来实现语言中缺失的自定义功能
    • 一些功能将在以后添加，而另一些将始终依赖于属性，因为它们不够通用
  • 列表
    • 固定大小（property: 5 of u8）
    • 动态大小（property: list of u8）
  • 泛型
• 自动格式化
• 脚本语言
  • Rhai
  • 通过PyO3的Python
• 模板引擎
  • Handlebars
  • Tera
• Wasm（通过extism）
• 用于与其他工具（JSON、Yaml、TOML）一起使用的数据导出
• 使用原始数据（JSON、Yaml、TOML、Rsn）而不是预定义的ssd格式
  • 这允许使用相同的工具，即使在与其他地方的数据一起工作时也是如此
• 基本健全性检查

Cargo功能

• default是wasm、tera和handlebars
• tera启用对tera模板的支持
• handlebars启用对handlebars模板的支持
• wasm 启用对 wasm 插件的支持
• ron 启用对 ron 的支持
• all 启用一切

数据规范

它主要是“所见即所得”，如此处所示

• data/test.svc 查看描述语言的外观。

目前唯一的限制是，自动格式化始终将注释放在元素之后的右边。这意味着以下内容将格式化为：

data Test {
    a: i32, /// test
    b: i32,
}

测试它

data Test {
    a: i32,
    /// test
    b: i32,
}

测试它

要测试它，请安装命令、克隆存储库并使用以下命令：

ssd generate rhai example-generators/cpp-like.rhai data/test.svc

示例

您可以查看文件

• example-generators/cpp-like.rhai 查看生成器可能的样子。
• example-generators/cpp-like.tym 查看类型映射文件的外观。
• example-generators/simple.hbs 查看简单 handlebars 模板的外观。
• example-generators/simple.tera 查看简单 tera 模板的外观。
• example-generators/wasm-example/README.md 查看 Rust (wasm) 中的简单生成器可能的样子。

安装

可以通过 cargo 安装

cargo install --locked ssd

或从 发布页面 下载预构建包。

使用方法

通用

➜ ssd help
Simple Service Description

Usage: ssd [COMMAND]

Commands:
  debug     Print debug representation of the parsed file
  pretty    Pretty print the parsed file
  generate  Generate source code
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

生成

➜ ssd generate help
Generate source code

Usage: ssd generate <COMMAND>

Commands:
  rhai        Use a rhai based generator
  handlebars  Use a handlebars based template. https://handlebars.node.org.cn/
  tera        Use a tera based template. https://tera.netlify.app/
  wasm        Use a wasm based generator
  data        Output as serialized data for external use
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Rhai

➜ ssd generate rhai --help
Use a rhai based generator

Usage: ssd generate rhai [OPTIONS] <SCRIPT> <FILE>

Arguments:
  <SCRIPT>
          The script to use to generate the file

  <FILE>
          which file to use

Options:
  -d, --debug
          Enables debug mode (print and debug function in the script)

      --no-map
          do not use type mappings

      --typemap <TYPEMAP>
          A file containing type mappings.

          If a file with the same name as the script file, but with the extension tym, it will be used automatically.
          e.g.: If there is a file `/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get
          used automatically.

  -r, --raw
          use raw data file as input instead of the ssd data format

  -o, --out <OUT>
          The file which should get written with the output from the generator

  -h, --help
          Print help (see a summary with '-h')

Handlebars

别名：ssd generate hbs

➜ ssd generate handlebars --help
Use a handlebars based template. https://handlebars.node.org.cn/

Usage: ssd generate handlebars [OPTIONS] <TEMPLATE> <FILE>

Arguments:
  <TEMPLATE>
          The template to use to generate the file

  <FILE>
          which file to use

Options:
      --no-map
          do not use type mappings

      --typemap <TYPEMAP>
          A file containing type mappings.

          If a file with the same name as the script file, but with the extension tym, it will be used automatically.
          e.g.: If there is a file `/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get
          used automatically.

  -r, --raw
          use raw data file as input instead of the scd data format

  -o, --out <OUT>
          The file which should get written with the output from the generator

  -h, --help
          Print help (see a summary with '-h')

Tera

➜ ssd generate tera --help
Use a tera based template. https://tera.netlify.app/

Usage: ssd generate tera [OPTIONS] <TEMPLATE_DIR> <TEMPLATE_NAME> <FILE>

Arguments:
  <TEMPLATE_DIR>
          Glob path for where to search for templates

  <TEMPLATE_NAME>
          The template to use to generate the file

  <FILE>
          which file to use

Options:
      --no-map
          do not use type mappings

      --typemap <TYPEMAP>
          A file containing type mappings.

          If a file with the same name as the script file, but with the extension tym, it will be used automatically.
          e.g.: If there is a file `/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get
          used automatically.

  -r, --raw
          use raw data file as input instead of the scd data format

  -o, --out <OUT>
          The file which should get written with the output from the generator

  -h, --help
          Print help (see a summary with '-h')

Wasm

➜ ssd generate wasm --help
Use a wasm based generator

Usage: ssd generate wasm [OPTIONS] <WASM> <FILE>

Arguments:
  <WASM>
          The wasm plugin to use to generate the file

  <FILE>
          which file to use

Options:
      --no-map
          do not use type mappings

      --typemap <TYPEMAP>
          A file containing type mappings.

          If a file with the same name as the script file, but with the extension tym, it will be used automatically.
          e.g.: If there is a file `/generator/script.rhai` and a corresponding `/generator/script.tym`, it will get
          used automatically.

  -r, --raw
          use raw data file as input instead of the scd data format

  -o, --out <OUT>
          The file which should get written with the output from the generator

  -h, --help
          Print help (see a summary with '-h')

Python / PyO3

通过 pip 安装

pip3 install py_ssd

使用方法

>>> import py_ssd
>>> model = py_ssd.parse_file(".", "./data/test.svc")
[src/parser.rs:509] key = "Rect"

# the namespace is generated from the file path (second parameter),
# with the base path removed (first parameter)
>>> model['namespace']
{'components': ['data', 'test']}

>>> model['data_types'].keys()
dict_keys(['Rect'])

>>> model['data_types']['Rect']['properties']['x']
{'typ': {'components': ['i32']}, 'attributes': [{'name': {'components': ['test']}, 'parameters': []}], 'comments': []}