From d75c559304b9deb5f09cfa6330ff7e0bf26c37ed Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Sat, 9 May 2020 17:12:25 +0200 Subject: update documentation and README --- README.md | 9 +++------ src/lib.rs | 35 ++++++++++++++++++++++++++++------- 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c68be25..babfd3d 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ evtclib [![Latest Version](https://img.shields.io/crates/v/evtclib.svg)](https://crates.io/crates/evtclib) [![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/evtclib) +[![License](https://img.shields.io/crates/l/evtclib.svg)](https://opensource.org/licenses/MIT) `evtclib` is a Rust library that allows you to parse `.evtc` files, as generated by the [arcdps addon](https://www.deltaconnected.com/arcdps/) for the @@ -25,12 +26,8 @@ Example use std::fs::File; fn main() -> Result<(), Box> { - // Open a file for processing - let mut file = File::open("Skorvald/20200421-183243.evtc")?; - // Parse the raw content of the file - let raw_log = evtclib::raw::parse_file(&mut file)?; - // Process the file to do the nitty-gritty low-level stuff done - let log = evtclib::process(&raw_log)?; + // Parse a log + let log = evtclib::process_file("Skorvald/20200421-183243.evtc")?; // Do work on the log for player in log.players() { println!("Player {} participated!", player.account_name()); diff --git a/src/lib.rs b/src/lib.rs index 11273ad..eb371bd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -30,20 +30,41 @@ //! //! # Workflow //! -//! Currently, there is no convenience function to turn a file into a [`Log`][Log] directly, so you -//! have to use the [`raw`][raw] submodule to obtain a low-level [`Evtc`][raw::Evtc], and then -//! convert it to the high-level [`Log`][Log]. +//! `evtclib` provides two convenience functions to obtain a [`Log`][Log]: +//! +//! If you have a stream (that is, something that is [`Read`][Read] + [`Seek`][Seek]), you can use +//! [`process_stream`][process_stream] to obtain a [`Log`][Log] by reading from the stream. +//! +//! If your evtc is saved in a file, you can use [`process_file`][process_file] to obtain a [`Log`] +//! from it. This will also ensure that the buffering is set up correctly, to avoid unnecessary +//! system calls. +//! +//! Both of those functions require the reader to be seekable, as that is what we need for zip +//! archive support. If you cannot provide that, or if you need finer grained control for other +//! reasons, you can use either [`raw::parse_file`][raw::parse_file] or +//! [`raw::parse_zip`][raw::parse_zip] to obtain the low-level [`Evtc`][raw::Evtc] structure, and +//! then turn it into a [`Log`][Log] by using [`process`][process]: //! //! ```no_run //! # fn main() -> Result<(), Box> { +//! use evtclib::{Compression, Log}; //! use std::fs::File; +//! // Preferred: +//! let log: Log = evtclib::process_file("my_log.evtc", Compression::None)?; +//! +//! // If you have a stream: +//! let file = File::open("my_log.evtc")?; +//! let log: Log = evtclib::process_stream(file, Compression::None)?; +//! +//! // If you really need to do it manually: //! // Open a file for processing -//! let mut file = File::open("my_log.evtc")?; +//! let file = File::open("my_log.evtc")?; //! // Parse the raw content of the file -//! let raw_log = evtclib::raw::parse_file(&mut file)?; +//! let raw_log = evtclib::raw::parse_file(file)?; //! // Process the file to do the nitty-gritty low-level stuff done -//! let log = evtclib::process(&raw_log)?; -//! // Do work on the log +//! let log: Log = evtclib::process(&raw_log)?; +//! +//! // In all cases, you can now do work with the log //! for player in log.players() { //! println!("Player {} participated!", player.account_name()); //! } -- cgit v1.2.3