instances_social/instances/list.rs
1//! Request builder for the instances/list call
2//!
3//! ```no_run
4//! use instances_social::Client;
5//!
6//! const TOKEN: &'static str = "...";
7//!
8//! fn main() -> Result<(), Box<std::error::Error>> {
9//! let client = Client::new(TOKEN);
10//!
11//! let result = client.instances()
12//! .list() // returns this builder
13//! .count(100) // sets the ?count=100 querystring param
14//! // ...etc
15//! .send()?; // actually sends the request
16//! Ok(())
17//! }
18//! ```
19
20use crate::{
21 Client,
22 ItemIter,
23 ItemIterator,
24 instances::response::{
25 Instance, ListResponse,
26 },
27};
28use std::error::Error;
29
30/// Request builder for the instances/list call
31///
32/// ```no_run
33/// use instances_social::Client;
34///
35/// const TOKEN: &'static str = "...";
36///
37/// fn main() -> Result<(), Box<std::error::Error>> {
38/// let client = Client::new(TOKEN);
39///
40/// let result = client.instances()
41/// .list() // returns this builder
42/// .count(100) // sets the ?count=100 querystring param
43/// // ...etc
44/// .send()?; // actually sends the request
45/// Ok(())
46/// }
47/// ```
48#[derive(Serialize)]
49pub struct ListRequestBuilder<'a> {
50 #[serde(skip)]
51 client: &'a Client,
52 #[serde(skip_serializing_if = "Option::is_none")]
53 count: Option<u64>,
54 #[serde(skip_serializing_if = "Option::is_none")]
55 include_dead: Option<bool>,
56 #[serde(skip_serializing_if = "Option::is_none")]
57 include_down: Option<bool>,
58 #[serde(skip_serializing_if = "Option::is_none")]
59 include_closed: Option<bool>,
60 #[serde(skip_serializing_if = "Option::is_none")]
61 supported_features: Option<String>,
62 #[serde(skip_serializing_if = "Option::is_none")]
63 min_version: Option<String>,
64 #[serde(skip_serializing_if = "Option::is_none")]
65 min_users: Option<u64>,
66 #[serde(skip_serializing_if = "Option::is_none")]
67 max_users: Option<u64>,
68 #[serde(skip_serializing_if = "Option::is_none")]
69 min_active_users: Option<u64>,
70 #[serde(skip_serializing_if = "Option::is_none")]
71 category: Option<String>,
72 #[serde(skip_serializing_if = "Option::is_none")]
73 language: Option<String>,
74 #[serde(skip_serializing_if = "Option::is_none")]
75 prohibited_content: Option<Vec<String>>,
76 #[serde(skip_serializing_if = "Option::is_none")]
77 allowed_content: Option<Vec<String>>,
78 #[serde(skip_serializing_if = "Option::is_none")]
79 min_id: Option<String>,
80 #[serde(skip_serializing_if = "Option::is_none")]
81 sort_by: Option<Sort>,
82 #[serde(skip_serializing_if = "Option::is_none")]
83 sort_order: Option<SortOrder>,
84}
85
86#[derive(Serialize)]
87#[serde(rename_all = "snake_case")]
88/// Represents the allowed sort values for the instances/list call
89pub enum Sort {
90 /// sort_by=name
91 Name,
92 /// sort_by=uptime
93 Uptime,
94 /// sort_by=https_score
95 HttpsScore,
96 /// sort_by=obs_score
97 ObsScore,
98 /// sort_by=users
99 Users,
100 /// sort_by=statuses
101 Statuses,
102 /// sort_by=connections
103 Connections,
104 /// sort_by=active_users
105 ActiveUsers,
106}
107
108#[derive(Serialize)]
109#[serde(rename_all = "snake_case")]
110/// Represents the allow sort order values for the instances/list call
111pub enum SortOrder {
112 /// represents `sort_order=asc`
113 Asc,
114 /// represents `sort_order=desc`
115 Desc,
116}
117
118impl<'a, 'b: 'a> ItemIter for &'a mut ListRequestBuilder<'b> {
119 type Response = ListResponse;
120
121 fn get_page(&mut self, token: Option<&String>) -> Result<Self::Response, Box<Error>> {
122 Ok(if let Some(tok) = token {
123 self.min_id(&tok).send()?
124 } else {
125 self.send()?
126 })
127 }
128}
129
130impl<'a> ListRequestBuilder<'a> {
131 pub(crate) fn new(client: &'a Client) -> ListRequestBuilder<'a> {
132 ListRequestBuilder {
133 client,
134 count: None,
135 include_dead: None,
136 include_down: None,
137 include_closed: None,
138 supported_features: None,
139 min_version: None,
140 min_users: None,
141 max_users: None,
142 min_active_users: None,
143 category: None,
144 language: None,
145 prohibited_content: None,
146 allowed_content: None,
147 min_id: None,
148 sort_by: None,
149 sort_order: None,
150 }
151 }
152
153 /// Set the `count` parameter for instances/list
154 ///
155 /// ```no_run
156 /// # extern crate instances_social;
157 /// # use instances_social::{Client, instances::list::Sort};
158 /// # use std::error::Error;
159 /// const TOKEN: &'static str = "...";
160 ///
161 /// # fn main() -> Result<(), Box<Error>> {
162 /// let client = Client::new(TOKEN);
163 /// let result = client.instances()
164 /// .list()
165 /// .count(100)
166 /// .send()?;
167 /// # Ok(())
168 /// # }
169 /// ```
170 pub fn count(&mut self, count: u64) -> &mut Self {
171 self.count = Some(count);
172 self
173 }
174
175 /// Set the `include_dead` parameter for instances/list
176 ///
177 /// ```no_run
178 /// # extern crate instances_social;
179 /// # use instances_social::{Client, instances::list::Sort};
180 /// # use std::error::Error;
181 /// const TOKEN: &'static str = "...";
182 ///
183 /// # fn main() -> Result<(), Box<Error>> {
184 /// let client = Client::new(TOKEN);
185 /// let result = client.instances()
186 /// .list()
187 /// .include_dead(true)
188 /// .send()?;
189 /// # Ok(())
190 /// # }
191 /// ```
192 pub fn include_dead(&mut self, include_dead: bool) -> &mut Self {
193 self.include_dead = Some(include_dead);
194 self
195 }
196
197 /// Set the `include_down` parameter for instances/list
198 ///
199 /// ```no_run
200 /// # extern crate instances_social;
201 /// # use instances_social::{Client, instances::list::Sort};
202 /// # use std::error::Error;
203 /// const TOKEN: &'static str = "...";
204 ///
205 /// # fn main() -> Result<(), Box<Error>> {
206 /// let client = Client::new(TOKEN);
207 /// let result = client.instances()
208 /// .list()
209 /// .include_down(true)
210 /// .send()?;
211 /// # Ok(())
212 /// # }
213 /// ```
214 pub fn include_down(&mut self, include_down: bool) -> &mut Self {
215 self.include_down = Some(include_down);
216 self
217 }
218
219 /// Set the `include_closed` parameter for instances/list
220 ///
221 /// ```no_run
222 /// # extern crate instances_social;
223 /// # use instances_social::{Client, instances::list::Sort};
224 /// # use std::error::Error;
225 /// const TOKEN: &'static str = "...";
226 ///
227 /// # fn main() -> Result<(), Box<Error>> {
228 /// let client = Client::new(TOKEN);
229 /// let result = client.instances()
230 /// .list()
231 /// .include_closed(true)
232 /// .send()?;
233 /// # Ok(())
234 /// # }
235 /// ```
236 pub fn include_closed(&mut self, include_closed: bool) -> &mut Self {
237 self.include_closed = Some(include_closed);
238 self
239 }
240
241 /// Set the `supported_features` parameter for instances/list
242 ///
243 /// ```no_run
244 /// # extern crate instances_social;
245 /// # use instances_social::{Client, instances::list::Sort};
246 /// # use std::error::Error;
247 /// const TOKEN: &'static str = "...";
248 ///
249 /// # fn main() -> Result<(), Box<Error>> {
250 /// let client = Client::new(TOKEN);
251 /// let result = client.instances()
252 /// .list()
253 /// .supported_features("foo")
254 /// .send()?;
255 /// # Ok(())
256 /// # }
257 /// ```
258 pub fn supported_features(&mut self, supported_features: &str) -> &mut Self {
259 self.supported_features = Some(supported_features.to_string());
260 self
261 }
262
263 /// Set the `min_version` parameter for instances/list
264 ///
265 /// ```no_run
266 /// # extern crate instances_social;
267 /// # use instances_social::{Client, instances::list::Sort};
268 /// # use std::error::Error;
269 /// const TOKEN: &'static str = "...";
270 ///
271 /// # fn main() -> Result<(), Box<Error>> {
272 /// let client = Client::new(TOKEN);
273 /// let result = client.instances()
274 /// .list()
275 /// .min_version("1.0.0")
276 /// .send()?;
277 /// # Ok(())
278 /// # }
279 /// ```
280 pub fn min_version(&mut self, min_version: &str) -> &mut Self {
281 self.min_version = Some(min_version.to_string());
282 self
283 }
284
285 /// Set the `min_users` parameter for instances/list
286 ///
287 /// ```no_run
288 /// # extern crate instances_social;
289 /// # use instances_social::{Client, instances::list::Sort};
290 /// # use std::error::Error;
291 /// const TOKEN: &'static str = "...";
292 ///
293 /// # fn main() -> Result<(), Box<Error>> {
294 /// let client = Client::new(TOKEN);
295 /// let result = client.instances()
296 /// .list()
297 /// .min_users(42)
298 /// .send()?;
299 /// # Ok(())
300 /// # }
301 /// ```
302 pub fn min_users(&mut self, min_users: u64) -> &mut Self {
303 self.min_users = Some(min_users);
304 self
305 }
306
307 /// Set the `max_users` parameter for instances/list
308 ///
309 /// ```no_run
310 /// # extern crate instances_social;
311 /// # use instances_social::{Client, instances::list::Sort};
312 /// # use std::error::Error;
313 /// const TOKEN: &'static str = "...";
314 ///
315 /// # fn main() -> Result<(), Box<Error>> {
316 /// let client = Client::new(TOKEN);
317 /// let result = client.instances()
318 /// .list()
319 /// .max_users(42)
320 /// .send()?;
321 /// # Ok(())
322 /// # }
323 /// ```
324 pub fn max_users(&mut self, max_users: u64) -> &mut Self {
325 self.max_users = Some(max_users);
326 self
327 }
328
329 /// Set the `min_active_users` parameter for instances/list
330 ///
331 /// ```no_run
332 /// # extern crate instances_social;
333 /// # use instances_social::{Client, instances::list::Sort};
334 /// # use std::error::Error;
335 /// const TOKEN: &'static str = "...";
336 ///
337 /// # fn main() -> Result<(), Box<Error>> {
338 /// let client = Client::new(TOKEN);
339 /// let result = client.instances()
340 /// .list()
341 /// .min_active_users(42)
342 /// .send()?;
343 /// # Ok(())
344 /// # }
345 /// ```
346 pub fn min_active_users(&mut self, min_active_users: u64) -> &mut Self {
347 self.min_active_users = Some(min_active_users);
348 self
349 }
350
351 /// Set the `category` parameter for instances/list
352 ///
353 /// ```no_run
354 /// # extern crate instances_social;
355 /// # use instances_social::{Client, instances::list::Sort};
356 /// # use std::error::Error;
357 /// const TOKEN: &'static str = "...";
358 ///
359 /// # fn main() -> Result<(), Box<Error>> {
360 /// let client = Client::new(TOKEN);
361 /// let result = client.instances()
362 /// .list()
363 /// .category("foo")
364 /// .send()?;
365 /// # Ok(())
366 /// # }
367 /// ```
368 pub fn category(&mut self, category: &str) -> &mut Self {
369 self.category = Some(category.to_string());
370 self
371 }
372
373 /// Set the `language` parameter for instances/list
374 ///
375 /// ```no_run
376 /// # extern crate instances_social;
377 /// # use instances_social::{Client, instances::list::Sort};
378 /// # use std::error::Error;
379 /// const TOKEN: &'static str = "...";
380 ///
381 /// # fn main() -> Result<(), Box<Error>> {
382 /// let client = Client::new(TOKEN);
383 /// let result = client.instances()
384 /// .list()
385 /// .language("foo")
386 /// .send()?;
387 /// # Ok(())
388 /// # }
389 /// ```
390 pub fn language(&mut self, language: &str) -> &mut Self {
391 self.language = Some(language.to_string());
392 self
393 }
394
395 /// Set the `prohibited_content` parameter for instances/list
396 ///
397 /// ```no_run
398 /// # extern crate instances_social;
399 /// # use instances_social::{Client, instances::list::Sort};
400 /// # use std::error::Error;
401 /// const TOKEN: &'static str = "...";
402 ///
403 /// # fn main() -> Result<(), Box<Error>> {
404 /// let client = Client::new(TOKEN);
405 /// let result = client.instances()
406 /// .list()
407 /// .prohibited_content(vec!["foo", "bar"])
408 /// .send()?;
409 /// # Ok(())
410 /// # }
411 /// ```
412 pub fn prohibited_content(&mut self, prohibited_content: Vec<&str>) -> &mut Self {
413 self.prohibited_content = Some(prohibited_content
414 .into_iter()
415 .map(|s| s.to_string())
416 .collect());
417 self
418 }
419
420 /// Set the `allowed_content` parameter for instances/list
421 ///
422 /// ```no_run
423 /// # extern crate instances_social;
424 /// # use instances_social::{Client, instances::list::Sort};
425 /// # use std::error::Error;
426 /// const TOKEN: &'static str = "...";
427 ///
428 /// # fn main() -> Result<(), Box<Error>> {
429 /// let client = Client::new(TOKEN);
430 /// let result = client.instances()
431 /// .list()
432 /// .allowed_content(vec!["foo", "bar"])
433 /// .send()?;
434 /// # Ok(())
435 /// # }
436 /// ```
437 pub fn allowed_content(&mut self, allowed_content: Vec<&str>) -> &mut Self {
438 self.allowed_content = Some(allowed_content
439 .into_iter()
440 .map(|s| s.to_string())
441 .collect());
442 self
443 }
444
445 /// Set the `min_id` parameter for instances/list
446 ///
447 /// ```no_run
448 /// # extern crate instances_social;
449 /// # use instances_social::{Client, instances::list::Sort};
450 /// # use std::error::Error;
451 /// const TOKEN: &'static str = "...";
452 ///
453 /// # fn main() -> Result<(), Box<Error>> {
454 /// let client = Client::new(TOKEN);
455 /// let result = client.instances()
456 /// .list()
457 /// .min_id("124")
458 /// .send()?;
459 /// # Ok(())
460 /// # }
461 /// ```
462 pub fn min_id(&mut self, min_id: &str) -> &mut Self {
463 self.min_id = Some(min_id.to_string());
464 self
465 }
466
467 /// Set the `sort_by` parameter for instances/list
468 ///
469 /// ```no_run
470 /// # extern crate instances_social;
471 /// # use instances_social::{Client, instances::list::Sort};
472 /// # use std::error::Error;
473 /// const TOKEN: &'static str = "...";
474 ///
475 /// # fn main() -> Result<(), Box<Error>> {
476 /// let client = Client::new(TOKEN);
477 /// let result = client.instances()
478 /// .list()
479 /// .sort_by(Sort::Name)
480 /// .send()?;
481 /// # Ok(())
482 /// # }
483 /// ```
484 pub fn sort_by(&mut self, sort_by: Sort) -> &mut Self {
485 self.sort_by = Some(sort_by);
486 self
487 }
488
489 /// Set the `sort_order` parameter for instances/list
490 ///
491 /// ```no_run
492 /// # extern crate instances_social;
493 /// # use instances_social::{Client, instances::list::SortOrder};
494 /// # use std::error::Error;
495 /// const TOKEN: &'static str = "...";
496 ///
497 /// # fn main() -> Result<(), Box<Error>> {
498 /// let client = Client::new(TOKEN);
499 /// let result = client.instances()
500 /// .list()
501 /// .sort_order(SortOrder::Asc)
502 /// .send()?;
503 /// # Ok(())
504 /// # }
505 /// ```
506 pub fn sort_order(&mut self, sort_order: SortOrder) -> &mut Self {
507 self.sort_order = Some(sort_order);
508 self
509 }
510
511 /// convert this to an iterator over `Instance`s
512 ///
513 /// ```no_run
514 /// # extern crate instances_social;
515 /// # use instances_social::Client;
516 /// # use std::error::Error;
517 /// const TOKEN: &'static str = "...";
518 ///
519 /// # fn main() -> Result<(), Box<Error>> {
520 /// let client = Client::new(TOKEN);
521 /// for instance in client.instances().list().iter() {
522 /// println!("{:?}", instance);
523 /// }
524 /// # Ok(())
525 /// # }
526 /// ```
527 pub fn iter(&'a mut self) -> impl Iterator<Item = Instance> + 'a {
528 ItemIterator::new(self)
529 }
530
531 /// Send the request
532 ///
533 /// ```no_run
534 /// # extern crate instances_social;
535 /// # use instances_social::Client;
536 /// # use std::error::Error;
537 /// const TOKEN: &'static str = "...";
538 ///
539 /// # fn main() -> Result<(), Box<Error>> {
540 /// let client = Client::new(TOKEN);
541 /// let result = client.instances().list().send()?;
542 /// # Ok(())
543 /// # }
544 /// ```
545 pub fn send(&self) -> Result<ListResponse, Box<Error>> {
546 let req = self.client.get_qs("instances/list", self)?;
547 Ok(self.client.send(req)?)
548 }
549}