1 个不稳定版本
0.1.0 | 2021年5月5日 |
---|
#2922 在 解析器实现
41 每月下载量
在 6 crates 中使用
99KB
2.5K SLoC
Verilization
Verilization 是一种用于定义二进制文件格式的序列化描述语言。与 Protocol Buffers 等其他序列化工具不同,序列化的 Verilization 数据不具备向前或向后兼容性。相反,它简化了从旧格式版本到新版本的转换,允许数据更紧凑,并对数据的底层形状有更多的控制。
目标
Verilization 的以下目标是主要的。
- 赋予用户对文件格式的最大控制权
- 以语言无关的方式定义格式
- 支持从旧版本格式轻松转换
其他较低级别的目标。
- 支持大整数字段
- 无需使用本地二进制文件即可嵌入到其他语言中
类型
以下类型被支持。
类型 | 编码 |
---|---|
struct 类型 |
按顺序编码每个字段 |
enum 类型 |
一个标签(以与 nat 相同的格式编码)后跟由标签表示的字段的编码 |
extern 类型 |
由目标语言编写的代码定义 |
结构体
使用多个版本定义 struct
类型。每个版本定义一系列字段。
struct Rectangle {
version 1 {
width: u32;
height: u32;
}
}
枚举
使用多个版本定义 enum
类型。每个版本定义一系列用作案例的字段。枚举值恰好由这些字段中的一个组成。
struct StringOrInt {
version 1 {
str: string;
num: int;
}
}
外部类型
在用户代码中定义 extern
类型。类型定义、转换和编解码器必须在目标语言中实现。
extern
类型可以声明可用于该类型的字面量。
extern MyString {
literal {
string;
}
}
支持以下字面量规范。
名称 | 示例 | 语法 | 注释 |
---|---|---|---|
整数 | 整数 [0, 256) | '整数'open_bracket 整数字面量? ','整数字面量?close_bracket 其中 `open_bracket : '[' |
单个字符 '<' 和代码 and close_bracket : ']' |
字符串 | 字符串 |
'字符串' |
字符串内容不能被限制。 |
序列 | 序列类型 T |
'序列'类型表达式 |
定义指定类型的序列。 |
情况 | 情况 Positive() |
'情况'标识符'(' [类型表达式{ ','类型表达式} ] ')' |
定义一个情况。如果名称不同,可以指定多个情况字面量。 |
记录 | 记录{a:A;b:B; } |
'记录' '{' {标识符':'类型表达式';' } '}' |
定义一个记录。 |
运行时库类型
运行时库提供了许多 extern
类型。
类型 | 字面量 | 编码 |
---|---|---|
{i,u}{8,16,32,64} |
类型范围内的整数 | 小端顺序的字节固定宽序列 |
int |
整数 | 可变长格式 |
nat |
非负整数 | 与 int 类似的格式,但没有符号位 |
字符串 |
字符串 | 长度为 nat 的字符串,后跟指定长度的 UTF-8 字节序列 |
list T |
T 的序列 | 长度为 nat 的序列,后跟 T |
option T |
两个情况 some(x) 和 none() |
一个字节 b 。如果 b 非零,则其后跟一个 T |
int
和 nat
的编码定义了一个小端顺序的比特序列。每个字节的最高位如果该数字中有更多字节则被设置。
这种编码是一个字节序列 [B0, ..., Bn],其中 Bi,7 = 1 当 i < n 且 Bn,7 = 0。这个字节序列等价于一个比特序列 [B0,0, ... B0,6, ..., Bn-1,0, ..., Bn-1,6] = [b0, ..., bm-1],其中 m = 6n。本质上,比特序列去除了用于确定序列何时结束的标志位,并按从最低到最高有效位的顺序对每个字节的剩余比特进行排序。比特序列映射如下
- 对于
int
类型,如果 bm-1 = 0,则 k = b0 * 20 + ... + bm - 2 * 2m-2 - 对于
int
类型,如果 bm-1 = 1,则 k = -(b0 * 20 + ... + bm - 2 * 2m-2) - 1 - 对于
nat
类型,k = b0 * 20 + ... + bm - 1 * 2m-1
版本控制
在以下示例中,用户有一个用户名和出生日期。
struct Person {
version 1 {
name: Name;
dob: Date;
}
}
struct Name {
version 1 {
firstName: string;
middleName: option string;
lastName: string;
}
}
然而,并非每个人都有 2 或 3 个名字。为了适应这种情况,我们可以创建一个新的版本,允许任意数量的名字。
struct Name {
version 1 {
...
}
version 2 {
names: list string;
}
}
对 Name
的这种修改意味着在格式的版本 2 中,Person
的 name
字段现在将使用 Name
的版本 2。但是,由于没有直接修改 Person
,版本 2 是自动创建的。在生成的代码中,用户应提供可以将 Name
从版本 1 升级到版本 2 的代码。然而,没有必要提供升级 Person
的此类代码。 Person
可以使用其字段的升级代码自动升级。
最终
版本化类型可以声明为 final
来指示不会添加该类型的任何新版本。这限制了类型到最后一个显式声明的版本,防止自动生成新版本。最终类型可能仅包含最终或非版本化类型的字段。
final struct FormatVersion {
version 1 {
major: nat;
}
}
泛型
泛型类型允许类型进行参数化。
final struct Pair(A, B) {
version 1 {
left: A;
right: B;
}
}
常量
常量允许定义在任意生成的语言之间共享的值。
字面量 | 示例 | 用法 |
---|---|---|
整数 | 88 |
extern 类型与整数 字面量 |
字符串 | "Hello World" |
extern 类型与字符串 字面量 |
序列 | [a,b,c] |
extern 类型与序列 字面量 |
记录 | {x= 1;y= 2; } |
struct 类型与extern 类型与记录 字面量 |
情况 | 名称(a) |
enum 类型与extern 类型与case Name 字面量 |
命令行
Verilization具有命令行界面。以下选项受到支持。
语言生成器
以下语言受到支持。
编译器绑定
Verilization编译器是用Rust编写的。它可以编译成WebAssembly,以便在其他语言中使用。这具有以下优势:工具可以分发(例如,作为NPM包、独立的JAR等),而不需要任何本地二进制文件。这些绑定公开了可以从运行时直接使用的接口,以及仅依赖于相关运行时的命令行界面。
目前,以下运行时提供了绑定。
- Node
lib.rs
:
Verilization编译器为各种语言生成序列化代码。
依赖关系
~2.5MB
~56K SLoC