Crate bspc

source ·
Expand description

This library wraps around the bspc Quake utility tool to make it easier to use it from Rust. It does so by spawning a child process and asynchronously waiting for its output.

Some features include:

  • setting up a temporary directory to store input/output files in
  • parsing output logs to look for errors/warnings
  • streaming the output logs in real-time (via OptionsBuilder::log_stream)

The BSPC tool itself is not included with the library. Instead, it needs to already exist in the filesystem before the library is used.

Example

Basic example showing the conversion of a Quake BSP file to a MAP file:

use bspc::{Command, Options};
use tokio_util::sync::CancellationToken;

let bsp_contents = b"...";
let result = bspc::convert(
    "./test_resources/bspci386",
    Command::BspToMap(bsp_contents),
    Options::builder()
        .verbose(true)
        .build(),
)
.await;
match result {
    Ok(output) => {
        assert_eq!(output.files.len(), 1);
        println!("{}", output.files[0].name);
        println!("{}", String::from_utf8_lossy(&output.files[0].contents));
    }
    Err(err) => {
        println!("Conversion failed: {}", err);
    }
}

Example with cancellation

The following snippet demonstrates how to cancel the conversion (in this case, using a timeout) via the cancellation token. Note that the cancellation is not done simply by dropping the future (as is normally done), since we want to ensure that the child process is killed and the temporary directory deleted before the future completes.

use bspc::{Command, Options, ConversionError};
use tokio_util::sync::CancellationToken;

let bsp_contents = b"...";
let cancel_token = CancellationToken::new();
let cancel_task = {
    let cancel_token = cancel_token.clone();
    tokio::spawn(async move {
        tokio::time::sleep(std::time::Duration::from_secs(10)).await;
        cancel_token.cancel();
    })
};
let result = bspc::convert(
    "./test_resources/bspci386",
    Command::BspToMap(bsp_contents),
    Options::builder()
        .verbose(true)
        .cancellation_token(cancel_token)
        .build(),
)
.await;
match result {
    Ok(output) => {
        assert_eq!(output.files.len(), 1);
        println!("{}", output.files[0].name);
        println!("{}", String::from_utf8_lossy(&output.files[0].contents));
    }
    Err(ConversionError::Cancelled) => {
        println!("Conversion timed out after 10 seconds");
    }
    Err(err) => {
        println!("Conversion failed: {}", err);
    }
}

Modules

logs

Structs

Options
Options for the conversion process.
OptionsBuilder
Builder for Options.
Output
Full output of the child process, including the exit code, log, and any output files.
OutputFile
A single output file produced by the BSPC process.

Enums

Command
The subcommand to pass to the BSPC executable.
ConversionError
Error type returned by convert.

Functions

convert
Runs the BSPC executable with the given arguments, converting a single file to a different format, returning the complete output of the process (all output files, logs, and exit code).

Type Definitions

CommandArgumentBuilder
Callback used by Command::Other.