.. _problem_config:

problem.toml の書き方
=====================

ツールを使うために、問題ごとに設定ファイル ``problem.toml`` を作成します。

.. tip:: 
    **Rime を使用したことがある方向け**: このファイルは Rime で言うところの ``PROBLEM`` ファイルに似た位置づけです。 ``PROBLEM`` と同じ階層に保存することを推奨します。

ファイルの一例は次のとおりです。より具体的な例は :tree:`リポジトリ内のサンプル <sample>` をご覧ください。

.. literalinclude:: codes/reference/problem.toml

設定項目それぞれについて説明します。

.. problemtoml:: id

    **これは必須項目です**

    問題 ID を指定します。この ID はツール実行中の問題判別や、出力ファイルの名前に使用されます
    
    ID は、実行時に操作対象となる設定ファイルそれぞれで **一意でなければなりません**。例えば、 ``id = "A"`` となる設定ファイルが複数存在してはいけません。

.. problemtoml:: assets_path

    問題文に添付する画像などが含まれているディレクトリへのパスを指定します。問題文に図が必要な場合などにご利用ください。
    
    ``assets_path`` 以下に存在する全てのファイル・ディレクトリが ``ss-out`` ディレクトリ中の ``assets`` ディレクトリにコピーされます。画像などのリンクを張る際は、この仕様を念頭に置いて指定してください。

.. tip:: 
    パスの記述は絶対パスでも良いですし、 ``problem.toml`` からの相対パスでも構いません。

.. problemtoml:: sample_path

    サンプルケースが含まれているディレクトリへのパスを指定します。何も指定しなかった場合は、 ``problem.toml`` が存在する階層下の ``tests`` ディレクトリが設定されます。
    
    指定されたディレクトリ内のファイルであって、以下に全て当てはまるものはサンプルケース関連のファイルとみなし、問題文に記載されます。
    
    - 拡張子が ``.in`` / ``.out`` / ``.diff`` / ``.md`` のいずれかである
        
        - ``.in`` ファイル: 入力例を表すファイル
        - ``.out`` / ``.diff`` ファイル: 出力例を表すファイル
        - ``.md`` ファイル: インタラクティブの入出力例を表すファイル (``sample`` ディレクトリの I 問題参照)
        - ``[言語名]/*.md`` ファイル: 入出力例に関する説明 (``sample`` ディレクトリの A 問題を参照)
            
            - 例: 日本語で ``00_sample_00`` に関する説明をしたいならば、 ``[sample_path]/ja/00_sample_00.md`` というファイルを用意します
    
    - ファイル名に ``sample`` が部分文字列として含まれる

.. problemtoml:: ignore_samples

    ``sample_path`` で指定されたディレクトリにある、サンプルケースとして認識されるファイル名のうち、問題文に反映してほしくないものをリスト形式で指定します。拡張子は含めてはなりません。何も指定されなかった場合、見つかった全てのサンプルケースが問題文に反映されます。

    ファイル名の指定には `Unix のシェル形式のワイルドカード <https://docs.python.org/ja/3/library/fnmatch.html>`_ も利用できます。

    例えば ``00_sample_00`` および ``00_sample_hoge`` を問題文に含めてほしくない場合、 ``ignore_samples = ["00_sample_00", "00_sample_hoge"]`` のように設定します。

.. problemtoml:: params_path
    
    問題制約となるパラメータの値を、generator や validator で利用できるようにファイルに出力したいときに、パラメータを記載したファイルの出力パスを指定します。何も指定しなかった場合は、ファイルが出力されません。

    既存のファイルと全く同じ出力になる場合、出力をスキップします。

    .. warning:: 
        現状は C++ 形式の出力のみ (``.cpp``, ``.cc``, ``.h``, ``.hpp``) 対応しています。今後対応言語は増やす予定です


.. problemtoml:: [[statements]]

    **この設定は必須です**

    用意する問題文ファイルそれぞれについて設定します。設定方法の例は ``sample`` ディレクトリにある A 問題・C 問題などを参照してください。
    
    - :tree:`サンプルの A 問題 <sample/A>` では、英語・日本語の両方で問題文を作成する例を示しています
    - :tree:`サンプルの C 問題 <sample/C>` では、英語・日本語の両方で問題文を作成することに加えて、制約のみが異なる問題を作成する例も示しています
    
    各問題文ファイルについて以下を設定します。

    .. problemtoml:: path

        **この設定は必須です**

        - ローカルに問題文が存在する場合: 問題文が記載されているファイル名を指定します
        - Google Docs に問題文が存在する場合: Google Docs の ID か、もしくは Google Docs のファイルの URL を指定します。設定方法の例は :tree:`サンプルの H 問題 <sample/H>` を参照してください。
    
    .. problemtoml:: lang

        問題文が書かれている言語を設定します。``ja`` (日本語) もしくは ``en`` (英語) のいずれか一方を指定します。
        
        何も指定しなかった場合は ``en`` が設定されているとみなして実行します。

    .. problemtoml:: digit_separator

        桁区切りに使用する文字を設定します。何も指定しなかった場合は ``,`` が設定されているとみなして実行します。

        - 半角スペース 1 文字を指定した場合: ``1 000 000`` のように、数字の間に半角スペースが入ります
        - ``,`` を指定した場合: ``1,000,000`` のように、数字の間に半角カンマが入ります
        - ``none`` を指定した場合: ``1000000`` のように、数字の間に区切り文字が入りません
    
    .. problemtoml:: markdown_extensions

        `Python-Markdown が公式でサポートしている拡張機能 <https://python-markdown.github.io/extensions/>`_ のうち、使用したいものの Entry Point をリスト形式で指定します。
    
    .. problemtoml:: mode
        
        ``docs`` または ``local`` のどちらかを指定します。問題文ファイルが存在する場所に応じて設定ください。
        
        何も設定しなかった場合はモードが自動で認識されますので、通常は ``mode`` を設定する必要はありません。

.. problemtoml:: [constraints]

    問題制約を記述します。 ``[定数名] = [定数]`` のように記載します。