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 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
/*
Copyright (C) 2020-2021 Kunal Mehta <legoktm@debian.org>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
//! mwapi_responses
//! ===============
//!
//! The `mwapi_responses` crate provides strict typing for dynamic MediaWiki
//! Action API queries. The goal is to faithfully represent what the API's
//! JSON structure is while saving people from manually writing out
//! serde-compatible structs for every query.
//!
//! A list module:
//! ```
//! use mwapi_responses::prelude::*;
//! #[query(
//! list = "logevents",
//! leaction = "newusers/create",
//! leprop = "user|type",
//! lelimit = "100"
//! )]
//! struct Response;
//! ```
//!
//! This creates a `Response` struct that matches the API response for the given
//! query. Roughly, it will expand to:
//!
//! ```ignore
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct Response {
//! #[serde(default)]
//! pub batchcomplete: bool,
//! #[serde(rename = "continue")]
//! #[serde(default)]
//! pub continue_: HashMap<String, String>,
//! pub query: ResponseBody,
//! }
//!
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct ResponseBody {
//! pub logevents: Vec<ResponseItemlogevents>,
//! }
//!
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct ResponseItemlogevents {
//! pub user: String,
//! #[serde(rename = "type")]
//! pub type_: String,
//! }
//! ```
//!
//! Or getting various properties from pages:
//! ```
//! use mwapi_responses::prelude::*;
//! #[query(
//! prop="info|revisions",
//! inprop="url",
//! rvprop="ids"
//! )]
//! struct Response;
//! ```
//! which expands to:
//! ```ignore
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct Response {
//! #[serde(default)]
//! pub batchcomplete: bool,
//! #[serde(rename = "continue")]
//! #[serde(default)]
//! pub continue_: HashMap<String, String>,
//! pub query: ResponseBody,
//! }
//!
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct ResponseBody {
//! pub pages: Vec<ResponseItem>,
//! }
//!
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct ResponseItem {
//! pub canonicalurl: String,
//! pub contentmodel: String,
//! pub editurl: String,
//! pub fullurl: String,
//! pub lastrevid: Option<u32>,
//! pub length: Option<u32>,
//! #[serde(default)]
//! pub missing: bool,
//! #[serde(default)]
//! pub new: bool,
//! pub ns: i32,
//! pub pageid: Option<u32>,
//! pub pagelanguage: String,
//! pub pagelanguagedir: String,
//! pub pagelanguagehtmlcode: String,
//! #[serde(default)]
//! pub redirect: bool,
//! pub title: String,
//! pub touched: Option<String>,
//! #[serde(default)]
//! pub revisions: Vec<ResponseItemrevisions>,
//! }
//!
//! #[derive(Debug, Clone, serde::Deserialize)]
//! pub struct ResponseItemrevisions {
//! pub parentid: u32,
//! pub revid: u32,
//! }
//! ```
//!
//! In both cases, you can easily iterate over `ResponseItemlogevents`
//! and `ResponseItem` respectively by calling `Response::items()`.
//!
//! ## Field naming
//! Fields are renamed if they can't be used as fields in Rust, like `continue`
//! or `type`. In these cases, an underscore is appended.
//!
//! ## Supported modules
//! The metadata that powers this crate is manually gathered. To see if
//! a specific module is supported, look at the [Git repository](https://gitlab.com/mwbot-rs/mwbot/-/tree/master/mwapi_responses_derive/data).
//! Contributions for missing modules or parameters are always welcome.
//!
//! ## Library agnostic
//! This crate does not implement or support any one specific API library,
//! rather it aims to just provide types and helpers to enable you to run
//! your API requests however you'd like.
//!
//! ## Helper functions
//! To avoid repeating the parameters in multiple places, you can call
//! `Response::params()` to get a `&[(&str, &str)]` of the parameters that
//! were provided to the `#[query(...)]` macro.
//!
//! ## Not yet implemented
//! There is no special support for continuing queries. In the future some
//! merge()-like function might be provided.
pub use mwapi_responses_derive::query;
pub use serde;
pub mod prelude {
pub use crate::{query, ApiResponse};
}
use std::collections::HashMap;
pub mod protection;
pub mod redirects;
pub trait ApiResponse<T> {
/// Get the request params to send to the API
fn params() -> &'static [(&'static str, &'static str)];
/// Iterate over the main items in this request
fn items(&self) -> &[T];
fn get_continue(&self) -> &HashMap<String, String>;
fn has_continue(&self) -> bool {
!self.get_continue().is_empty()
}
}