「Data encoding ライブラリ」の版間の差分

提供: tezos-wiki
移動先: 案内、 検索
(ページの作成:「.. _data_encoding: = The <code>data_encoding</code> library = Throughout the Tezos protocol, data is serialized so that it can be used via RPC, written to disk, or plac...」)
 
 
1行目: 1行目:
−
.. _data_encoding:
+
.. _data_encoding：
  
−
= The <code>data_encoding</code> library =
+
= <code> data_encoding </code>ライブラリ=
  
−
Throughout the Tezos protocol, data is serialized so that it can be used via RPC, written to disk, or placed in a block. This serialization/de-serialization is handled via the :package:<code>tezos-data-encoding</code> library by providing a set primitive encodings and a variety of combinators.
+
Tezosプロトコル全体を通して、データはRPCを介して、ディスクに書き込まれたり、ブロックに配置されるようにシリアル化されています。このシリアライゼーション/デシリアライゼーションは、set primitiveエンコーディングとさまざまなコンビネータを提供することによって、：package：<code> tezos-data-encoding </code>ライブラリで処理されます。
  
−
== Examples/Tutorial ==
+
==例/チュートリアル==
  
−
Encoding an integer <sub><sub><sub>~</sub></sub><sub><sub><sub>~</sub></sub></sub>~</sub>
+
整数<sub> <sub>?</sub> </sub> </sub>?</sub>?</sub>
  
−
Integers are defined as other concrete data types with a generic encoding type <code>type 'a encoding</code>. This means that it is an encoding to/from type <code>int</code>. There are a variety of ways to encode an integer, depending on what binary serialization you want to achieve:
+
整数は、汎用エンコーディングタイプ<code> type 'a encoding </code>を持つ他の具体的なデータ型として定義されます。これは、<code> int </code>型への/からの符号化であることを意味します。達成したいバイナリのシリアル化に応じて、整数をエンコードする方法はさまざまです。
  
−
* <code>Data_encoding.int8</code>
+
* <code> Data_encoding.int8 </code>
−
* <code>Data_encoding.uint8</code>
+
* <code> Data_encoding.uint8 </code>
−
* <code>Data_encoding.int16</code>
+
* <code> Data_encoding.int16 </code>
−
* <code>Data_encoding.uint16</code>
+
* <code> Data_encoding.uint16 </code>
−
* <code>Data_encoding.int31</code>
+
* <code> Data_encoding.int31 </code>
−
* <code>Data_encoding.int32</code>
+
* <code> Data_encoding.int32 </code>
−
* <code>Data_encoding.int64</code>
+
* <code> Data_encoding.int64 </code>
  
−
For example, an encoding that represents a 31 bit integer has type <code>Data_encoding.int31 = int Data_encoding.encoding</code>.
+
たとえば、31ビット整数を表すエンコーディングは、<code> Data_encoding.int31 = int Data_encoding.encoding </code>型です。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>let int31_encoding = Data_encoding.int31</pre>
+
<pre> let int31_encoding = Data_encoding.int31 </pre>
−
Encoding an object <sub><sub>~</sub><sub><sub><sub><sub>~</sub></sub></sub></sub></sub>~~
+
オブジェクトのエンコーディング<sub>?</sub> <sub> <sub> <sub> <sub>?</sub> </sub> </sub> </sub> ~~
  
−
Encoding a single integer is fairly uninteresting. The Dataencoding library provides a number of combinators that can be used to build more complicated objects. Consider the type that represents an interval from the first number to the second:
+
1つの整数をエンコーディングするのは面白くありません。 Dataencodingライブラリには、より複雑なオブジェクトを構築するために使用できるいくつかのコンビネータが用意されています。最初の数値から2番目の数値までの間隔を表す型を考えてみましょう。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>type interval = int64 * int64</pre>
+
<pre> type interval = int64 * int64 </pre>
−
We can define an encoding for this type as:
+
このタイプのエンコーディングを次のように定義できます。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>let interval_encoding =
+
<pre> let interval_encoding =
−
   Data_encoding.(obj2 (req &quot;min&quot; int64) (req &quot;max&quot; int64))</pre>
+
   Data_encoding（obj2（req "min" int64）（req "max" int64））</pre>
−
In the example above we construct a new value <code>interval_encoding</code> by combining two int64 integers using the <code>obj2</code> constructor.
+
上記の例では、<code> obj2 </code>コンストラクタを使用して2つのint64整数を組み合わせることで、新しい値<code> interval_encoding </code>を作成します。
  
−
The library provides different constructors, i.e.?for objects that have no data (<code>Data_encoding.empty</code>), constructors for object up to 10 fields, constructors for tuples, list, etc.
+
ライブラリは、データを持たないオブジェクト（<code> Data_encoding.empty </code>）、最大10個のフィールドのオブジェクトのコンストラクタ、タプル、リストなどのコンストラクタなどの異なるコンストラクタを提供します。
  
−
These are serialized to binary by converting each internal object to binary and placing them in the order of the original object and to JSON as a JSON object with field names.
+
これらは、各内部オブジェクトをバイナリに変換し、元のオブジェクトの順番に配置し、フィールド名を持つJSONオブジェクトとしてJSONに配置することによって、バイナリにシリアル化されます。
  
−
Lists, arrays, and options <sub><sub><sub><sub><sub><sub><sub><sub><sub><sub>~</sub></sub></sub></sub></sub></sub></sub></sub></sub>~</sub>~~
+
リスト、配列、およびオプション<sub> <sub> <sub> <sub> <sub> <sub> <sub> <sub> <sub>?</sub> </sub> </sub> / sub> </sub> </sub> </sub> </sub>
  
−
List, Arrays and options types can by built on top of ground data types.
+
リスト、配列、およびオプションの型は、地上のデータ型の上に構築することができます。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>type interval_list = interval list
+
<pre> type interval_list =インターバルリスト
  
−
type interval_array = interval array
+
タイプinterval_array =区間配列
 +
タイプinterval_option =間隔オプション</pre>
 +
これらのタイプのエンコーダは
  
−
type interval_option = interval option</pre>
+
..コード:: ocaml
−
And the encoders for these types as
 
  
−
.. code:: ocaml
+
<pre> let interval_list_encoding = Data_encoding.list interval_encoding
−
 
 
−
<pre>let interval_list_encoding = Data_encoding.list interval_encoding
 
 
let interval_array_encoding = Data_encoding.array interval_encoding
 
let interval_array_encoding = Data_encoding.array interval_encoding
−
let interval_option_encoding = Data_encoding.option interval_encoding</pre>
+
let interval_option_encoding = Data_encoding.option interval_encoding </pre>
−
Union types <sub><sub><sub>~</sub></sub></sub>~<sub>~</sub>
+
結合タイプ<sub> <sub>?</sub> </sub> </sub>?<sub>?</sub>
  
−
The Tezos codebase makes heavy use of variant types. Consider the following variant type:
+
Tezosコードベースは、バリアント型を頻繁に使用します。次のバリアント型を考えてみましょう。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>type variant = B of bool
+
<pre>型の変種= boolのB
−
             | S of string</pre>
+
             |文字列</pre>
−
Encoding for this types can be expressed as:
+
このタイプのエンコーディングは、次のように表すことができます。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>let variant_encoding =
+
<pre> let variant_encoding =
−
   Data_encoding.(union ~tag_size:`Uint8
+
   Data_encoding。（union?tag_size： `Uint8
−
                   [ case
+
                   [ケース
−
                       bool
+
                       ブール
−
                       (function B b -&gt; Some b | _ -&gt; None)
+
                       （関数B b→一部b | _→なし）
−
                       (fun b -&gt; B b) ;
+
                       （fun b→B b）。
−
                     case
+
                     場合
−
                       string
+
                       文字列
−
                       (function S s -&gt; Some s | _ -&gt; None)
+
                       （関数S s - > Some s | _ - > None）
−
                       (fun s -&gt; S s) ])</pre>
+
                       （fun s - > s s）]）</pre>
−
This variant encoding is a bit more complicated. Let’s look at the parts of the type:
+
この変形エンコーディングはもう少し複雑です。タイプの部分を見てみましょう：
  
−
* We include an optimization hint to the binary encoding to inform it of the number of elements we expect in the tag. In most cases, we can use :literal:<code>\</code>Uint8`, which allows you to have up to 256 possible cases (default).
+
*バイナリエンコーディングへの最適化ヒントを含めて、タグに期待する要素の数を通知します。ほとんどの場合、literal：<code> \ </code> Uint8`を使用できます。これにより、最大256のケース（デフォルト）を持つことができます。
−
* We provide a function to wrap the datatype. The encoding works by repeatedly trying to decode the datatype using these functions until one returns <code>Some payload</code>. This payload is then encoded using the dataencoding specified.
+
*データ型をラップする関数を提供します。エンコーディングは、<code> Some payload </code>を返すまで、これらの関数を使用してデータ型を繰り返しデコードしようとします。このペイロードは、次に指定されたデータ符号化を使用して符号化される。
−
* We specify a function from the encoded type to the actual datatype.
+
*コード化された型から実際のデータ型に関数を指定します。
  
−
Since the library does not provide an exhaustive check on these constructors, the user must be careful when constructing unin types to avoid unfortunate runtime failures.
+
ライブラリはこれらのコンストラクタを徹底的にチェックするわけではないので、不幸なランタイムエラーを避けるためにunin型を構築するときは注意が必要です。
  
−
== How the Dataencoding module works ==
+
== Dataencodingモジュールの仕組み==
  
−
This section is 100% optional. You do not need to understand this section to use the library.
+
このセクションは100％オプションです。このセクションを理解してライブラリを使用する必要はありません。
  
−
The library uses GADTs to provide type-safe serialization/de-serialization. From there, a runtime representation of JSON objects is parsed into the type-safe version.
+
ライブラリはGADTを使用して、型保証型のシリアル化/逆シリアル化を提供します。そこから、JSONオブジェクトのランタイム表現がタイプセーフなバージョンに解析されます。
  
−
First we define an untyped JSON AST:
+
最初に、型なしのJSON ASTを定義します。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
−
<pre>type json =
+
<pre>タイプjson =
−
   [ `O of (string * json) list
+
   [`（string * json）リストのうちのO
−
   | `Bool of bool
+
   | `ブールのブール
−
   | `Float of float
+
   | `フロートのフロート
−
   | `A of json list
+
   | `jsonリストのA
 
   | `Null
 
   | `Null
−
   | `String of string ]</pre>
+
   | `string of string] </pre>
−
This is then parsed into a typed AST ( we eliminate several cases for clarity):
+
これは型付きASTに解析されます（わかりやすくするためにいくつかのケースを削除しています）。
  
−
.. code:: ocaml
+
..コード:: ocaml
  
 
<pre>type 'a desc =
 
<pre>type 'a desc =
139行目: 138行目:
 
   | Def : { name : string ;
 
   | Def : { name : string ;
 
             encoding : 'a t } -&gt; 'a desc</pre>
 
             encoding : 'a t } -&gt; 'a desc</pre>
−
* The first set of constructors define all ground types.
+
*コンストラクタの最初のセットはすべての地形を定義します。
−
* The constructors for <code>Bytes</code>, <code>String</code> and <code>String_enum</code> includes a length fields in order to provide safe binary serialization.
+
* <code> Bytes </code>、<code> String </code>および<code> String_enum </code>のコンストラクタには安全なバイナリのシリアル化を提供するための長さフィールドが含まれています。
−
* The constructors for <code>Array</code> and <code>List</code> are used by the combinators we saw earlier.
+
* <code> Array </code>と<code> List </code>のコンストラクタは、先ほど見たコンビネータで使用されています。
−
* The <code>Obj</code> and <code>Objs</code> constructors create JSON objects. These are wrapped in the <code>Conv</code> constructor to remove nesting that results when these constructors are used naively.
+
* <code> Obj </code>コンストラクタと<code> Objs </code>コンストラクタはJSONオブジェクトを作成します。これらのコンストラクタは、<code> Conv </code>コンストラクタでラップされ、これらのコンストラクタが順不同で使用されたときに生成されるネストを削除します。
−
* The <code>Mu</code> constructor is used to create self-referential definitions.
+
*自己参照定義を作成するには、<code> Mu </code>コンストラクタを使用します。
−
* The <code>Conv</code> constructor allows you to clean up a nested definition or compute another type from an existing one.
+
* <code> Conv </code>コンストラクタを使用すると、ネストされた定義をクリーンアップしたり、既存のタイプから別のタイプを計算したりすることができます。
−
* The <code>Describe</code> and <code>Def</code> constructors are used to add documentation
+
* <code> Describe </code>コンストラクタと<code> Def </code>コンストラクタは、ドキュメントの追加に使用されます
  
−
The library also provides various wrappers and convenience functions to make constructing these objects easier. Reading the documentation in the <code>mli file &lt;../api/odoc/tezos-data-encoding/Tezos_data_encoding/Data_encoding/index.html&gt;</code>__ should orient you on how to use these functions and their purposes.
+
ライブラリには、これらのオブジェクトを簡単に構築するためのさまざまなラッパーと便利な関数も用意されています。 <code> mliファイル</api / odoc / tezos-data-encoding / Tezos_data_encoding / Data_encoding / index.html＆gt; </code> __のドキュメントを読むと、これらの関数の使い方と目的。

2018年5月31日 (木) 00:29時点における最新版

.. _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; __のドキュメントを読むと、これらの関数の使い方と目的。

「http://tezos-wiki.jp/wiki/index.php?title=Data_encoding_ライブラリ&oldid=26278」から取得