pokerust 0.3.1

Pokeapi wrapper
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

//! # Pokérust
//!
//! Rust wrapper for the pokeapi <https://pokeapi.co/>
//!
//! ## Basic Usage
//!
//! Get an object from an API by id
//! ```no_run
//! use pokerust::{Berry, FromId};
//! let berry = Berry::from_id(1).unwrap();
//! ```
//! or by name
//! ```no_run
//! use pokerust::{Berry, FromName};
//! let berry = Berry::from_name("cheri").unwrap();
//! ```
//! API responses are automatically cached.
//!
//! You can also fetch the resource lists:
//! ```no_run
//! # use std::error::Error;
//! # use pokerust::{Item, Endpoint, List};
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let items = Item::list(5, 20)?;  // ?offset=5&limit=20
//!
//! // get the lists referenced in the next and previous fields
//! items.previous_list()?;
//! items.next_list()?;
//!
//! // you can also just get the full list
//! let all_items = Item::full_list()?;
//! # Ok(())
//! # }
//! ```
//!
//! To get resources pointed to by `(Named)APIResource`, use `get()`:
//! ```no_run
//! # use std::error::Error;
//! # use pokerust::{Berry, FromName};
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let berry = Berry::from_name("cheri")?;
//! let berry_item = berry.item.get()?; // berry_item is an Item
//! # Ok(())
//! # }
//! ```
//! This can be chained:
//! ```no_run
//! # use std::error::Error;
//! # use pokerust::{PokemonSpecies, FromName};
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let marill = PokemonSpecies::from_name("marill")?;
//! let sea_incense = marill.evolution_chain.get()?.baby_trigger_item.unwrap().get()?;
//! # Ok(())
//! # }
//! ```
//!
//! The location of the pokeapi used can be changed by setting the
//! `POKERUST_ENDPOINT` environment variable. Defaults to the public instance at
//! <https://pokeapi.co/api/v2/>. Please consult the pokeapi documentation and read
//! the fair use policy before using the public API instance.

#![warn(clippy::all, clippy::pedantic, clippy::nursery)]

use serde::de::DeserializeOwned;

use crate::cache::get_resource;

mod cache;
mod pokeapi;
mod util;

pub use pokeapi::berries::*;
pub use pokeapi::contests::*;
pub use pokeapi::encounters::*;
pub use pokeapi::evolution::*;
pub use pokeapi::games::*;
pub use pokeapi::items::*;
pub use pokeapi::locations::*;
pub use pokeapi::machines::*;
pub use pokeapi::moves::*;
pub use pokeapi::pokemon::*;
pub use pokeapi::resource_lists::*;
pub use pokeapi::utility::*;

/// Trait for API objects with an associated endpoint.
pub trait Endpoint {
    type ResourceListKind;

    const ENDPOINT: &'static str;

    /// Get a list of these API objects with the given offset and limit.
    ///
    /// # Errors
    ///
    /// Will return an Err if there is an issue contacting the API endpoint on an uncached route
    fn list(offset: usize, limit: usize) -> Result<Self::ResourceListKind, minreq::Error>;

    /// Get the complete list of these API objects.
    ///
    /// # Errors
    ///
    /// Will return an Err if there is an issue contacting the API endpoint on an uncached route
    fn full_list() -> Result<Self::ResourceListKind, minreq::Error>;
}

/// Trait for API objects with a name.
pub trait Named {
    /// Get the name of this object.
    fn name(&self) -> &String;
}

/// Trait for API objects with an ID.
pub trait Id {
    /// Get the ID of this object.
    fn id(&self) -> i16;
}

/// API resources that can be retrived from an ID.
pub trait FromId: Id + Endpoint
where
    Self: Sized,
{
    /// Retrieve the API object of this type with this ID.
    ///
    /// # Errors
    ///
    /// Will return an Err if there is an issue contacting the API endpoint on an uncached route
    fn from_id(id: i16) -> Result<Self, minreq::Error>;
}

impl<T: Endpoint + Id + DeserializeOwned> FromId for T {
    fn from_id(id: i16) -> Result<Self, minreq::Error> {
        get_resource(&format!("{}/{}/", T::ENDPOINT, id))?.json::<Self>()
    }
}

/// API resources that can be retrived from a name.
pub trait FromName: Named + Endpoint
where
    Self: Sized,
{
    /// Retrieve the API object of this type with this name.
    ///
    /// # Errors
    ///
    /// Will return an Err if there is an issue contacting the API endpoint on an uncached route
    fn from_name(id: &str) -> Result<Self, minreq::Error>;
}

impl<T: Endpoint + Named + DeserializeOwned> FromName for T {
    fn from_name(id: &str) -> Result<Self, minreq::Error> {
        get_resource(&format!("{}/{}/", T::ENDPOINT, id))?.json::<Self>()
    }
}