Qithub コマンドの引数（JSON フォーマット）の仕様

本項では、各コマンドが実行時に引数で受け取るデータ、つまり Qithub エンコードされた JSON フォーマットについて記載しています。

Qithub コマンドやエンコードについては「Qithubコマンドの基本概要」をご覧ください。

基本 JSON フォーマット（受け取りデータ）

以下は、引数で渡された Qithub エンコードをデコードした際の JSON データの基本フォーマットです。各々のコマンドは、第１引数で受け取った Qithub エンコード・データを各自でデコードする必要があります。

{
    "name_cmd": "＜コマンド名＞",
    "args_cmd": "＜コマンドの引数＞"
}

必須要素（パラメーター）	形式	内容／用途
name_cmd	文字列	コマンド名
args_cmd	文字列	コマンドの引数

下記のトゥートの場合、受け取る args_cmd の値は「arg1 arg2\n\nHOGE」になります。

@qithub:your-command arg1 arg2

HOGE

引数の考え方（主な流れ）

Qithub コマンドを作成／設計するうえで大事なのは、基本的にトゥートで受け取ることを前提にしてることです。

その際のトゥートによるコマンドのフォーマットは以下の通りです。

@qithub:<コマンド名>␣<args（トゥートの最後まで）>

トゥートによるコマンド実行の例

@qithub:roll-dice 3d6 --emoji=yes
これはサンプルトゥートです

例えば、上記のようなトゥートを BOT が受け取った場合は、コマンドに渡される引数の値は次のようになります。

スクリプトが受け取るデータ

上記トゥートを受け取った BOT が、スクリプトの第１引数に渡す Qithub エンコードされたデータ

%7B%22name_cmd%22%3A%22dice-roll%22%2C%22args_cmd%22%3A%223d6+--emoji%3Dyes%5Cn%5Cu3053%5Cu308c%5Cu306f%5Cu30b5%5Cu30f3%5Cu30d7%5Cu30eb%5Cu30c8%5Cu30a5%5Cu30fc%5Cu30c8%5Cu3067%5Cu3059%22%7D

受け取ったデータのデコード（JSON データ）

上記 Qithub エンコードデータはデコード（URL デコード）すると以下のような JSON データになります。

{
    "name_cmd": "roll-dice",
    "args_cmd": "3d6 --emoji=yes\n\u3053\u308c\u306f\u30b5\u30f3\u30d7\u30eb\u30c8\u30a5\u30fc\u30c8\u3067\u3059"
}

PHP の場合のデコードサンプル。

<?php

$data_encode = $argv(1); // スクリプトの第１引数取得
$data_decode = urldecode($data_encode); // URLデコード
$data_array  = json_decode($data_decode,JSON_OBJECT_AS_ARRAY); // JSON を PHP 配列にデコード

print_r($data_array);

Python の場合のデコード・サンプル

# -*- coding: utf-8 -*-

import sys, urllib.parse, json

data_encode = sys.argv[1] # スクリプトの第１引数取得
data_decode = urllib.parse.unquote(data_encode) # URLデコード
data_dict   = json.loads(data_decode) # JSON を辞書形式にデコード

print(data_dict)

その他のオプション・パラメーター

受け取る JOSN データの name_cmd と args_cmd は必須要素（パラメーター）ですが、これら以外の要素が渡される場合があります。

1. 各コマンドの Main.xxx と同階層に info.json ファイルが設置されている場合
2. 各コマンドが上記 info.json にてユーザーにリクエストしている場合

この info.json ファイルを設置することで、より高度なコマンドを作ることができますが、詳しくは『info.json の仕様』をご覧ください。

---

▶︎ 次項『Qithub コマンドの返り値（出力）』