colfer
Version 1.8.1
Colfer 是一种针对速度和大小进行优化的二进制序列化格式。
该项目的编译器colf(1)生成从模式定义到编组和解组数据结构的源代码。
这是发布到公共领域的免费且不受阻碍的软件。该格式的灵感来自于 Proto col Buf fer s。
下载预构建的编译器或运行go get -u github.com/pascaldekloe/colfer/cmd/colf自己制作一个。 Homebrew 用户还可以brew install colfer 。
当不带参数调用时，该命令会打印自己的手册。
NAME
colf — compile Colfer schemas
SYNOPSIS
colf [-h]
colf [-vf] [-b directory] [-p package]
[-s expression] [-l expression] C [file ...]
colf [-vf] [-b directory] [-p package] [-t files]
[-s expression] [-l expression] Go [file ...]
colf [-vf] [-b directory] [-p package] [-t files]
[-x class] [-i interfaces] [-c file]
[-s expression] [-l expression] Java [file ...]
colf [-vf] [-b directory] [-p package]
[-s expression] [-l expression] JavaScript [file ...]
DESCRIPTION
The output is source code for either C, Go, Java or JavaScript.
For each operand that names a file of a type other than
directory, colf reads the content as schema input. For each
named directory, colf reads all files with a .colf extension
within that directory. If no operands are given, the contents of
the current directory are used.
A package definition may be spread over several schema files.
The directory hierarchy of the input is not relevant to the
generated code.
OPTIONS
-b directory
Use a base directory for the generated code. (default ".")
-c file
Insert a code snippet from a file.
-f Normalize the format of all schema input on the fly.
-h Prints the manual to standard error.
-i interfaces
Make all generated classes implement one or more interfaces.
Use commas as a list separator.
-l expression
Set the default upper limit for the number of elements in a
list. The expression is applied to the target language under
the name ColferListMax. (default "64 * 1024")
-p package
Compile to a package prefix.
-s expression
Set the default upper limit for serial byte sizes. The
expression is applied to the target language under the name
ColferSizeMax. (default "16 * 1024 * 1024")
-t files
Supply custom tags with one or more files. Use commas as a list
separator. See the TAGS section for details.
-v Enable verbose reporting to standard error.
-x class
Make all generated classes extend a super class.
TAGS
Tags, a.k.a. annotations, are source code additions for structs
and/or fields. Input for the compiler can be specified with the
-t option. The data format is line-oriented.
<line> :≡ <qual> <space> <code> ;
<qual> :≡ <package> '.' <dest> ;
<dest> :≡ <struct> | <struct> '.' <field> ;
Lines starting with a '#' are ignored (as comments). Java output
can take multiple tag lines for the same struct or field. Each
code line is applied in order of appearance.
EXIT STATUS
The command exits 0 on success, 1 on error and 2 when invoked
without arguments.
EXAMPLES
Compile ./io.colf with compact limits as C:
colf -b src -s 2048 -l 96 C io.colf
Compile ./*.colf with a common parent as Java:
colf -p com.example.model -x com.example.io.IOBean Java
BUGS
Report bugs at <https://github.com/pascaldekloe/colfer/issues>.
Text validation is not part of the marshalling and unmarshalling
process. C and Go just pass any malformed UTF-8 characters. Java
and JavaScript replace unmappable content with the '?' character
(ASCII 63).
SEE ALSO
protoc(1), flatc(1)
建议将生成的源代码提交到相应的版本控制中，以保持构建一致性并最大限度地减少编译器安装的需要。或者，您可以使用 Maven 插件。
< plugin >
< groupId >net.quies.colfer</ groupId >
< artifactId >colfer-maven-plugin</ artifactId >
< version >1.11.2</ version >
< configuration >
< packagePrefix >com/example</ packagePrefix >
</ configuration >
</ plugin >数据结构在.colf文件中定义。该格式非常不言自明。
// Package demo offers a demonstration.
// These comment lines will end up in the generated code.
package demo
// Course is the grounds where the game of golf is played.
type course struct {
ID uint64
name text
holes []hole
image binary
tags []text
}
type hole struct {
// Lat is the latitude of the cup.
lat float64
// Lon is the longitude of the cup.
lon float64
// Par is the difficulty index.
par uint8
// Water marks the presence of water.
water bool
// Sand marks the presence of sand.
sand bool
}
查看生成的 C、Go、Java 或 JavaScript 代码是什么样子的。
下表显示了 Colfer 数据类型如何应用于每种语言。
| 科尔弗 | C | 去 | 爪哇 | JavaScript |
|---|---|---|---|---|
| 布尔值 | 字符 | 布尔值 | 布尔值 | 布尔值 |
| uint8 | uint8_t | uint8 | 字节 † | 数字 |
| uint16 | uint16_t | uint16 | 短的 † | 数字 |
| uint32 | uint32_t | uint32 | 整数 † | 数字 |
| uint64 | uint64_t | uint64 | 长的 † | 数字 ‡ |
| 整型32 | int32_t | 整型32 | 整数 | 数字 |
| 整型64 | int64_t | 整型64 | 长的 | 数字 ‡ |
| 浮动32 | 漂浮 | 浮动32 | 漂浮 | 数字 |
| 浮动64 | 双倍的 | 浮动64 | 双倍的 | 数字 |
| 时间戳 | 时间规范 | 时间.时间 †† | 时间.即时 | 日期+数字 |
| 文本 | 常量 char* + size_t | 细绳 | 细绳 | 细绳 |
| 二进制 | uint8_t* + size_t | []字节 | 字节[] | Uint8Array |
| 列表 | * + 尺寸_t | 片 | 大批 | 大批 |
列表可以包含浮点、文本、二进制或数据结构。
Colfer 适用于不受信任的数据源，例如网络 I/O 或批量流。编组和解组带有内置的大小保护，以确保可预测的内存消耗。该格式旨在防止内存炸弹。
无论数据输入如何，编组器都不会产生格式错误的输出。在任何情况下，解组器都不得在序列的范围之外进行读取。模糊测试尚未揭示任何波动性。计算能力受到欢迎。
名称更改不会影响序列化格式。应重命名已弃用的字段，以明确阻止其使用。为了向后兼容，必须将新字段添加到 colfer 结构的末尾。因此，字段的数量可以被视为模式版本。
Colfer 的目标是在不影响可靠性的情况下成为最快、最小的格式。请参阅基准 wiki 进行比较。次优性能被视为错误。
