scryfall/catalog.rs
1//! A Catalog object contains an array of Magic datapoints (words, card values,
2//! etc). Catalog objects are provided by the API as aids for building other
3//! Magic software and understanding possible values for a field on Card
4//! objects.
5//!
6//! Visit the official [docs](https://scryfall.com/docs/api/catalogs) for more documentation.
7
8use serde::{Deserialize, Serialize};
9
10use crate::uri::Uri;
11use crate::util::CATALOG_URL;
12
13/// A Catalog object contains an array of Magic datapoints (words, card values,
14/// etc). Catalog objects are provided by the API as aids for building other
15/// Magic software and understanding possible values for a field on Card
16/// objects.
17#[derive(Serialize, Deserialize, Clone, Eq, PartialEq, Hash, Debug)]
18#[cfg_attr(test, serde(deny_unknown_fields))]
19pub struct Catalog {
20 /// A link to the current catalog on Scryfall’s API.
21 pub uri: Uri<Catalog>,
22
23 /// The number of items in the `data` array.
24 pub total_values: usize,
25
26 /// An array of datapoints, as strings.
27 pub data: Vec<String>,
28}
29
30impl Catalog {
31 /// Returns a list of all nontoken English card names in Scryfall’s
32 /// database. Values are updated as soon as a new card is entered for
33 /// spoiler seasons.
34 ///
35 /// # Examples
36 /// ```rust
37 /// use scryfall::catalog::Catalog;
38 /// # tokio_test::block_on(async {
39 /// assert!(Catalog::card_names().await.unwrap().data.len() > 0)
40 /// # })
41 /// ```
42 pub async fn card_names() -> crate::Result<Self> {
43 Uri::from(CATALOG_URL.join("card-names")?).fetch().await
44 }
45
46 /// Returns a list of all canonical artist names in Scryfall’s database.
47 /// This catalog won’t include duplicate, misspelled, or funny names for
48 /// artists. Values are updated as soon as a new card is entered for
49 /// spoiler seasons.
50 ///
51 /// # Examples
52 /// ```rust
53 /// use scryfall::catalog::Catalog;
54 /// # tokio_test::block_on(async {
55 /// assert!(Catalog::artist_names().await.unwrap().data.len() > 0)
56 /// # })
57 /// ```
58 pub async fn artist_names() -> crate::Result<Self> {
59 Uri::from(CATALOG_URL.join("artist-names")?).fetch().await
60 }
61
62 /// Returns a Catalog of all English words, of length 2 or more, that could
63 /// appear in a card name. Values are drawn from cards currently in
64 /// Scryfall’s database. Values are updated as soon as a new card is
65 /// entered for spoiler seasons.
66 ///
67 /// # Examples
68 /// ```rust
69 /// use scryfall::catalog::Catalog;
70 /// # tokio_test::block_on(async {
71 /// assert!(Catalog::word_bank().await.unwrap().data.len() > 0)
72 /// # })
73 /// ```
74 pub async fn word_bank() -> crate::Result<Self> {
75 Uri::from(CATALOG_URL.join("word-bank")?).fetch().await
76 }
77
78 /// Returns a Catalog of all creature types in Scryfall’s database. Values
79 /// are updated as soon as a new card is entered for spoiler seasons.
80 ///
81 /// # Examples
82 /// ```rust
83 /// use scryfall::catalog::Catalog;
84 /// # tokio_test::block_on(async {
85 /// assert!(Catalog::creature_types().await.unwrap().data.len() > 0)
86 /// # })
87 /// ```
88 pub async fn creature_types() -> crate::Result<Self> {
89 Uri::from(CATALOG_URL.join("creature-types")?).fetch().await
90 }
91
92 /// Returns a Catalog of all Planeswalker types in Scryfall’s database.
93 /// Values are updated as soon as a new card is entered for spoiler
94 /// seasons.
95 ///
96 /// # Examples
97 /// ```rust
98 /// use scryfall::catalog::Catalog;
99 /// # tokio_test::block_on(async {
100 /// assert!(Catalog::planeswalker_types().await.unwrap().data.len() > 0)
101 /// # })
102 /// ```
103 pub async fn planeswalker_types() -> crate::Result<Self> {
104 Uri::from(CATALOG_URL.join("planeswalker-types")?)
105 .fetch()
106 .await
107 }
108
109 /// Returns a Catalog of all Land types in Scryfall’s database. Values are
110 /// updated as soon as a new card is entered for spoiler seasons.
111 ///
112 /// # Examples
113 /// ```rust
114 /// use scryfall::catalog::Catalog;
115 /// # tokio_test::block_on(async {
116 /// assert!(Catalog::land_types().await.unwrap().data.len() > 0)
117 /// # })
118 /// ```
119 pub async fn land_types() -> crate::Result<Self> {
120 Uri::from(CATALOG_URL.join("land-types")?).fetch().await
121 }
122
123 /// Returns a Catalog of all artifact types in Scryfall’s database. Values
124 /// are updated as soon as a new card is entered for spoiler seasons.
125 ///
126 /// # Examples
127 /// ```rust
128 /// use scryfall::catalog::Catalog;
129 /// # tokio_test::block_on(async {
130 /// assert!(Catalog::artifact_types().await.unwrap().data.len() > 0)
131 /// # })
132 /// ```
133 pub async fn artifact_types() -> crate::Result<Self> {
134 Uri::from(CATALOG_URL.join("artifact-types")?).fetch().await
135 }
136
137 /// Returns a Catalog of all enchantment types in Scryfall’s database.
138 /// Values are updated as soon as a new card is entered for spoiler
139 /// seasons.
140 ///
141 /// # Examples
142 /// ```rust
143 /// use scryfall::catalog::Catalog;
144 /// # tokio_test::block_on(async {
145 /// assert!(Catalog::enchantment_types().await.unwrap().data.len() > 0)
146 /// # })
147 /// ```
148 pub async fn enchantment_types() -> crate::Result<Self> {
149 Uri::from(CATALOG_URL.join("enchantment-types")?)
150 .fetch()
151 .await
152 }
153
154 /// Returns a Catalog of all spell types in Scryfall’s database. Values are
155 /// updated as soon as a new card is entered for spoiler seasons.
156 ///
157 /// # Examples
158 /// ```rust
159 /// use scryfall::catalog::Catalog;
160 /// # tokio_test::block_on(async {
161 /// assert!(Catalog::spell_types().await.unwrap().data.len() > 0)
162 /// # })
163 /// ```
164 pub async fn spell_types() -> crate::Result<Self> {
165 Uri::from(CATALOG_URL.join("spell-types")?).fetch().await
166 }
167
168 /// Returns a Catalog of all possible values for a creature or vehicle’s
169 /// power in Scryfall’s database. Values are updated as soon as a new
170 /// card is entered for spoiler seasons.
171 ///
172 /// # Examples
173 /// ```rust
174 /// use scryfall::catalog::Catalog;
175 /// # tokio_test::block_on(async {
176 /// assert!(Catalog::powers().await.unwrap().data.len() > 0)
177 /// # })
178 /// ```
179 pub async fn powers() -> crate::Result<Self> {
180 Uri::from(CATALOG_URL.join("powers")?).fetch().await
181 }
182
183 /// Returns a Catalog of all possible values for a creature or vehicle’s
184 /// toughness in Scryfall’s database. Values are updated as soon as a
185 /// new card is entered for spoiler seasons.
186 ///
187 /// # Examples
188 /// ```rust
189 /// use scryfall::catalog::Catalog;
190 /// # tokio_test::block_on(async {
191 /// assert!(Catalog::toughnesses().await.unwrap().data.len() > 0)
192 /// # })
193 /// ```
194 pub async fn toughnesses() -> crate::Result<Self> {
195 Uri::from(CATALOG_URL.join("toughnesses")?).fetch().await
196 }
197
198 /// Returns a Catalog of all possible values for a Planeswalker’s loyalty in
199 /// Scryfall’s database. Values are updated as soon as a new card is
200 /// entered for spoiler seasons.
201 ///
202 /// # Examples
203 /// ```rust
204 /// use scryfall::catalog::Catalog;
205 /// # tokio_test::block_on(async {
206 /// assert!(Catalog::loyalties().await.unwrap().data.len() > 0)
207 /// # })
208 /// ```
209 pub async fn loyalties() -> crate::Result<Self> {
210 Uri::from(CATALOG_URL.join("loyalties")?).fetch().await
211 }
212
213 /// Returns a Catalog of all card watermarks in Scryfall’s database. Values
214 /// are updated as soon as a new card is entered for spoiler seasons.
215 ///
216 /// # Examples
217 /// ```rust
218 /// use scryfall::catalog::Catalog;
219 /// # tokio_test::block_on(async {
220 /// assert!(Catalog::watermarks().await.unwrap().data.len() > 0)
221 /// # })
222 /// ```
223 pub async fn watermarks() -> crate::Result<Self> {
224 Uri::from(CATALOG_URL.join("watermarks")?).fetch().await
225 }
226
227 /// Returns a Catalog of all keyword abilities in Scryfall’s database.
228 /// Values are updated as soon as a new card is entered for spoiler seasons.
229 ///
230 /// # Examples
231 /// ```rust
232 /// # use scryfall::catalog::Catalog;
233 /// # tokio_test::block_on(async {
234 /// assert!(
235 /// Catalog::keyword_abilities().await
236 /// .unwrap()
237 /// .data
238 /// .iter()
239 /// .find(|a| a.as_str() == "Haste")
240 /// .is_some()
241 /// );
242 /// # });
243 /// ```
244 pub async fn keyword_abilities() -> crate::Result<Self> {
245 Uri::from(CATALOG_URL.join("keyword-abilities")?)
246 .fetch()
247 .await
248 }
249
250 /// Returns a Catalog of all keyword actions in Scryfall’s database. Values
251 /// are updated as soon as a new card is entered for spoiler seasons.
252 ///
253 /// # Examples
254 /// ```rust
255 /// # use scryfall::catalog::Catalog;
256 /// # tokio_test::block_on(async {
257 /// assert!(
258 /// Catalog::keyword_actions().await
259 /// .unwrap()
260 /// .data
261 /// .iter()
262 /// .find(|a| a.as_str() == "Scry")
263 /// .is_some()
264 /// );
265 /// # })
266 /// ```
267 pub async fn keyword_actions() -> crate::Result<Self> {
268 Uri::from(CATALOG_URL.join("keyword-actions")?)
269 .fetch()
270 .await
271 }
272
273 /// Returns a Catalog of all ability words in Scryfall’s database. Values
274 /// are updated as soon as a new card is entered for spoiler seasons.
275 ///
276 /// # Examples
277 /// ```rust
278 /// # use scryfall::catalog::Catalog;
279 /// assert!(
280 /// # tokio_test::block_on(async {
281 /// Catalog::ability_words().await
282 /// .unwrap()
283 /// .data
284 /// .iter()
285 /// .find(|a| a.as_str() == "Landfall")
286 /// .is_some()
287 /// # })
288 /// );
289 /// ```
290 pub async fn ability_words() -> crate::Result<Self> {
291 Uri::from(CATALOG_URL.join("ability-words")?).fetch().await
292 }
293}