12 releases (6 breaking)
0.11.1 | Mar 27, 2022 |
---|---|
0.11.0 | Sep 17, 2020 |
0.10.1 | May 16, 2020 |
0.8.3 | Dec 21, 2019 |
0.8.0 | Mar 29, 2019 |
#594 in Parser implementations
279 downloads per month
Used in vampirc-io
170KB
3.5K
SLoC
vampirc-uci
Vampirc UCI is a Universal Chess Interface (UCI) protocol parser and serializer.
The UCI protocol is a way for a chess engine to communicate with a chessboard GUI, such as Cute Chess.
The Vampirc Project is a chess engine and chess library suite, written in Rust. It is named for the Slovenian grandmaster Vasja Pirc, and, I guess, vampires? I dunno.
Vampirc UCI uses the PEST parser to parse the UCI messages. If you want to build your own abstractions of the protocol, the corresponding PEG grammar is available here.
Installing the library
To use the crate, declare a dependency on it in your Cargo.toml file:
[dependencies]
vampirc-uci = "0.11"
Then reference the vampirc_uci
crate in your crate root:
extern crate vampirc_uci;
Usage
- Choose and import one of the
parse..
functions. See Choosing the parsing function.
use vampirc_uci::parse;
- Some other useful imports (for message representation):
use vampirc_uci::{UciMessage, MessageList, UciTimeControl, Serializable};
- Parse some input:
let messages: MessageList = parse("uci\nposition startpos moves e2e4 e7e5\ngo ponder\n");
- Do something with the parsed messages:
for m in messages {
match m {
UciMessage::Uci => {
// Initialize the UCI mode of the chess engine.
}
UciMessage::Position { startpos, fen, moves } => {
// Set up the starting position in the engine and play the moves e2-e4 and e7-e5
}
UciMessage::Go { time_control, search_control } {
if let Some(tc) = time_control {
match tc {
UciTimeControl::Ponder => {
// Put the engine into ponder mode ("think" on opponent's time)
}
_ => {...}
}
}
}
_ => {...}
}
}
- Outputting the messages
let message = UciMessage::Option(UciOptionConfig::Spin {
name: "Selectivity".to_string(),
default: Some(2),
min: Some(0),
max: Some(4),
});
println!(message); // Outputs "option name Selectivity type spin default 2 min 0 max 4"
- Or, parse and handle input line by line, from, for example,
stdin
:
use std::io::{self, BufRead};
use vampirc_uci::{UciMessage, parse_one};
for line in io::stdin().lock().lines() {
let msg: UciMessage = parse_one(&line.unwrap());
println!("Received message: {}", msg);
}
Choosing the parsing function
There are several parsing functions available, depending on your need and use case. They differ in what they return and how they handle unrecognized input. The following table may be of assistance in selecting the parsing function:
Function | Returns | Can skip terminating newline | On unrecognised input... |
---|---|---|---|
parse |
MessageList (a Vec of UciMessage ) |
On last command | Ignores it |
parse_strict |
MessageList (a Vec of UciMessage ) |
On last command | Throws a pest::ParseError |
parse_with_unknown |
MessageList (a Vec of UciMessage ) |
On last command | Wraps it in a UciMessage::Unknown variant |
parse_one |
UciMessage |
Yes | Wraps it in a UciMessage::Unknown variant |
From my own experience, I recommend using either parse_with_unknown
if your string can contain multiple commands, or
else parse_one
if you're doing line by line parsing. That way, your chess engine or tooling can at least log
unrecognised input, available from UciMessage::Unknown(String, Error)
variant.
Integration with the chess crate (since 0.9.0)
This library (optionally) integrates with the chess crate. First, include the
vampirc-uci
crate into your project with the chess
feature:
[dependencies]
vampirc-uci = {version = "0.11", features = ["chess"]}
This will cause the vampirc_uci's internal representation of moves, squares and pieces to be replaced with chess
crate's representation of those concepts. Full table below:
vampirc_uci 's representation | chess' representation |
---|---|
vampirc_uci::UciSquare |
chess::Square |
vampirc_uci::UciPiece |
chess::Piece |
vampirc_uci::UciMove |
chess::ChessMove |
WARNING
chess
is a fairly heavy create with some heavy dependencies, so probably only use the integration feature if you're
building your own chess engine or tooling with it.
API
The full API documentation is available at docs.rs.
New in 0.11.1
- Improved
parse_with_unknown(&str)
so that it correctly recognizes as much of input as possible. For example, whereas earlier the inputuci\ndebug on\nucinewgame\nabc\nstop\nquit
would be returned as a singleUci::Unknown
message, the improved grammar support will return six separate messages, five of which will be proper UCI messages, while wrapping 'abc' intoUci::Unknown
. - A fix for incorrect serialization to string of the
btime
parameter, thanks to @analog_hors. - Support for the chess crate v. 3.2.0.
New in 0.11.0
- Support for negative times, such as negative time left and time increment, as discussed in
vampirc-uci doesn't recognize negative times #16.
To support negative durations, the representation of millisecond-based time quantities has been switched
from Rust standard library's
std::time::Duration
to the chrono crate'schrono::Duration
(doc). This is an API-breaking change, hence the version increase. - Fix for vampric-uci-19, a sometimes incorrect parsing of the
go
message.
New in 0.10.1
- Republish as 0.10.1 due to improper publish.
New in 0.10.0
- Added the
parse_one(&str)
method that parses and returns a single command, to be used in a loop that reads fromstdin
or otherBufReader
. See example above. - Changed the internal representation of time parameters from
u64
intostd::time::Duration
(breaking change). - Relaxed grammar rules now allow that the last command sent to
parse()
or friends doesn't need to have a newline terminator. This allows for parsing of, among others, a single command read in a loop fromstdin::io::stdin().lock().lines()
, which strips the newline characters from the end - see vampirc-uci-14. - Marked the
UciMessage::direction(&self)
method as public.
New in 0.9.0
- (Optional) integration with chess crate (see above).
- Removed the explicit Safe and Sync implementations.
New in 0.8.3
- Added the
UciMessage::info_string()
utility function. - Allowed the empty
go
command (see Parser cannot parse "go\n").
New in 0.8.2
- Added
ByteVecUciMessage
as aUciMessage
wrapper that keeps the serialized form of the message in the struct as a byte Vector. Useful if you need to serialize the same message multiple types or supportAsRef<[u8]>
trait for funnelling the messages into afutures::Sink
or something. - Modifications for integration with async async-std based vampirc-io.
New in 0.8.1
- Added
parse_with_unknown()
method that instead of ignoring unknown messages (likeparse
) or throwing an error (likeparse_strict
) returns them as aUciMessage::Unknown
variant.
New in 0.8.0
- Support for parsing of the
info
message, with the UciAttributeInfo enum representing all 17 types of messages described by the UCI documentation, as well as any other info message via the Any variant.
New in 0.7.5
- Support for parsing of the
option
message. - Proper support for
<empty>
strings inoption
andsetoption
.
vampirc-io
This section used to recommend using the vampirc-io crate to connect your UCI-based chess engine to the GUI, but honestly, with recent advances to Rust's async stack support, it is probably just easier if you do it yourself using, for example, the async-std library.
Limitations and 1.0
The library is functionally complete – it supports the parsing and serialization to string of all the messages described by the UCI specification. Before the 1.0 version can be released, though, this library needs to be battle tested more, especially in the upcoming Vampirc chess engine.
Furthermore, as I am fairly new to Rust, I want to make sure the implementation of this protocol parser is Rust-idiomatic before releasing 1.0. For this reason, the API should not be considered completely stable until 1.0 is released.
Additionally, some performance testing would also not go amiss.
Supported engine-bound messages (100%)
uci
debug
isready
register
position
setoption
ucinewgame
stop
ponderhit
quit
go
Supported GUI-bound messages (100%)
id
uciok
readyok
bestmove
copyprotection
registration
option
info
Dependencies
~3–4MB
~76K SLoC