ug_scraper/lib.rs
1// UG-Scraper - A basic rust API for getting data from Ultimate Guitar
2// Copyright (C) 2025 Linus Tibert
3//
4// This program was originally published under the MIT licence as seen
5// here: https://github.com/Lich-Corals/ug-tab-scraper-rs/blob/mistress/LICENCE
6
7/// Functions used by other modules for network access
8pub mod network;
9/// API for searching tabs on UG
10pub mod search_scraper;
11/// API for getting a tab from UG
12pub mod tab_scraper;
13
14/// Errors possibly occuring in the crate
15pub mod error {
16 use std::error::Error;
17 use std::fmt;
18
19 /// Possible errors
20 #[derive(Debug, PartialEq, Clone, Eq, Hash)]
21 pub enum UGError {
22 /// Occurs when an unsupported HTML is attempted to be evaluated.
23 InvalidHTMLError,
24 /// Occurs when an unsupported URL is attempted to be downloaded as a tab.
25 InvalidURLError,
26 /// Occurs when a tab without any available metadata is attempted to be downloaded.
27 NoBasicDataMatchError,
28 /// Occurs when any data extracting function gets unexpected data from UG.
29 ///
30 /// E.g. if a string value is found in a place where a float is expected.
31 UnexpectedWebResultError,
32 /// Is returned by types_and_values::get_data_type() if the provided string does not match any known type of tab.
33 UnknownTypeError,
34 }
35
36 impl fmt::Display for UGError {
37 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
38 write!(f, "{}", self.clone())
39 }
40 }
41
42 impl Error for UGError {}
43}
44
45/// Types, constants and closely associated functions which are used by across the crate
46///
47/// All of the defined types have the [`serde::Serialize`] and [`serde::Deserialize`] traits.
48pub mod types {
49 use crate::error::UGError;
50 use serde::{Deserialize, Serialize};
51 use std::fmt;
52
53 /// A list of tab types supported for downloading
54 ///
55 /// Includes Chords, Tabs, Bass Tabs, Ukulele Chords and Drum Tabs
56 pub const SUPPORTED_DOWNLOAD_TYPES: [DataSetType; 5] = [
57 DataSetType::Chords,
58 DataSetType::Tab,
59 DataSetType::Bass,
60 DataSetType::Ukulele,
61 DataSetType::Drums,
62 ];
63
64 /// Known types of tab on UG. Includes unsupported ones.
65 #[derive(Debug, PartialEq, Default, Eq, Clone, Copy, Hash, Serialize, Deserialize)]
66 pub enum DataSetType {
67 #[default]
68 Unknown,
69 /// Downloading supported
70 Chords,
71 /// Downloading supported
72 Tab,
73 /// Downloading supported
74 Ukulele,
75 /// Downloading supported
76 Bass,
77 /// Downloading supported
78 Drums,
79 /// Downloading not supported
80 Official,
81 /// Downloading not supported
82 Pro,
83 /// Downloading not supported
84 Power,
85 /// Downloading not supported
86 Video,
87 }
88
89 impl fmt::Display for DataSetType {
90 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
91 write!(f, "{:?}", self)
92 }
93 }
94
95 /// Possible types of line in a `Song`
96 #[derive(Debug, PartialEq, Eq, Default, Clone, Copy, Hash, Serialize, Deserialize)]
97 pub enum DataType {
98 #[default]
99 /// Lines with Chords detected by UG
100 Chord,
101 /// Plain text
102 Lyric,
103 /// The title of a song section
104 ///
105 /// (e.g.: \[chorus\], \[intro\], etc.)
106 SectionTitle,
107 }
108
109 impl fmt::Display for DataType {
110 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
111 write!(f, "{:?}", self)
112 }
113 }
114
115 /// A set of data returned as sarch result
116 ///
117 /// This struct is normally automatically generated by [`crate::search_scraper::get_search_results`] or [`crate::search_scraper::search_page`].
118 #[derive(Debug, PartialEq, Default, Clone, Serialize, Deserialize)]
119 pub struct SearchResult {
120 /// The basic metadata of the search result (tab)
121 pub basic_data: BasicSongData,
122 /// Amount of ratings given by users on UG
123 pub rating_count: u32,
124 /// Rating on UG (0.0 - 5.0)
125 pub rating_value: f32,
126 }
127
128 impl fmt::Display for SearchResult {
129 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
130 write!(f, "{:?}", self)
131 }
132 }
133
134 /// A single line of a tab
135 ///
136 /// This struct is normally generated by [`crate::tab_scraper::get_tab_lines`].
137 #[derive(Debug, PartialEq, Default, Clone, Serialize, Deserialize)]
138 pub struct Line {
139 /// Type data stored on the line
140 pub line_type: DataType,
141 /// The contents on the line as plain text
142 pub text_data: String,
143 }
144
145 impl Line {
146 /// Replace german chord names with english ones
147 ///
148 /// Musical notation is one of the things Germans did their own, slightly more complicated way.
149 /// This function will replace german names for chords with their english equivalents.
150 ///
151 /// ## Example:
152 /// ```
153 /// use ug_scraper::types::{Line, DataType};
154 ///
155 /// // Create a line with German chord names H, Dmoll, Fis, Es and B
156 /// let mut line: Line = Line { line_type: DataType::Chord,
157 /// text_data: "A H C Dmoll Fis Es B".to_string() };
158 ///
159 /// // Replace the weïrd chord names
160 /// line = line.replace_german_names();
161 /// // Returns:
162 /// // "A B C Dm F# Eb Bb"
163 ///
164 /// ```
165 ///
166 /// Note:
167 /// Some of the German chord notations (e.g. Fes or Dmoll) are rarely found in any tabs.
168 /// But to ensure they don't confuse anyone, they are included in this function too.
169 pub fn replace_german_names(mut self) -> Line {
170 if self.line_type == DataType::Chord {
171 let entries: [&'static str; 18] = [
172 "Ces", "Cis", "Des", "Dis", "Es", "Eis", "Fes", "Fis",
173 "Ges", "Gis", "As", "Ais", "H", "Bes", "His", "Bis", "dur",
174 "moll",
175 ];
176 let replacements: [&'static str; 18] = [
177 "Cb ", "C# ", "Db ", "D# ", "Eb", "E# ", "Fb ", "F# ",
178 "Gb ", "G# ", "Ab", "A# ", "B", "Bb ", "B# ", "B# ", "maj",
179 "m ",
180 ];
181 if entries
182 .iter()
183 .any(|entry: &&str| self.text_data.contains(entry))
184 {
185 self.text_data = self
186 .text_data
187 .replace("B", "Bb")
188 .replace("Bb ", "Bb ");
189
190 for i in 0..entries.len() {
191 self.text_data = self
192 .text_data
193 .replace(entries[i], replacements[i]);
194 }
195 }
196 }
197 self
198 }
199 }
200
201 impl fmt::Display for Line {
202 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
203 write!(f, "{:?}", self)
204 }
205 }
206
207 /// A full set of available data about a tab on UG
208 ///
209 /// This struct is normally generated by [`crate::tab_scraper::get_song_data`].
210 #[derive(Debug, PartialEq, Default, Clone, Serialize, Deserialize)]
211 pub struct Song {
212 /// A vector of all lines in the tab
213 pub lines: Vec<Line>,
214 /// The detailed metadata of the song.
215 ///
216 /// This data is optional, because some types of tab (e.g. Drum) don't have any metadata.
217 pub metadata: Option<SongMetaData>,
218 /// Basic data about the tab
219 pub basic_data: BasicSongData,
220 }
221
222 impl fmt::Display for Song {
223 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
224 write!(f, "{:?}", self)
225 }
226 }
227
228 /// Basic metadata every tab has
229 ///
230 /// This struct is normally generated by [`crate::tab_scraper::get_basic_metadata`].
231 #[derive(Debug, PartialEq, Default, Clone, Serialize, Deserialize)]
232 pub struct BasicSongData {
233 /// Title of the song
234 pub title: String,
235 /// Name of the artist
236 pub artist: String,
237 /// Link to the tab
238 pub tab_link: String,
239 /// UG ID of the song
240 ///
241 /// Don't confuse this with the tab ID, which is only for a single tab!
242 pub song_id: u32,
243 /// UG ID of the tab
244 ///
245 /// Don't confuse this with the song ID, which is for every tab of the song!
246 pub tab_id: u32,
247 /// The type of tab
248 pub data_type: DataSetType,
249 }
250
251 impl fmt::Display for BasicSongData {
252 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
253 write!(f, "{:?}", self)
254 }
255 }
256
257 /// Special metadata which is not available for every tab (type)
258 ///
259 /// Tabs of the type `Drums` never have this. Bass tabs often don't have.
260 /// Many tabs are missing values of the metadata; thus, they are all options.
261 ///
262 /// This struct is normally automatically generated when using [`crate::tab_scraper::get_song_data`].
263 #[derive(Debug, PartialEq, Default, Clone, Serialize, Deserialize)]
264 pub struct SongMetaData {
265 pub capo: Option<String>,
266 pub tonality: Option<String>,
267 pub tuning_name: Option<String>,
268 pub tuning: Option<String>,
269 }
270
271 impl fmt::Display for SongMetaData {
272 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
273 write!(f, "{:?}", self)
274 }
275 }
276
277 /// Get the data type associated with a string scraped from UG
278 ///
279 /// ## Example:
280 /// ```
281 /// use ug_scraper::types::get_data_type;
282 ///
283 /// get_data_type("Chords");
284 /// // Returns:
285 /// // enum variant DataSetType::Chords
286 /// ```
287 ///
288 /// ## Supported strings:
289 /// * Chords
290 /// * Tabs
291 /// * Bass Tabs
292 /// * Ukulele Chords
293 /// * Drum Tabs
294 /// * Official
295 /// * Pro
296 /// * Power
297 /// * Video
298 ///
299 /// Returns `UGError::UnknownTypeError` if type is unknown.
300 pub fn get_data_type(type_string: &str) -> Result<DataSetType, UGError> {
301 match type_string {
302 "Chords" => Ok(DataSetType::Chords),
303 "Tabs" => Ok(DataSetType::Tab),
304 "Bass Tabs" => Ok(DataSetType::Bass),
305 "Ukulele Chords" => Ok(DataSetType::Ukulele),
306 "Drum Tabs" => Ok(DataSetType::Drums),
307 "Official" => Ok(DataSetType::Official),
308 "Pro" => Ok(DataSetType::Pro),
309 "Power" => Ok(DataSetType::Power),
310 "Video" => Ok(DataSetType::Video),
311 _ => Err(UGError::UnknownTypeError),
312 }
313 }
314
315 #[cfg(test)]
316 mod tests {
317 use crate::types::Line;
318
319 #[test]
320 fn german_names_replacement() {
321 let german_line: Line = Line {
322 line_type: super::DataType::Chord,
323 text_data: "A H C Dmoll Fis Es B B".to_string(),
324 };
325 let english_line: Line = Line {
326 line_type: super::DataType::Chord,
327 text_data: "A B C Dm F# Eb Bb Bb".to_string(),
328 };
329 assert_eq!(
330 german_line.replace_german_names().text_data,
331 english_line.text_data
332 );
333 }
334 }
335}