berkus
/
cacache-rs
mirror of https://github.com/zkat/cacache-rs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: improve examples

This commit is contained in:
Kat Marchán 2019-10-21 18:27:56 -04:00
parent c619105315
commit ccdd8c7578
No known key found for this signature in database
GPG Key ID: AEB529C08A3C7E9E
3 changed files with 241 additions and 281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

310
src/get.rs
View File

@ -41,24 +41,19 @@ impl AsyncGet {
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let mut handle = cacache::get::open("./my-cache", "my-key").await?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str).await?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let mut handle = cacache::get::open("./my-cache", "my-key").await?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str).await?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// Ok(())
/// }
/// ```
pub fn check(self) -> Result<Algorithm> {
self.reader
@ -72,24 +67,19 @@ impl AsyncGet {
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let mut handle = cacache::get::open("./my-cache", "my-key").await?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str).await?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let mut handle = cacache::get::open("./my-cache", "my-key").await?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str).await?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// Ok(())
/// }
/// ```
pub async fn open<P, K>(cache: P, key: K) -> Result<AsyncGet>
where
@ -110,25 +100,20 @@ where
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "key", b"hello world").await?;
/// let mut handle = cacache::get::open_hash("./my-cache", sri).await?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str).await?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "key", b"hello world").await?;
/// let mut handle = cacache::get::open_hash("./my-cache", sri).await?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str).await?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// Ok(())
/// }
/// ```
pub async fn open_hash<P>(cache: P, sri: Integrity) -> Result<AsyncGet>
where
@ -144,20 +129,15 @@ where
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let data = cacache::get::data("./my-cache", "my-key").await?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let data = cacache::get::data("./my-cache", "my-key").await?;
/// Ok(())
/// }
/// ```
pub async fn data<P, K>(cache: P, key: K) -> Result<Vec<u8>>
where
@ -179,21 +159,16 @@ where
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// let data = cacache::get::data_hash("./my-cache", &sri).await?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// let data = cacache::get::data_hash("./my-cache", &sri).await?;
/// Ok(())
/// }
/// ```
pub async fn data_hash<P>(cache: P, sri: &Integrity) -> Result<Vec<u8>>
where
@ -206,20 +181,15 @@ where
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// cacache::get::copy("./my-cache", "my-key", "./data.txt").await?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// cacache::get::copy("./my-cache", "my-key", "./data.txt").await?;
/// Ok(())
/// }
/// ```
pub async fn copy<P, K, Q>(cache: P, key: K, to: Q) -> Result<u64>
where
@ -241,21 +211,16 @@ where
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello world").await?;
/// cacache::get::copy_hash("./my-cache", &sri, "./data.txt").await?;
/// # Ok(())
/// # }
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello world").await?;
/// cacache::get::copy_hash("./my-cache", &sri, "./data.txt").await?;
/// Ok(())
/// }
/// ```
pub async fn copy_hash<P, Q>(cache: P, sri: &Integrity, to: Q) -> Result<u64>
where
@ -307,16 +272,17 @@ impl SyncGet {
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let mut handle = cacache::get::open_sync("./my-cache", "my-key")?;
/// let mut str = String::new();
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let mut handle = cacache::get::open_sync("./my-cache", "my-key")?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str)?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// # Ok(())
/// # }
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// Ok(())
/// }
/// ```
pub fn check(self) -> Result<Algorithm> {
self.reader
@ -330,16 +296,17 @@ impl SyncGet {
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let mut handle = cacache::get::open_sync("./my-cache", "my-key")?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str)?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let mut handle = cacache::get::open_sync("./my-cache", "my-key")?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str)?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// Ok(())
/// }
/// ```
pub fn open_sync<P, K>(cache: P, key: K) -> Result<SyncGet>
where
@ -360,17 +327,18 @@ where
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let sri = cacache::put::data_sync("./my-cache", "key", b"hello world")?;
/// let mut handle = cacache::get::open_hash_sync("./my-cache", sri)?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str)?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let sri = cacache::put::data_sync("./my-cache", "key", b"hello world")?;
/// let mut handle = cacache::get::open_hash_sync("./my-cache", sri)?;
/// let mut str = String::new();
/// handle.read_to_string(&mut str)?;
/// // Remember to check that the data you got was correct!
/// handle.check()?;
/// Ok(())
/// }
/// ```
pub fn open_hash_sync<P>(cache: P, sri: Integrity) -> Result<SyncGet>
where
@ -386,12 +354,13 @@ where
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let data = cacache::get::data_sync("./my-cache", "my-key")?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let data = cacache::get::data_sync("./my-cache", "my-key")?;
/// Ok(())
/// }
/// ```
pub fn data_sync<P, K>(cache: P, key: K) -> Result<Vec<u8>>
where
@ -413,13 +382,14 @@ where
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// let data = cacache::get::data_hash_sync("./my-cache", &sri)?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// let data = cacache::get::data_hash_sync("./my-cache", &sri)?;
/// Ok(())
/// }
/// ```
pub fn data_hash_sync<P>(cache: P, sri: &Integrity) -> Result<Vec<u8>>
where
@ -432,12 +402,13 @@ where
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// cacache::get::copy_sync("./my-cache", "my-key", "./my-hello.txt")?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// cacache::get::copy_sync("./my-cache", "my-key", "./my-hello.txt")?;
/// Ok(())
/// }
/// ```
pub fn copy_sync<P, K, Q>(cache: P, key: K, to: Q) -> Result<u64>
where
@ -459,13 +430,14 @@ where
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// cacache::get::copy_hash_sync("./my-cache", &sri, "./my-hello.txt")?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// cacache::get::copy_hash_sync("./my-cache", &sri, "./my-hello.txt")?;
/// Ok(())
/// }
/// ```
pub fn copy_hash_sync<P, Q>(cache: P, sri: &Integrity, to: Q) -> Result<u64>
where

35
src/put.rs
View File

@ -21,20 +21,14 @@ use std::task::{Context as TaskContext, Poll};
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// # Ok(())
/// # }
/// use async_attributes;
/// use anyhow::Result;
///
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// Ok(())
/// }
/// ```
pub async fn data<P, D, K>(cache: P, key: K, data: D) -> Result<Integrity>
where
@ -144,12 +138,13 @@ impl AsyncPut {
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let data = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// # Ok(())
/// # }
/// use anyhow::Result;
/// use std::io::Read;
///
/// fn main() -> Result<()> {
/// let data = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// Ok(())
/// }
/// ```
pub fn data_sync<P, D, K>(cache: P, key: K, data: D) -> Result<Integrity>
where

177
src/rm.rs
View File

@ -15,28 +15,23 @@ use crate::index;
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// cacache::rm::entry("./my-cache", "my-key").await?;
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
///
/// // This fails:
/// cacache::get::data("./my-cache", "my-key").await?;
/// cacache::rm::entry("./my-cache", "my-key").await?;
///
/// // But this succeeds:
/// cacache::get::data_hash("./my-cache", &sri).await?;
/// # Ok(())
/// # }
/// // This fails:
/// cacache::get::data("./my-cache", "my-key").await?;
///
/// // But this succeeds:
/// cacache::get::data_hash("./my-cache", &sri).await?;
/// Ok(())
/// }
/// ```
pub async fn entry<P, K>(cache: P, key: K) -> Result<()>
where
@ -59,29 +54,25 @@ where
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// cacache::rm::entry("./my-cache", "my-key").await?;
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
///
/// // These fail:
/// cacache::get::data("./my-cache", "my-key").await?;
/// cacache::get::data_hash("./my-cache", &sri).await?;
/// cacache::rm::entry("./my-cache", "my-key").await?;
///
/// // But this succeeds:
/// cacache::get::entry("./my-cache", "my-key").await?;
/// # Ok(())
/// # }
/// // These fail:
/// cacache::get::data("./my-cache", "my-key").await?;
/// cacache::get::data_hash("./my-cache", &sri).await?;
///
/// // But this succeeds:
/// cacache::get::entry("./my-cache", "my-key").await?;
///
/// Ok(())
/// }
/// ```
pub async fn content<P: AsRef<Path>>(cache: P, sri: &Integrity) -> Result<()> {
rm::rm_async(cache.as_ref(), &sri).await.with_context(|| {
@ -98,27 +89,23 @@ pub async fn content<P: AsRef<Path>>(cache: P, sri: &Integrity) -> Result<()> {
///
/// ## Example
/// ```no_run
/// # use async_std::prelude::*;
/// # use async_std::task;
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # task::block_on(async {
/// # example().await.unwrap();
/// # });
/// # Ok(())
/// # }
/// #
/// # async fn example() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
/// use async_std::prelude::*;
/// use async_attributes;
/// use anyhow::Result;
///
/// cacache::rm::entry("./my-cache", "my-key").await?;
/// #[async_attributes::main]
/// async fn main() -> Result<()> {
/// let sri = cacache::put::data("./my-cache", "my-key", b"hello").await?;
///
/// // These all fail:
/// cacache::get::data("./my-cache", "my-key").await?;
/// cacache::get::entry("./my-cache", "my-key").await?;
/// cacache::get::data_hash("./my-cache", &sri).await?;
/// # Ok(())
/// # }
/// cacache::rm::entry("./my-cache", "my-key").await?;
///
/// // These all fail:
/// cacache::get::data("./my-cache", "my-key").await?;
/// cacache::get::entry("./my-cache", "my-key").await?;
/// cacache::get::data_hash("./my-cache", &sri).await?;
///
/// Ok(())
/// }
/// ```
pub async fn all<P: AsRef<Path>>(cache: P) -> Result<()> {
for entry in cache.as_ref().read_dir()? {
@ -134,20 +121,22 @@ pub async fn all<P: AsRef<Path>>(cache: P) -> Result<()> {
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// use anyhow::Result;
/// use std::io::Read;
///
/// cacache::rm::entry_sync("./my-cache", "my-key")?;
/// fn main() -> Result<()> {
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
///
/// // This fails:
/// cacache::get::data_sync("./my-cache", "my-key")?;
/// cacache::rm::entry_sync("./my-cache", "my-key")?;
///
/// // But this succeeds:
/// cacache::get::data_hash_sync("./my-cache", &sri)?;
/// # Ok(())
/// # }
/// // This fails:
/// cacache::get::data_sync("./my-cache", "my-key")?;
///
/// // But this succeeds:
/// cacache::get::data_hash_sync("./my-cache", &sri)?;
///
/// Ok(())
/// }
/// ```
pub fn entry_sync<P, K>(cache: P, key: K) -> Result<()>
where
@ -168,21 +157,23 @@ where
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// use anyhow::Result;
/// use std::io::Read;
///
/// cacache::rm::entry_sync("./my-cache", "my-key")?;
/// fn main() -> Result<()> {
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
///
/// // These fail:
/// cacache::get::data_sync("./my-cache", "my-key")?;
/// cacache::get::data_hash_sync("./my-cache", &sri)?;
/// cacache::rm::entry_sync("./my-cache", "my-key")?;
///
/// // But this succeeds:
/// cacache::get::entry_sync("./my-cache", "my-key")?;
/// # Ok(())
/// # }
/// // These fail:
/// cacache::get::data_sync("./my-cache", "my-key")?;
/// cacache::get::data_hash_sync("./my-cache", &sri)?;
///
/// // But this succeeds:
/// cacache::get::entry_sync("./my-cache", "my-key")?;
///
/// Ok(())
/// }
/// ```
pub fn content_sync<P: AsRef<Path>>(cache: P, sri: &Integrity) -> Result<()> {
rm::rm(cache.as_ref(), &sri).with_context(|| {
@ -199,19 +190,21 @@ pub fn content_sync<P: AsRef<Path>>(cache: P, sri: &Integrity) -> Result<()> {
///
/// ## Example
/// ```no_run
/// # use anyhow::Result;
/// # fn main() -> Result<()> {
/// # use std::io::Read;
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
/// use anyhow::Result;
/// use std::io::Read;
///
/// cacache::rm::entry_sync("./my-cache", "my-key")?;
/// fn main() -> Result<()> {
/// let sri = cacache::put::data_sync("./my-cache", "my-key", b"hello")?;
///
/// // These all fail:
/// cacache::get::data_sync("./my-cache", "my-key")?;
/// cacache::get::data_hash_sync("./my-cache", &sri)?;
/// cacache::get::entry_sync("./my-cache", "my-key")?;
/// # Ok(())
/// # }
/// cacache::rm::entry_sync("./my-cache", "my-key")?;
///
/// // These all fail:
/// cacache::get::data_sync("./my-cache", "my-key")?;
/// cacache::get::data_hash_sync("./my-cache", &sri)?;
/// cacache::get::entry_sync("./my-cache", "my-key")?;
///
/// Ok(())
/// }
/// ```
pub fn all_sync<P: AsRef<Path>>(cache: P) -> Result<()> {
for entry in cache.as_ref().read_dir()? {