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
/*
Copyright (C) Tim Starling
Copyright (C) Daniel Kinzler
Copyright (C) 2021 Kunal Mehta <legoktm@debian.org>
Copyright (C) 2021 Erutuon
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 <http://www.gnu.org/licenses/>.
*/
//! mwtitle
//! =======
//!
//! `mwtitle` is a library for parsing, normalizing and formatting MediaWiki
//! page titles. It is primarily a port of the MediaWikiTitleCodec class
//! from MediaWiki, and passes the MediaWiki test suite.
//!
//! The easiest way to get started is create a [`TitleCodec`] from a [siteinfo](https://www.mediawiki.org/wiki/API:Siteinfo)
//! API request.
//! ```
//! # #[tokio::main]
//! # async fn main() -> anyhow::Result<()> {
//! # #[cfg(feature = "parsing")]
//! # {
//! # use mwtitle::{SiteInfoResponse, TitleCodec};
//! let url = "https://en.wikipedia.org/w/api.php\
//! ?action=query&meta=siteinfo\
//! &siprop=general|namespaces|namespacealiases|interwikimap\
//! &formatversion=2&format=json";
//! let resp: SiteInfoResponse = reqwest::get(url).await?.json().await?;
//! let codec = TitleCodec::from_site_info(resp.query)?;
//! let title = codec.new_title("Talk:Main Page#Section 1")?;
//! assert_eq!(title.namespace(), 1);
//! assert_eq!(title.dbkey(), "Main_Page");
//! assert_eq!(title.fragment(), Some("Section 1"));
//! assert_eq!(codec.to_pretty(&title), "Talk:Main Page".to_string());
//! assert_eq!(
//! codec.to_pretty_with_fragment(&title),
//! "Talk:Main Page#Section 1".to_string()
//! );
//! # }
//! # Ok(())
//! # }
//! ```
//!
//! It's also possible to possible to create a `TitleCodec` from a JSON
//! `siteinfo-namespaces.json` or compressed `siteinfo-namespaces.json.gz`
//! that comes from Wikimedia dumps. This requires the extra `utils` feature
//! to be enabled.
//!
//! ## Contributing
//! `mwtitle` 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!
#![cfg_attr(docs, feature(doc_cfg))]
#[cfg(feature = "parsing")]
#[cfg_attr(docs, doc(cfg(feature = "parsing")))]
mod codec;
mod display;
mod error;
mod interwiki_set;
#[cfg(feature = "parsing")]
#[cfg_attr(docs, doc(cfg(feature = "parsing")))]
mod ip;
#[cfg(feature = "parsing")]
#[cfg_attr(docs, doc(cfg(feature = "parsing")))]
mod ipv6;
mod namespace_map;
#[cfg(feature = "parsing")]
#[cfg_attr(docs, doc(cfg(feature = "parsing")))]
mod php;
mod site_info;
#[cfg(feature = "parsing")]
pub use codec::TitleCodec;
pub use error::Error;
pub use interwiki_set::InterwikiSet;
pub use namespace_map::NamespaceMap;
pub use site_info::{
Interwiki, NamespaceAlias, NamespaceInfo, Response as SiteInfoResponse,
SiteInfo,
};
pub type Result<T, E = Error> = std::result::Result<T, E>;
const NS_MAIN: i32 = 0;
const NS_FILE: i32 = 6;
const NS_CATEGORY: i32 = 14;
/// Represents a MediaWiki title. A title can be broken down into the following
/// attributes: `[[interwiki:ns:db_key#fragment]]`.
/// * `interwiki`: Optional prefix pointing to another site
/// * `namespace`: Numerical ID corresponding to a MediaWiki namespace
/// * `dbkey`: Page name, with underscores instead of spaces
/// * `fragment`: Optional anchor for a specific section
///
/// ```
/// # use mwtitle::Title;
/// // ns1 is Talk, so this is [[Talk:Main Page]]
/// let title = Title::new_unchecked(1, "Main_Page");
/// assert_eq!(title.namespace(), 1);
/// assert_eq!(title.dbkey(), "Main_Page");
/// assert!(title.interwiki().is_none());
/// assert!(title.fragment().is_none());
/// let title = title.with_fragment("Section 1");
/// assert_eq!(title.fragment(), Some("Section 1"));
/// ```
#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
pub struct Title {
namespace: i32,
dbkey: String,
fragment: Option<String>,
interwiki: Option<String>,
local_interwiki: bool,
}
impl Title {
/// Create a new `Title`, with no validation on the namespace
/// or text parts. Good if you're getting the title from a
/// trusted place like the API. If the namespace does not exist
/// in the `TitleCodec` this is used with it can result in panics.
///
/// Note that text is supposed to be the database key,
/// with no namespace prefix.
pub fn new_unchecked(namespace: i32, text: &str) -> Self {
Self {
namespace,
// Normalize dbkey just because it's easy
dbkey: text.replace(' ', "_"),
fragment: None,
interwiki: None,
local_interwiki: false,
}
}
/// Set a fragment.
pub fn with_fragment(mut self, fragment: &str) -> Self {
self.fragment = Some(fragment.to_string());
self
}
/// Remove the fragment.
pub fn remove_fragment(mut self) -> Self {
self.fragment = None;
self
}
/// Get the namespace ID.
pub fn namespace(&self) -> i32 {
self.namespace
}
/// Get the dbkey.
pub fn dbkey(&self) -> &str {
&self.dbkey
}
/// Get the fragment, if there is one.
pub fn fragment(&self) -> Option<&str> {
self.fragment.as_deref()
}
/// Get the interwiki, if there is one.
pub fn interwiki(&self) -> Option<&str> {
self.interwiki.as_deref()
}
/// Whether this title was created via a local interwiki link.
pub fn is_local_interwiki(&self) -> bool {
self.local_interwiki
}
/// If the title is a local page that could exist, basically not an
/// interwiki link, nor a fragment-only link, nor a special page.
pub fn is_local_page(&self) -> bool {
self.interwiki.is_none()
&& !self.dbkey.is_empty()
&& self.namespace >= 0
}
/// Whether this title refers to a file.
pub fn is_file(&self) -> bool {
self.namespace == NS_FILE
}
/// Whether this title refers to a category.
pub fn is_category(&self) -> bool {
self.namespace == NS_CATEGORY
}
}