colfer
Version 1.8.1
Colfer は、速度とサイズに関して最適化されたバイナリ シリアル化形式です。
プロジェクトのコンパイラcolf(1)スキーマ定義からデータ構造のマーシャルおよびアンマーシャルまでのソース コードを生成します。
これは、パブリック ドメインにリリースされた無料で制限のないソフトウェアです。この形式はProtocol Bufferからインスピレーションを得ています。
事前に構築されたコンパイラーをダウンロードするか、 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 | 長さ † | 番号 ‡ |
| int32 | int32_t | int32 | 整数 | 番号 |
| int64 | int64_t | int64 | 長さ | 番号 ‡ |
| float32 | フロート | float32 | フロート | 番号 |
| float64 | ダブル | float64 | ダブル | 番号 |
| タイムスタンプ | タイムスペック | 時間.時間 †† | 時間.インスタント | 日付 + 番号 |
| 文章 | const char* + size_t | 弦 | 弦 | 弦 |
| バイナリ | uint8_t* + size_t | []バイト | バイト[] | Uint8Array |
| リスト | * + サイズ_t | スライス | 配列 | 配列 |
リストには、浮動小数点、テキスト、バイナリ、またはデータ構造が含まれる場合があります。
Colfer は、ネットワーク I/O やバルク ストリームなどの信頼できないデータ ソースに適しています。マーシャリングとアンマーシャリングには、予測可能なメモリ消費量を確保するためのサイズ保護が組み込まれています。この形式は設計によりメモリ爆弾を防止します。
マーシャラーは、データ入力に関係なく、不正な出力を生成することはできません。いかなる場合でも、アンマーシャラーはシリアルの境界外を読み取ることはできません。ファズテストでは、まだ揮発性は明らかにされていません。計算能力のある方は大歓迎です。
名前の変更はシリアル化形式には影響しません。非推奨のフィールドは、その使用を明確に阻止するために名前を変更する必要があります。下位互換性を確保するには、新しいフィールドを Colfer 構造体の最後に追加する必要があります。したがって、フィールドの数はスキーマのバージョンとして見ることができます。
Colfer は、信頼性を損なうことなく、最速かつ最小のフォーマットを目指しています。比較についてはベンチマーク Wiki を参照してください。最適化されていないパフォーマンスはバグのように扱われます。
