Commit aa27aafd authored by Leonardo Schwarz's avatar Leonardo Schwarz

Docs for the entities module and some small fixes.

parent fa0af270
......@@ -35,10 +35,11 @@ enum_mb_xml!{
}
/// A geographic region or settlement.
///
/// The exact type is distinguished by the `area_type` field.
/// This is one of the *core entities* of MusicBrainz.
///
/// https://musicbrainz.org/doc/Area
/// [MusicBrainz documentation](https://musicbrainz.org/doc/Area).
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Area {
/// MBID of the entity in the MusicBrainz database.
......@@ -51,7 +52,7 @@ pub struct Area {
/// characters.
pub sort_name: String,
/// The type of the area.
/// Type of the area, gives more information about
pub area_type: AreaType,
/// ISO 3166 code, assigned to countries and subdivisions.
......
......@@ -5,34 +5,17 @@ use entities::{Mbid, Resource};
use entities::date::PartialDate;
use entities::refs::AreaRef;
/// TODO: Find all possible variants. (It says "male, female or neither" in the
/// docs but what does
/// this mean. Is there a difference between unknown genders and non-binary
/// genders?)
/// TODO rewrite using macro.
#[derive(Debug, Clone, Eq, PartialEq)]
pub enum Gender {
Female,
Male,
Other(String),
}
impl FromXml for Gender {
fn from_xml<'d, R>(reader: &'d R) -> Result<Self, FromXmlError>
where
R: XpathReader<'d>,
{
let s = String::from_xml(reader)?;
match s.as_str() {
"Female" => Ok(Gender::Female),
"Male" => Ok(Gender::Male),
"" => Err(FromXmlError::Absent),
other => Ok(Gender::Other(other.to_string())),
}
enum_mb_xml! {
/// Specification of the gender of an artist.
pub enum Gender {
var Female = "Female",
var Male = "Male",
var Other = "Other",
}
}
enum_mb_xml! {
/// Specifies what an `Artist` instance actually is.
pub enum ArtistType {
var Person = "Person",
var Group = "Group",
......@@ -43,12 +26,12 @@ enum_mb_xml! {
}
}
/// A musician, a group or another music professional. There are also a couple
/// special purpose
/// artists.
/// A musician, a group or another music professional.
///
/// There are also a couple special purpose artists.
///
/// Additional information can be found in the MusicBrainz wiki:
/// https://musicbrainz.org/doc/Artist
/// Additional information can be found in the [MusicBrainz
/// docs](https://musicbrainz.org/doc/Artist).
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Artist {
/// MBID of the entity in the MusicBrainz database.
......@@ -58,43 +41,53 @@ pub struct Artist {
pub name: String,
/// Name to properly sort the artist by.
///
/// Even for artists whose `name` is written in a different script this one
/// will be in latin
/// script. The full
/// will be in latin script. The full
/// [guidelines](https://musicbrainz.org/doc/Style/Artist/Sort_Name) are a
/// bit more complicated.
pub sort_name: String,
/// Aliases of the artist name. These include alternative official
/// spellings, and common
/// misspellings, versions in different scripts and other variations of the
/// artist name.
/// Aliases of the `Artist`'s name. These include alternative official
/// spellings, common misspellings, versions in different scripts and
/// other variations of the `Artist` name.
pub aliases: Vec<String>,
/// Additional disambiguation if there are multiple artists with the exact
/// same name.
/// Any additional free form annotation for this `Artist`.
///
/// This can include things like biographies, descriptions of their musical
/// style, etc.
pub annotation: Option<String>,
/// Additional disambiguation if there are multiple `Artist`s with the same
/// name.
pub disambiguation: Option<String>,
/// Whether this Artist is a person, group, or something else.
/// Whether this `Artist` is a person, group, or something else.
pub artist_type: Option<ArtistType>,
/// If the Artist is a single person this indicates their gender.
/// If the `Artist` is a single person this indicates their gender.
pub gender: Option<Gender>,
/// The area an artist is primarily identified with. Often, but not always,
/// birth/formation
/// country of the artist/group.
/// The area an `Artist` is primarily identified with. Often, but not
/// always, birth/formation country of the artist/group.
pub area: Option<AreaRef>,
// TODO docs
/// For a single person: date of birth.
///
/// For a group of people: formation date.
pub begin_date: Option<PartialDate>,
// TODO docs
/// For a deceased person: date of death.
///
/// For a group of people: dissolution date.
pub end_date: Option<PartialDate>,
// TODO docs
/// [IPI Code](https://wiki.musicbrainz.org/IPI) of the `Artist`.
pub ipi_code: Option<String>,
// TODO docs
pub isni_code: Option<String>, // TODO disambiguation comment
/// [ISNI Code](https://wiki.musicbrainz.org/ISNI) of the `Artist`.
pub isni_code: Option<String>,
}
impl FromXmlContained for Artist {}
......@@ -105,6 +98,7 @@ impl FromXml for Artist {
{
Ok(Artist {
aliases: reader.read_vec(".//mb:artist/mb:alias-list/mb:alias/text()")?,
annotation: reader.read_option(".//mb:artist/mb:annotation/text()")?,
area: reader.read_option(".//mb:artist/mb:area")?,
artist_type: reader.read_option(".//mb:artist/@type")?,
begin_date: reader.read_option(".//mb:artist/mb:life-span/mb:begin/text()")?,
......
......@@ -14,40 +14,43 @@ enum_mb_xml! {
}
}
/// An organized event people can attend, these are generally live performances.
///
/// Additional information can be found in the [MusicBrainz
/// docs](https://musicbrainz.org/doc/Event)
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Event {
/// MBID of the entity in the MusicBrainz database.
mbid: Mbid,
pub mbid: Mbid,
/// The official name of the event or a descriptive name if the event
/// doesn't have an official
/// name.
name: String,
/// doesn't have an official name.
pub name: String,
/// Aternative event names.
aliases: Vec<String>,
pub aliases: Vec<String>,
/// Describes what type of event this is exactly.
event_type: Option<EventType>,
pub event_type: Option<EventType>,
/// List of songs played at the event.
///
/// This is provided in an extensive text format, for which parsing is not
/// yet implemented.
setlist: Option<String>,
pub setlist: Option<String>,
/// Begin date of the event.
begin_date: PartialDate,
pub begin_date: PartialDate,
/// End date of the event.
end_date: Option<PartialDate>,
pub end_date: Option<PartialDate>,
// TODO: start_time: Time
/// Disambiguation to distinguish Event from other Events with the same
/// name (if existent).
disambiguation: Option<String>,
/// Additional disambiguation if there are multiple `Event`s with the same
/// name.
pub disambiguation: Option<String>,
/// Additional, unstructured information about the event.
annotation: Option<String>,
/// Any additional free form annotation for this `Event`.
pub annotation: Option<String>,
}
impl Resource for Event {
......
//! Defines types representing the entities from the MusicBrainz database.
/// TODO consider what type to use
pub use std::time::Duration;
......@@ -39,23 +41,28 @@ pub use self::mbid::Mbid;
// TODO: Convert get_name and base_url into associated consts once these land
// in stable rust.
/// A Resource is any entity which can be directly retrieved from MusicBrainz.
///
/// We define this trait for the sake of using the `Client` type more
/// efficiently, users of the `musicbrainz` crate shouldn't need to use this
/// type directly.
pub trait Resource {
/// Returns the name of the Resource, e. g. "Artist".
/// Returns the name of the Resource, e. g. `"Artist"`.
fn get_name() -> &'static str;
/// Returns the url where one can get a ressource in the valid format for
/// Returns the url where one can get a resource in the valid format for
/// parsing from.
fn get_url(mbid: &Mbid) -> String;
/// Base url of the entity, for example:
/// `https://musicbrainz.org/ws/2/artist/`.
/// These are used for searches for example.
/// Base url of the entity, e. g. `"https://musicbrainz.org/ws/2/artist/"`.
///
/// These are used for building search requests.
fn base_url() -> &'static str;
}
pub struct Work {}
// TODO pub struct Work {}
pub struct Url {}
// TODO pub struct Url {}
// TODO: rating, tag, collection
// TODO: discid, isrc, iswc
......@@ -4,6 +4,7 @@ use xpath_reader::{FromXml, FromXmlError, XpathReader};
use xpath_reader::reader::{FromXmlContained, FromXmlElement};
enum_mb_xml! {
/// Specifies what a `Place` instance actually is.
pub enum PlaceType {
var Studio = "Studio",
var Venue = "Venue",
......@@ -14,7 +15,10 @@ enum_mb_xml! {
}
}
/// TODO: Parsing of the coordinate values.
/// A pair of coordinates on the surface of planet earth.
///
/// TODO: Parsing of the coordinate values, currently they are only unchecked
/// string values.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Coordinates {
pub latitude: String,
......@@ -36,31 +40,43 @@ impl FromXml for Coordinates {
/// A venue, studio or other place where music is performed, recorded,
/// engineered, etc.
///
/// Additional information can be found in the [MusicBrainz
/// docs](https://musicbrainz.org/doc/Place).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Place {
/// MBID of the entity in the MusicBrainz database.
pub mbid: Mbid,
/// The official name of a place.
/// The official name of a `Place`.
pub name: String,
/// The type of the place.
/// The type of the `Place`.
pub place_type: Option<PlaceType>,
/// Address of the place in the local adressing format.
/// Address of the `Place` in the local adressing format.
pub address: Option<String>,
/// The exact coordinates of the place.
pub coordinates: Option<Coordinates>,
/// Specifies the `Area` the `Place` is located in.
pub area: Option<AreaRef>,
/// When the `Place` was founded.
pub begin: Option<PartialDate>,
/// When the `Place` closed down.
pub end: Option<PartialDate>,
/// Alternative versions of this `Place`'s name.
pub aliases: Vec<String>,
/// Additional disambiguation if there are multiple places with the same
/// name.
pub disambiguation: Option<String>,
/// Any additional free form annotation for this `Place`.
pub annotation: Option<String>,
}
......@@ -71,17 +87,17 @@ impl FromXml for Place {
R: XpathReader<'d>,
{
Ok(Place {
mbid: reader.read(".//mb:place/@id")?,
name: reader.read(".//mb:place/mb:name/text()")?,
place_type: reader.read_option(".//mb:place/@type")?,
address: reader.read_option(".//mb:place/mb:address/text()")?,
coordinates: reader.read_option(".//mb:place/mb:coordinates")?,
aliases: reader.read_vec(".//mb:place/mb:aliases/text()")?,
annotation: reader.read_option(".//mb:place/mb:annotation/text()")?,
area: reader.read_option(".//mb:place/mb:area")?,
begin: reader.read_option(".//mb:place/mb:life-span/mb:begin/text()")?,
end: reader.read_option(".//mb:place/mb:life-span/mb:end/text()")?,
aliases: reader.read_vec(".//mb:place/mb:aliases/text()")?,
coordinates: reader.read_option(".//mb:place/mb:coordinates")?,
disambiguation: reader.read_option(".//mb:place/mb:disambiguation/text()")?,
annotation: reader.read_option(".//mb:place/mb:annotation/text()")?,
end: reader.read_option(".//mb:place/mb:life-span/mb:end/text()")?,
mbid: reader.read(".//mb:place/@id")?,
name: reader.read(".//mb:place/mb:name/text()")?,
place_type: reader.read_option(".//mb:place/@type")?,
})
}
}
......
......@@ -6,12 +6,16 @@ use entities::{Mbid, Resource};
use entities::date::PartialDate;
use entities::refs::{ArtistRef, LabelRef, RecordingRef};
/// Describes a single track, `Releases` consist of multiple `ReleaseTrack`s.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ReleaseTrack {
/// MBID of the entity in the MusicBrainz database.
pub mbid: Mbid,
// TODO: docstring ; what is the difference between `position` and `number`???
/// The position of the track on the `Release`.
///
/// TODO (clarification) : what is the difference between `position` and
/// `number`???
pub position: u16,
/// The track number as listed in the release.
......@@ -90,16 +94,15 @@ enum_mb_xml! {
var Bootleg = "Bootleg",
/// An alternate version of a release where the titles have been changed.
/// These don't correspond to any real release and should be linked to the
/// original release
/// using the transliteration relationship.
/// These don't correspond to any real release and should actually be linked to the
/// original release using the transliteration relationship.
///
/// TL;DR: Essentially this shouldn't be used.
var PseudoRelease = "Pseudo-Release",
}
}
/// Lists information about a release.
/// Lists information about a `Release`.
///
/// Note that its both possible to find a `LabelInfo` with only one of `label`
/// or `cat_num`.
......@@ -131,7 +134,8 @@ impl FromXml for LabelInfo {
}
}
#[derive(Clone, Debug)]
/// A `Release` is any publication of one or more tracks.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Release {
/// MBID of the entity in the MusicBrainz database.
pub mbid: Mbid,
......@@ -183,20 +187,20 @@ impl FromXml for Release {
R: XpathReader<'d>,
{
Ok(Release {
mbid: reader.read(".//mb:release/@id")?,
title: reader.read(".//mb:release/mb:title/text()")?,
artists: reader.read_vec(".//mb:release/mb:artist-credit/mb:name-credit")?,
date: reader.read_option(".//mb:release/mb:date/text()")?,
barcode: reader.read_option(".//mb:release/mb:barcode/text()")?,
country: reader.read_option(".//mb:release/mb:country/text()")?,
date: reader.read_option(".//mb:release/mb:date/text()")?,
disambiguation: reader.read_option(".//mb:release/mb:disambiguation/text()")?,
labels: reader.read_vec(".//mb:release/mb:label-info-list/mb:label-info")?,
barcode: reader.read_option(".//mb:release/mb:barcode/text()")?,
status: reader.read_option(".//mb:release/mb:status/text()")?,
packaging: reader.read_option(".//mb:release/mb:packaging/text()")?,
language:
reader.read_option(".//mb:release/mb:text-representation/mb:language/text()")?,
script: reader.read_option(".//mb:release/mb:text-representation/mb:script/text()")?,
disambiguation: reader.read_option(".//mb:release/mb:disambiguation/text()")?,
mbid: reader.read(".//mb:release/@id")?,
mediums: reader.read_vec(".//mb:release/mb:medium-list/mb:medium")?,
packaging: reader.read_option(".//mb:release/mb:packaging/text()")?,
script: reader.read_option(".//mb:release/mb:text-representation/mb:script/text()")?,
status: reader.read_option(".//mb:release/mb:status/text()")?,
title: reader.read(".//mb:release/mb:title/text()")?,
})
}
}
......
......@@ -54,8 +54,9 @@ impl FromXml for ReleaseGroupType {
}
/// Groups multiple `Release`s into one a single logical entity.
/// Even if there is only one release of a kind, it belongs to exactly one
/// release group.
///
/// Even if there is only one `Release` of a kind, it belongs to exactly one
/// `ReleaseGroup`.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ReleaseGroup {
/// MBID of the entity in the MusicBrainz database.
......@@ -74,10 +75,11 @@ pub struct ReleaseGroup {
/// The type of this release group.
pub release_type: ReleaseGroupType,
// TODO docstring
/// Additional disambiguation if there are multiple `ReleaseGroup`s with
/// the same name.
pub disambiguation: Option<String>,
// TODO: docstring
/// Any additional free form annotation for this `ReleaseGroup`.
pub annotation: Option<String>,
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment