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 Scid vs. PC.
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:
[]
= "0.8"
Then reference the vampirc_uci
crate in your crate root:
extern crate vampirc_uci;
Usage
- Import either the
parse(..)
method or theparse_strict(..)
method. The difference between them is thatparse_strict(..)
will return apest::error::Error
if any of the input is unrecognized or violates the rules of the PEG grammar, whereasparse
will simply ignore any such input. The latter is the approach recommended by the protocol specification.
use parse;
- Some other useful imports (for message representation):
use ;
- Parse some input:
let messages: MessageList = parse;
- Do something with the parsed messages:
for m in messages
- Outputting the messages
let message = Option;
println!; // Outputs "option name Selectivity type spin default 2 min 0 max 4"
API
The full API documentation is available at docs.rs.
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 crate goes together well with the vampirc-io crate, a library for non-blocking communication over standard input and output (which is how UCI communication is usually conducted), based on the async-std framework.
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