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
//! The `brawl-api` crate creates models and fetching methods employing the //! [official Brawl Stars API](https://developer.brawlstars.com). It aims to be an usable, //! predictable and programmer-friendly library. Anywhere it is not seen as so, contribution is //! very welcome. //! //! # Requesting //! //! All the requesting work is done by the [`reqwest` crate]. //! The library supports both sync (blocking) and, with the `async` feature (enabled by default), //! async function styles - all fetching methods with that duality have a sync variant (with its //! normal name) and an async one (named by prefixing the sync name with `a_` - e.g.: `fetch` (sync) //! and `a_fetch` (async)). //! //! # Deserialization and data structure //! //! Deserialization of JSON is done thanks to the [`serde`] and [`serde-json`] libraries, which are //! of invaluable aid on that aspect. This means that **all library models** implement the //! [`Serialize`] and [`Deserialize`] serde traits, optimized to match the JSON formats documented //! in the API's official documentation. //! //! In addition, it is noticeable that most API models implement the `Default` trait. This is for //! usage with `serde`, in order to ensure that the values will be there, regardless of an API //! failure. Fields not marked with `Option<T>` **should be there** by most standards - note that //! the official Brawl Stars API docs state that all fields everywhere are optional (which isn't //! helpful), even though most of them will always occur unless a server fault or some unexpected, //! new use-case was added (in which case, the library can be blamed for not being updated - **feel //! free to contribute with a PR, or just an issue poking me about this, adding this to the //! library!**). //! //! For more info on models, see the [`model`] module. //! //! # Recommended Usage //! //! It is recommended to import the library using its [`prelude`] module: //! //! ```rust //! use brawl_api::prelude::*; //! ``` //! //! This brings into scope all of the library's traits, models and the helper [`Brawlers`] enum. //! //! If it is not desired to bring all models into scope, then at least **import all traits** so that //! models work properly: //! //! ```rust //! use brawl_api::traits::*; //! ``` //! //! # Feature Flags //! //! The crate has a few feature flags available (all enabled by default): //! //! - `async` flag: //! - Enables the usage of async (non-blocking) fetch functions - `a_fetch`, `a_fetch_from`, //! `a_fetch_into`, `a_refetch` - where applicable. //! - Adds `async_trait` as a dependency. //! - `auto-hashtag` flag: Enables the smart insertion of hashtags on anywhere a tag is required. //! - This means, for example, that on a [`Player::fetch`] call, which requires the tag of the //! player to be fetched, one can pass a string containing a hashtag at the start (in which case, //! the library simply uses it) ***or without*** (then, with this feature on, the lib adds it //! automatically). //! - Disabling this requires passing hashtags at the start of every tag string. This is due to //! how the API parses tags, and not much can be done about it. //! - `chrono`: Adds `chrono` as dependency and enables the usage of [`TimeLike.parse`], which //! parses an incoming timestamp into a [`chrono::DateTime<chrono::Utc>`]. //! - `players` flag: Enables the usage of the [`model::players`] module (for the `/players` endpoint). //! - `clubs` flag: Enables the usage of the [`model::clubs`] module (for the `/clubs` endpoint). //! - `rankings` flag: Enables the usage of the [`model::rankings`] module (for the `/rankings` endpoint). //! - `brawlers` flag: Enables the usage of the [`model::brawlers`] module (for the `/brawlers` endpoint). //! //! [`reqwest` crate]: https://crates.io/crate/reqwest //! [`serde`]: https://crates.io/crate/serde //! [`serde-json`]: https://crates.io/crate/serde-json //! [`Serialize`]: https://docs.rs/serde/*/ser/trait.Serialize.html //! [`Deserialize`]: https://docs.rs/serde/*/de/trait.Deserialize.html //! [`Player::fetch`]: model/players/player/struct.Player.html#method.fetch //! [`TimeLike.parse`]: time/struct.TimeLike.html#method.parse //! [`chrono::DateTime<chrono::Utc>`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html //! [`model`]: model/index.html //! [`prelude`]: prelude/index.html //! [`Brawlers`]: constants/enum.Brawlers.html //! [`model::players`]: model/players/index.html //! [`model::clubs`]: model/clubs/index.html //! [`model::rankings`]: model/rankings/index.html //! [`model::brawlers`]: model/brawlers/index.html pub(crate) mod util; pub(crate) mod serde; pub mod constants; pub use constants::Brawlers; pub mod http; pub use http::client::Client; mod macros; pub mod model; pub mod time; pub use time::TimeLike; #[cfg(any(feature = "players", feature = "brawlers"))] pub use model::common::StarPower; #[cfg(feature = "players")] pub use model::players::{ Player, PlayerClub, PlayerBrawlerStat, battlelog::{ BattleLog, Battle, BattleEvent, BattleResultInfo, BattlePlayer, BattleBrawler, BattleOutcome, }, }; pub mod traits; #[cfg(feature = "clubs")] pub use model::clubs::{Club, ClubMember, ClubMembers, ClubMemberRole, ClubType}; #[cfg(feature = "rankings")] pub use model::rankings::{ players::{PlayerLeaderboard, PlayerRanking, PlayerRankingClub}, clubs::{ClubLeaderboard, ClubRanking}, brawlers::BrawlerLeaderboard, }; #[cfg(feature = "brawlers")] pub use model::brawlers::{BrawlerList, Brawler}; pub mod error; pub use error::{Error, Result}; pub mod prelude; //#[cfg(test)] //mod tests { // #[test] // fn it_works() { // assert_eq!(2 + 2, 4); // } //}