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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
/*
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<u64>,
//!     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: u64,
//!     pub revid: u64,
//! }
//! ```
//!
//! In both cases, you can easily iterate over `ResponseItemlogevents`
//! and `ResponseItem` respectively by calling `Response::items()`.
//!
//! 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.
//!
//! 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 or HTTP
//! library, rather it aims to just provide types and helpers to enable you to
//! run and execute your API requests however you'd like.
//!
//! The [`mwapi`](https://docs.rs/mwapi) crate provides a convenience function
//! to execute a query using these generated responses: `query_response()`.
//!
//! ## Future plans
//! There is no special support for continuing queries. In the future some
//! merge()-like function might be provided.
//!
//! Some other ideas are outlined in [a blog post by Legoktm](https://blog.legoktm.com/2021/11/01/generating-rust-types-for-mediawiki-api-responses.html).
//!
//! ## Contributing
//! `mwapi_responses` is a part of the [`mwbot-rs` project](https://www.mediawiki.org/wiki/Mwbot-rs).
//! We're always looking for new contributors, please [reach out](https://www.mediawiki.org/wiki/Mwbot-rs#Contributing)
//! if you're interested!
#![deny(clippy::all)]

pub mod normalize;
pub mod protection;
pub mod timestamp;

#[cfg(feature = "derive")]
pub use mwapi_responses_derive::query;
/// serde is re-exported for use in the macro
#[doc(hidden)]
pub use serde;
use std::collections::HashMap;
pub mod prelude {
    #[cfg(feature = "derive")]
    pub use crate::query;
    pub use crate::ApiResponse;
}
use std::slice::Iter;
use std::vec::IntoIter;

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) -> Iter<'_, T>;

    /// Iterate and own over main items in this request
    fn into_items(self) -> IntoIter<T>;

    /// Private, for internal usage only
    #[doc(hidden)]
    fn normalized_titles(&self) -> &[normalize::Normalized];

    /// Private, for internal usage only
    #[doc(hidden)]
    fn redirects(&self) -> &[normalize::Redirect];

    /// Get a map of normalized/redirects all merged
    fn title_map(&self) -> HashMap<String, String> {
        let normalized: HashMap<String, String> = self
            .normalized_titles()
            .iter()
            .map(|norm| (norm.from.to_string(), norm.to.to_string()))
            .collect();
        let mut redirects: HashMap<String, String> = self
            .redirects()
            .iter()
            .map(|redir| (redir.from.to_string(), redir.to.to_string()))
            .collect();
        let mut titles = HashMap::new();
        for (from, to) in normalized {
            // See if the normalized title is also a redirect
            let real_to = redirects.remove(&to).unwrap_or(to);
            titles.insert(from, real_to);
        }
        // Merge in the remaining redirects
        titles.extend(redirects);

        titles
    }
}