From 15b8542c97768e1c49e4fb20e7c5d81eab6f9ea2 Mon Sep 17 00:00:00 2001 From: Smitty Date: Fri, 28 May 2021 10:11:49 -0400 Subject: [PATCH] better lib structure/docs --- src/entity.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++-- src/ids.rs | 19 ++++++++++++++++--- src/text.rs | 3 ++- 3 files changed, 67 insertions(+), 6 deletions(-) diff --git a/src/entity.rs b/src/entity.rs index 2e2e85f..baa4483 100755 --- a/src/entity.rs +++ b/src/entity.rs @@ -6,43 +6,72 @@ use serde::{Deserialize, Serialize}; /// A Wikibase entity: this could be an entity, property, or lexeme. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Entity { + /// All of the claims on the entity. pub claims: Vec<(Pid, ClaimValue)>, + /// The type of the entity. pub entity_type: EntityType, - pub description: Text, + /// All of the descriptions in all known languages. + pub description: Vec, + /// All of the labels in all known languages. + pub labels: Vec, } +/// The type of entity: normal entity with a Qid, a property with a Pid, or a lexeme with a Lid. #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[non_exhaustive] pub enum EntityType { + /// An entity with a Qid. Entity, + /// An entity with a Pid. Property, + /// An entity with a Lid. Lexeme, } /// Data relating to a claim value. #[derive(Debug, Clone, Serialize, Deserialize)] pub enum ClaimValueData { + /// The ID of a file on Wikimedia Commons. CommonsMedia(String), + /// Coordinates on some globe. GlobeCoordinate { - //supported + /// Latitude. lat: f64, + /// Longitude. lon: f64, + /// How many degrees of distance of precision there are. precision: f64, + /// The globe the coordnaties are on, usually usually Q2 for Earth. globe: Qid, }, + /// A Wikidata item. Item(Qid), + /// A Wikidata property. Property(Pid), + /// A language-less string of text. Stringg(String), + /// Text with a language. MonolingualText(Text), + /// The same text, translated across multiple languages. MultilingualText(Vec), + /// An external identifier. ExternalID(String), + /// Some numeric quantity of something. Quantity { + /// How much. amount: f64, // technically it could exceed the bound, but meh + /// The lowest possible value. If this isn't present then it is exactly the amount. lower_bound: Option, + /// The highest possible value. If this isn't present then it is exactly the amount. upper_bound: Option, + /// The units used. unit: Option, // *could* be any IRI but in practice almost all are Wikidata entity IRIs }, + /// A point in time time. DateTime { + /// The time as a Chrono DateTime. date_time: DateTime, + /// The precision of the date: /// 0 - billion years /// 1 - 100 million years /// 2 - 10 million years @@ -60,15 +89,25 @@ pub enum ClaimValueData { /// 14 - second (deprecated) precision: u8, }, + /// A URL. Url(String), + /// A LaTeX math expression. MathExpr(String), + /// A geometric shape. The value of the string is currently unspecified. GeoShape(String), + /// LilyPond musical notation. MusicNotation(String), + /// ID of a file with tabular data on Wikimedia commons. TabularData(String), + /// A lexeme ID on Wikidata. Lexeme(Lid), + /// A form ID on Wikidata. Form(Fid), + /// A sense ID on Wikidata. Sense(Sid), + /// No value. NoValue, + /// Unknown value. UnknownValue, } @@ -95,20 +134,24 @@ impl Default for Rank { /// A group of claims that make up a single reference. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ReferenceGroup { + /// All of the claims. pub claims: Vec<(Pid, ClaimValueData)>, } /// A claim value. #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct ClaimValue { + /// The data of the claim. pub data: ClaimValueData, pub rank: Rank, + /// The globally unique claim ID. pub id: String, pub qualifiers: Vec<(Pid, ClaimValueData)>, pub references: Vec, } impl Entity { + /// All of the values of "instance of" on the entity. pub fn instances(&self) -> Vec { let mut instances = Vec::with_capacity(1); for (pid, claim) in &self.claims { @@ -122,6 +165,7 @@ impl Entity { instances } + /// When the entity started existing. pub fn start_time(&self) -> Option> { for (pid, claim) in &self.claims { if *pid == consts::DATE_OF_BIRTH { @@ -133,6 +177,7 @@ impl Entity { None } + /// When the entity stopped existing. pub fn end_time(&self) -> Option> { for (pid, claim) in &self.claims { if *pid == consts::DATE_OF_DEATH { @@ -145,6 +190,7 @@ impl Entity { } } +/// An error related to entity parsing/creation. #[derive(Debug, Clone, PartialEq, Eq)] #[non_exhaustive] pub enum EntityError { @@ -369,6 +415,7 @@ impl ClaimValueData { } impl ClaimValue { + /// Try to parse a JSON claim to a claim value. #[must_use] pub fn get_prop_from_snak(mut claim: json::JsonValue, skip_id: bool) -> Option { let claim_str = take_prop("rank", &mut claim) diff --git a/src/ids.rs b/src/ids.rs index c2e40c7..4b4e1b9 100755 --- a/src/ids.rs +++ b/src/ids.rs @@ -3,9 +3,12 @@ use serde::{Deserialize, Serialize}; use std::{num::ParseIntError, str::FromStr}; +/// An error parsing an ID. #[derive(Debug, Clone)] pub enum IdParseError { + /// The number couldn't be parsed. UnparseableNumber(ParseIntError), + /// The ID had an invalid prefix letter. InvalidPrefix, } @@ -14,6 +17,8 @@ macro_rules! id_def { #[derive( Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize, )] + #[doc = "A Wikidata"] + #[doc = $full_name] pub struct $name(pub u64); impl $name { @@ -50,6 +55,7 @@ macro_rules! id_def { } } impl std::fmt::Display for $name { + /// Display the ID as it would be in a URI. fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, concat!($letter, "{}"), self.0) } @@ -63,15 +69,14 @@ id_def!(Lid, "lexeme ID", "L"); /// A lexeme ID and associated form ID #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)] -// see id_def! comment about datatype pub struct Fid(pub Lid, pub u16); /// A lexeme ID and assoicated sense ID #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)] -// see id_def! comment about datatype pub struct Sid(pub Lid, pub u16); impl ToString for Fid { + /// Display the ID as it would be in a URI. #[must_use] fn to_string(&self) -> String { match self { @@ -81,6 +86,7 @@ impl ToString for Fid { } impl ToString for Sid { + /// Display the ID as it would be in a URI. #[must_use] fn to_string(&self) -> String { match self { @@ -107,7 +113,7 @@ macro_rules! pid_consts ( macro_rules! qid_unit_suffixes { { $($key:ident => $value:expr),+, } => { #[must_use] - pub fn unit_suffix(qid: Qid) -> Option<&'static str> { + pub(super) fn unit_suffix(qid: Qid) -> Option<&'static str> { $( if qid == $key { Some($value) @@ -120,6 +126,13 @@ macro_rules! qid_unit_suffixes { }; } +impl Qid { + /// If the Qid is a commonly used unit on Wikidata, get it as a unit suffix. + pub fn unit_suffix(self) -> Option<&'static str> { + consts::unit_suffix(self) + } +} + #[allow(clippy::unreadable_literal)] /// Various IDs for commonly used entities/properties on Wikidata. pub mod consts { diff --git a/src/text.rs b/src/text.rs index 5faa734..06e6d80 100644 --- a/src/text.rs +++ b/src/text.rs @@ -1,9 +1,10 @@ use serde::{Deserialize, Serialize}; -/// A language used in the Wikibase data model. +/// A language, as used in the Wikibase data model. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] pub struct Lang(pub String); +/// Text that is in a certain language. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] pub struct Text { pub text: String,