# 7.3.2. 出力形式

## 7.3.2.1. 概要

コマンドは実行結果をJSONまたはMessagePack、XML、TSVのどれかで出力します。

JSONとMessagePackの出力は同じ構造になっています。XMLとTSVはそれぞれ独自の構造になっています。

JSONまたはMessagePackの利用を推奨します。XMLは目視で結果を確認する時に便利です。TSVは特殊な用途では有用です。通常はTSVを使う必要はありません。

## 7.3.2.2. JSONとMessagePack

このセクションではJSONとMessagePack形式を使った時のコマンド実行結果の構造を説明します。MessagePackはバイナリー形式なのでここでは構造を示すためにJSONを使います。バイナリー形式はドキュメントには向いていません。

JSON形式、MessagePack形式のときは以下のような構造になります:

    [HEADER, BODY]

実行例:

    [
      [
        0,
        1337566253.89858,
        0.000355720520019531
      ],
      [
        [
          [
            1
          ],
          [
            [
              "_id",
              "UInt32"
            ],
            [
              "_key",
              "ShortText"
            ],
            [
              "content",
              "Text"
            ],
            [
              "n_likes",
              "UInt32"
            ]
          ],
          [
            2,
            "Groonga",
            "I started to use groonga. It's very fast!",
            10
          ]
        ]
      ]
    ]

この例では、以下の部分が `HEADER` に相当します:

    [
      0,
      1337566253.89858,
      0.000355720520019531
    ]

`BODY` に相当する部分は以下です:

    [
      [
        [
          1
        ],
        [
          [
            "_id",
            "UInt32"
          ],
          [
            "_key",
            "ShortText"
          ],
          [
            "content",
            "Text"
          ],
          [
            "n_likes",
            "UInt32"
          ]
        ],
        [
          2,
          "Groonga",
          "I started to use groonga. It's very fast!",
          10
        ]
      ]
    ]

### 7.3.2.2.1. `HEADER`

`HEADER` は配列です。 `HEADER` の内容にはいくつかのパターンがあります。

#### 7.3.2.2.1.1. 成功した場合

コマンドが成功した場合は `HEADER` には3つの要素があります:

    [0, UNIX_TIME_WHEN_COMMAND_IS_STARTED, ELAPSED_TIME]

最初の値は常に `0` です。

`UNIX_TIME_WHEN_COMMAND_IS_STARTED` はコマンドの実行が始まったときの時刻です。時刻は1970-01-01 00:00:00から経過した秒数で表現されています。 `ELAPSED_TIME` はコマンドの実行にかかった時間です。単位は秒です。 `UNIX_TIME_WHEN_COMMAND_IS_STARTED` も `ELAPSED_TIME` も浮動小数点数です。小数部分はナノ秒を表します。

#### 7.3.2.2.1.2. エラーの場合

エラーの場合、 `HEADER` には4個または5個の要素があります:

    [
      RETURN_CODE,
      UNIX_TIME_WHEN_COMMAND_IS_STARTED,
      ELAPSED_TIME,
      ERROR_MESSAGE,
      ERROR_LOCATION
    ]

`ERROR_LOCATION` は `HEADER` には含まれないかもしれませんが、他の4個の要素は常に含まれます。

`RETURN_CODE` は0ではない値です。リターンコードの詳細は リターンコード を見てください。

`UNIX_TIME_WHEN_COMMAND_IS_STARTED` と `ELAPSED_TIME` は成功した時と同じです。

`ERROR_MESSAGE` はエラーメッセージです。文字列です。

`ERROR_LOCATION` は存在しないことがあります。もし、エラーが発生した場所の情報を収集できていた場合は `ERROR_LOCATION` が含まれます。 `ERROR_LOCATION` は配列です。 `ERROR_LOCATION` は1個または2個の要素を含みます:

    [
      LOCATION_IN_GROONGA,
      LOCATION_IN_INPUT
    ]

`LOCATION_IN_GROONGA` はGroonga内でエラーが発生したソースコードの場所です。この情報はGroonga開発者には役に立ちますが、ユーザーの役には立ちません。 `LOCATION_IN_GROONGA` は配列です。 `LOCATION_IN_GROONGA` には3個の要素があります:

    [
      FUNCTION_NAME,
      SOURCE_FILE_NAME,
      LINE_NUMBER
    ]

`FUNCTION_NAME` はエラーが発生した関数の名前です。

`SOURCE_FILE_NAME` はエラーが発生した箇所を含んだGroongaのソースコードのファイル名です。

`LINE_NUMBER` はエラーが発生した箇所の `SOURCE_FILE_NAME` での行番号です。

`LOCATION_IN_INPUT` は存在しないことがあります。 `LOCATION_IN_INPUT` は入力ファイルでエラーが発生した場所の情報を収集できたときに含まれます。入力ファイルは `groonga` コマンドのコマンドラインオプション `--file` で指定できます。 `LOCATION_IN_GROONGA` は配列です。 `LOCATION_IN_GROONGA` には3個の要素があります:

    [
      INPUT_FILE_NAME,
      LINE_NUMBER,
      LINE_CONTENT
    ]

`INPUT_FILE_NAME` はエラーが発生した入力ファイルのファイル名です。

`LINE_NUMBER` はエラーが発生した箇所の `INPUT_FILE_NAME` での行番号です。

`LINE_CONTENT` は `INPUT_FILE_NAME` 内の `LINE_NUMBER` 行目の内容です。

### 7.3.2.2.2. `BODY`

`BODY` の内容は実行したコマンドに依存します。 `BODY` がないこともあります。

エラーが発生した時に、 `BODY` にエラーメッセージが入っていることもあります。

## 7.3.2.3. XML

TODO

## 7.3.2.4. TSV

TODO

## 7.3.2.5. 参考

- リターンコード はリターンコードについて説明しています。

前へ

7.3.1. コマンドバージョン

次へ

7.3.3. プリティープリント