広告されたオプション値の検証
UsiOption::validate_value(Option<&str>) は、広告された単一オプションの型、上下限、候補に対して値を検証します。
I/Oやengine固有の処理は行いません。
rsshogi-usi = "0.2.1" 以降で利用できます。
入力とエラー
| 型 | 成功する値 | 失敗の分類 |
|---|---|---|
| Check | Some("true")、Some("false") | その他のSomeはInvalidBoolean |
| Spin | i64としてparseでき、広告された上下限を含む範囲のSome | 非整数と桁あふれはInvalidInteger、範囲外はBelowMinimum / AboveMaximum |
| Combo | varsとの完全一致 | 候補外はNotInVars。大小文字を区別する |
| String / Filename | 空文字列を含むすべてのSome | 型による制限は追加しない |
| Button | None | 空文字列を含む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結果 |
|---|---|
None | setoption 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側の責務です。