MetaTweet (new) Requests Specification

metatweet-requests-spec.txt

MetaTweet Requests (リクエスト)

目的
    MetaTweet サーバに対し要求を与え、結果を得る定型化された唯一の手段として定義される。
    サーバに対し要求を与えるとは、例えばローカルストレージからデータを受取り、または Twitter 等の
    外部サービスに対し問い合わせを行いその結果を格納しつつ返す、などに繋がる行為となる。
    入力および出力の型は自由である。本来 IEnumerable<StorageObject>、即ち MetaTweet のデータ
    オブジェクトのシーケンスが長らく前提とされてきたが、もはや全く限定されない。

定義
    以下の要素が定義される。
    リクエスト
        上述。リクエストは原則として文字列により表現され、1 以上のフラグメント (これもまた文字列と
        して表現される) を単純に連結したものとして表現される。
            * <request> := ( <fragment> )+ ;
    フラグメント
        リクエストを構成する実際の処理単位、または、それを補助する指示子。リクエストはフラグメントに
        より表される処理を (別途補助的なフラグメントにより指示される通りに) パイプライン形式で順次
        実行してゆき、その最終出力を結果とする指示である。
        フラグメントは入力を任意で要求し、任意で出力を行うことができる。
        フラグメントは変数の宣言を含むことができる。フラグメントで定義された変数とその値のリストは
        ディクショナリ形式で保管され、フラグメント内で書き換え、項目を追加することができ、その内容は
        次のフラグメントに引き渡される。
        フラグメントは Flow、Code、BeginScope、EndScope、Conjunction の 5 種類に分けられ、各々書式が
        定義される。
    スコープ
        フラグメントに与えられる変数や出力結果を保持する環境。また、数学における括弧の用法のように
        処理が実行される順序の単位ともなる。
    Flow フラグメント
        MetaTweet の Flow モジュール上でカスタム属性の付与によって公開される処理 (例えば Twitter の
        home_timeline を取得するなど) を実行するフラグメント。
    Code フラグメント
        指示された言語とコードをそのまま実行するフラグメント。
    BeginScope フラグメント
        新しいスコープを開始するフラグメント。
    EndScope フラグメント
        現在のスコープを終了し、上位のスコープに戻るフラグメント。
    Conjunction フラグメント
        一つ前に位置するフラグメント/スコープの処理結果に応じて、後に続くフラグメント/スコープを
        実行するかどうか、また、与える入力の内容を制御するフラグメント。

文法
    共通
        全てのフラグメントは文字 / から開始される。続いて任意で変数の設定 (文字 '$' から開始する; 後述)
        を記述する。その後に各フラグメントを区別する文字、およびそれぞれの具体的内容が続いてゆく。
            * <fragment> := '/' ( <variable_definition_list> )? (
                <flow_body> | <code_body> | <begin_scope_body> | <end_scope_body> | <conjunction_body>
            ) ;
    変数
        変数の設定は文字 '$' から開始され、$KEY=VALUE の形式で定義される。サポートされるべき VALUE の
        値は文字列、数値、リクエスト (少なくとも Code フラグメント、可能であれば全てのフラグメントを
        サポートするべきである) である。複数の変数を設定する場合は $KEY1=VALUE1$KEY2=VALUE2... のように
        単純に記述を連結して続けてゆく。
            * <variable_definition_list> := ( <variable_definition> )+ ;
            * <variable_definition> := '$' <variable_key> '=' <variable_value> ;
            * <variable_key> := IDENTIFIER ;
            * <variable_value> := ( STRING | NUMBER | <request> ) ;
    Flow フラグメント
        Flow フラグメントは文字 '!' により識別される。続いて、任意で処理を含む Flow モジュールの名前を
        記述する。その後に文字 '/' から開始されるセレクタ (Flow モジュール内で公開される処理の ID) を
        記述し、最後に所謂 URI クエリ形式任意で引数を記述する。即ち、文字 '?' から開始し、
        KEY1=VALUE1&KEY2=VALUE2... のように続いてゆく形式である。引数として与えられるのはひとまず文字列
        のみとする。
            * <flow_body> := '!' ( <flow_module_name> )? <flow_selector_name> ( <flow_argument_list> )?
            * <flow_module_name> := IDENTIFIER ;
            * <flow_selector_name> := '/' IDENTIFIER ;
            * <flow_argument_list> := '?' ( <flow_argument> ( '&' <flow_argument> )+  )+ ;
            * <flow_argument> := <flow_argument_key> '=' <flow_argument_value> ;
            * <flow_argument_key> := STRING ;
            * <flow_argument_value> := STRING ;
    Code フラグメント
        Code フラグメントは文字 '@' により識別され、その後にコードの本文を記述する。
            * <code_body> := '@' <code> ;
            * <code> := STRING ;
    BeginScope フラグメント
        BeginScope フラグメントは単に文字 '(' のみである。
            * <begin_scope_body> := '(' ;
    EndScope フラグメント
        EndScope フラグメントは単に文字 ')' のみである。変数の設定は無視される。
            * <end_scope_body> := ')' ;
    Conjunction フラグメント
        Conjunction フラグメントは文字 '-' によって識別される。続いて、指示の内容を示す識別子を記述する。
            * <conjunction_body> := '-' : <conjunction_type> ;
            * <conjunction_type> := IDENTIFIER ;
    実体参照
        文字列内において文字列 '#'、数値、文字 ';' の部分はその数値の Unicode コードポイントを持つ
        文字に置換される。文字 '#x'、数値、文字 ';' の部分はその数値の Unicode コードポイントを持つ
        文字に置換される。実体参照によって表された部分はリクエストのフラグメントへの分割やその他の
        評価に用いず、よってエスケープ文字として使用することができる。
            * <entity_reference> := '#' ( <decimal_codepoint> | 'x' <hexadecimal_codepoint> ) ';' ;
            * <decimal_codepoint> := NUMBER ;
            * <hexadecimal_codepoint> := HEXNUMBER ;