Data encoding ライブラリ

提供: tezos-wiki
移動先: 案内検索

.. _data_encoding:

data_encoding ライブラリ[編集]

Tezosプロトコル全体を通して、データはRPCを介して、ディスクに書き込まれたり、ブロックに配置されるようにシリアル化されています。このシリアライゼーション/デシリアライゼーションは、set primitiveエンコーディングとさまざまなコンビネータを提供することによって、:package: tezos-data-encoding ライブラリで処理されます。

例/チュートリアル[編集]

整数 ? </sub>?</sub>?</sub>

整数は、汎用エンコーディングタイプ type 'a encoding を持つ他の具体的なデータ型として定義されます。これは、 int 型への/からの符号化であることを意味します。達成したいバイナリのシリアル化に応じて、整数をエンコードする方法はさまざまです。

  • Data_encoding.int8
  • Data_encoding.uint8
  • Data_encoding.int16
  • Data_encoding.uint16
  • Data_encoding.int31
  • Data_encoding.int32
  • Data_encoding.int64

たとえば、31ビット整数を表すエンコーディングは、 Data_encoding.int31 = int Data_encoding.encoding 型です。

..コード:: ocaml

 let int31_encoding = Data_encoding.int31 

オブジェクトのエンコーディング? ? ~~

1つの整数をエンコーディングするのは面白くありません。 Dataencodingライブラリには、より複雑なオブジェクトを構築するために使用できるいくつかのコンビネータが用意されています。最初の数値から2番目の数値までの間隔を表す型を考えてみましょう。

..コード:: ocaml

 type interval = int64 * int64 

このタイプのエンコーディングを次のように定義できます。

..コード:: ocaml

 let interval_encoding =
  Data_encoding(obj2(req "min" int64)(req "max" int64))

上記の例では、 obj2 コンストラクタを使用して2つのint64整数を組み合わせることで、新しい値 interval_encoding を作成します。

ライブラリは、データを持たないオブジェクト( Data_encoding.empty )、最大10個のフィールドのオブジェクトのコンストラクタ、タプル、リストなどのコンストラクタなどの異なるコンストラクタを提供します。

これらは、各内部オブジェクトをバイナリに変換し、元のオブジェクトの順番に配置し、フィールド名を持つJSONオブジェクトとしてJSONに配置することによって、バイナリにシリアル化されます。

リスト、配列、およびオプション ? / sub>

リスト、配列、およびオプションの型は、地上のデータ型の上に構築することができます。

..コード:: ocaml

 type interval_list =インターバルリスト

タイプinterval_array =区間配列
タイプinterval_option =間隔オプション

これらのタイプのエンコーダは

..コード:: ocaml

 let interval_list_encoding = Data_encoding.list interval_encoding
let interval_array_encoding = Data_encoding.array interval_encoding
let interval_option_encoding = Data_encoding.option interval_encoding 

結合タイプ ? ??

Tezosコードベースは、バリアント型を頻繁に使用します。次のバリアント型を考えてみましょう。

..コード:: ocaml

型の変種= boolのB
             |文字列

このタイプのエンコーディングは、次のように表すことができます。

..コード:: ocaml

 let variant_encoding =
  Data_encoding。(union?tag_size: `Uint8
                   [ケース
                       ブール
                       (関数B b→一部b | _→なし)
                       (fun b→B b)。
                     場合
                       文字列
                       (関数S s - > Some s | _ - > None)
                       (fun s - > s s)])

この変形エンコーディングはもう少し複雑です。タイプの部分を見てみましょう:

  • バイナリエンコーディングへの最適化ヒントを含めて、タグに期待する要素の数を通知します。ほとんどの場合、literal: \ Uint8`を使用できます。これにより、最大256のケース(デフォルト)を持つことができます。
  • データ型をラップする関数を提供します。エンコーディングは、 Some payload を返すまで、これらの関数を使用してデータ型を繰り返しデコードしようとします。このペイロードは、次に指定されたデータ符号化を使用して符号化される。
  • コード化された型から実際のデータ型に関数を指定します。

ライブラリはこれらのコンストラクタを徹底的にチェックするわけではないので、不幸なランタイムエラーを避けるためにunin型を構築するときは注意が必要です。

Dataencodingモジュールの仕組み[編集]

このセクションは100%オプションです。このセクションを理解してライブラリを使用する必要はありません。

ライブラリはGADTを使用して、型保証型のシリアル化/逆シリアル化を提供します。そこから、JSONオブジェクトのランタイム表現がタイプセーフなバージョンに解析されます。

最初に、型なしのJSON ASTを定義します。

..コード:: ocaml

タイプjson =
  [`(string * json)リストのうちのO
  | `ブールのブール
  | `フロートのフロート
  | `jsonリストのA
  | `Null
  | `string of string] 

これは型付きASTに解析されます(わかりやすくするためにいくつかのケースを削除しています)。

..コード:: ocaml

type 'a desc =
  | Null : unit desc
  | Empty : unit desc
  | Bool : bool desc
  | Int64 : Int64.t desc
  | Float : float desc
  | Bytes : Kind.length -> MBytes.t desc
  | String : Kind.length -> string desc
  | String_enum : Kind.length * (string * 'a) list -> 'a desc
  | Array : 'a t -> 'a array desc
  | List : 'a t -> 'a list desc
  | Obj : 'a field -> 'a desc
  | Objs : Kind.t * 'a t * 'b t -> ('a * 'b) desc
  | Tup : 'a t -> 'a desc
  | Union : Kind.t * tag_size * 'a case list -> 'a desc
  | Mu : Kind.enum * string * ('a t -> 'a t) -> 'a desc
  | Conv :
      { proj : ('a -> 'b) ;
        inj : ('b -> 'a) ;
        encoding : 'b t ;
        schema : Json_schema.schema option } -> 'a desc
  | Describe :
      { title : string option ;
        description : string option ;
        encoding : 'a t } -> 'a desc
  | Def : { name : string ;
            encoding : 'a t } -> 'a desc
  • コンストラクタの最初のセットはすべての地形を定義します。
  • Bytes String および String_enum のコンストラクタには安全なバイナリのシリアル化を提供するための長さフィールドが含まれています。
  • Array List のコンストラクタは、先ほど見たコンビネータで使用されています。
  • Obj コンストラクタと Objs コンストラクタはJSONオブジェクトを作成します。これらのコンストラクタは、 Conv コンストラクタでラップされ、これらのコンストラクタが順不同で使用されたときに生成されるネストを削除します。
  • 自己参照定義を作成するには、 Mu コンストラクタを使用します。
  • Conv コンストラクタを使用すると、ネストされた定義をクリーンアップしたり、既存のタイプから別のタイプを計算したりすることができます。
  • Describe コンストラクタと Def コンストラクタは、ドキュメントの追加に使用されます

ライブラリには、これらのオブジェクトを簡単に構築するためのさまざまなラッパーと便利な関数も用意されています。 mliファイル</api / odoc / tezos-data-encoding / Tezos_data_encoding / Data_encoding / index.html&gt; __のドキュメントを読むと、これらの関数の使い方と目的。