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 進行比較。次優性能被視為錯誤。
