Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

広告されたオプション値の検証

UsiOption::validate_value(Option<&str>) は、広告された単一オプションの型、上下限、候補に対して値を検証します。 I/Oやengine固有の処理は行いません。 rsshogi-usi = "0.2.1" 以降で利用できます。

入力とエラー

型成功する値失敗の分類
CheckSome("true")、Some("false")その他のSomeはInvalidBoolean
Spini64としてparseでき、広告された上下限を含む範囲のSome非整数と桁あふれはInvalidInteger、範囲外はBelowMinimum / AboveMaximum
Combovarsとの完全一致候補外はNotInVars。大小文字を区別する
String / Filename空文字列を含むすべてのSome型による制限は追加しない
ButtonNone空文字列を含むSomeはUnexpectedValue
OtherなしNoneを含めUnsupportedKind

Button以外の既知型に対するNoneはMissingValueです。 SpinはRustのstr::parse::<i64>()に従い、+1も許容しますが、前後の空白は除去しません。 省略された境界に制限を補わず、min > maxは下限を先に比較して境界違反として拒否します。 広告定義の専用診断は行いません。

Comboは候補一覧が空なら全値を拒否し、一覧に空文字列がある場合だけSome("")を受理します。 これは公開モデル上の契約であり、広告parserが空のvarを受理しない既存仕様は変わりません。 trim、大小文字変換、パス正規化、既定値への補正は行いません。

OptionValueErrorは入力値、名前、候補、未知型文字列を保持しません。 DisplayとDebugにもそれらを含めません。 consumerがエラーへ設定値を追記しないようにしてください。

Buttonと空値

既存のUsiCommand::SetOptionと同じく、Noneはvalue節なし、Someはvalue節ありを意味します。

モデル上の値format結果
Nonesetoption name ClearHash
Some("")setoption name LogFile value
Some("<empty>")setoption name LogFile value <empty>

StringとFilenameで<empty>を空文字列へ変換するのは広告のdefaultだけです。 setoptionの値にその変換を追加することはありません。 値検証で成功しても、engineがその値をどう適用するかは保証しません。

operatorからの移行

validate_options.rs に、標準ライブラリと本crateだけで動く例があります。

#![allow(unused)]
fn main() {
extern crate rsshogi_usi;
use rsshogi_usi::{
    format_command, validate_portable_command, OptionValueError,
    UsiCommand, UsiOptionKind,
};
use std::{collections::BTreeMap, error::Error};
use rsshogi_usi::UsiOption;
fn prepare(advertised: &BTreeMap<String, UsiOption>, name: &str, configured_value: &str)
    -> Result<String, Box<dyn Error>> {
// 1. 収集済みの広告一覧と名前を照合する。
let option = advertised.get(name).ok_or("unknown engine option")?;

// 2. consumer設定のButton空文字表現を、検査してからNoneへ変換する。
let value = if option.kind == UsiOptionKind::Button {
    if !configured_value.is_empty() {
        return Err(OptionValueError::UnexpectedValue.into());
    }
    None
} else {
    Some(configured_value)
};
option.validate_value(value)?;

// 3. 型検査済みの値からcommandを生成し、送信前検査を行う。
let command = UsiCommand::SetOption {
    name: option.name.clone(),
    value: value.map(str::to_owned),
};
validate_portable_command(&command)?;
if value.is_some_and(|v| v.contains(['\r', '\n'])) {
    return Err("option value contains a line break".into());
}
let line = format_command(&command);
Ok(line)
}
}

validate_portable_commandはオプション名の空白だけを検査します。 値の型検査と併用しても、改行による別コマンドの混入を防ぐ検査にはなりません。 上の例ではCR/LFをconsumerで拒否しています。 既存parserは空白をtoken分割して再結合するため、先頭末尾の空白や連続空白の完全保存も保証しません。

広告一覧の収集と重複名の扱い、名前照合、設定ファイル表現の変換、送信形式の制約、engineの設定適用確認はconsumer側に残ります。 ファイルの存在や利用可否、プロセス管理、usiok/readyokのtimeoutもruntime側の責務です。