diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | .gitmodules | 3 | ||||
| -rw-r--r-- | Cargo.toml | 12 | ||||
| -rw-r--r-- | LICENSE-APACHE | 202 | ||||
| -rw-r--r-- | LICENSE-MIT | 19 | ||||
| m--------- | OpenGL-Refpages | 0 | ||||
| -rw-r--r-- | rustfmt.toml | 11 | ||||
| -rw-r--r-- | src/description.rs | 211 | ||||
| -rw-r--r-- | src/lib.rs | 158 | ||||
| -rw-r--r-- | src/util.rs | 34 | ||||
| -rw-r--r-- | src/xml/element.rs | 186 | ||||
| -rw-r--r-- | src/xml/mod.rs | 2 | ||||
| -rw-r--r-- | src/xml/parser.rs | 221 |
13 files changed, 1061 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4fffb2f --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/target +/Cargo.lock diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..f2ef3c8 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "OpenGL-Refpages"] + path = OpenGL-Refpages + url = https://github.com/KhronosGroup/OpenGL-Refpages diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..538a569 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "opengl-refpages" +version = "0.1.0" +edition = "2021" + +[dependencies] +include_dir = "0.7.3" +quick-xml = "0.27.1" +thiserror = "1.0.38" + +[dev-dependencies] +pretty_assertions = "1.3.0" diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..14ef2d6 --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,202 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2023 HampusM + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 0000000..170fea6 --- /dev/null +++ b/LICENSE-MIT @@ -0,0 +1,19 @@ +Copyright (c) 2023 HampusM + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/OpenGL-Refpages b/OpenGL-Refpages new file mode 160000 +Subproject bdf33f8dfeab700ffcae74435b7511bb10d97f2 diff --git a/rustfmt.toml b/rustfmt.toml new file mode 100644 index 0000000..4d1e29f --- /dev/null +++ b/rustfmt.toml @@ -0,0 +1,11 @@ +max_width = 90 +brace_style = "AlwaysNextLine" +group_imports = "StdExternalCrate" +wrap_comments = true +comment_width = 90 +format_code_in_doc_comments = true +imports_layout = "HorizontalVertical" +imports_granularity = "Module" +newline_style = "Unix" +reorder_impl_items = true + diff --git a/src/description.rs b/src/description.rs new file mode 100644 index 0000000..ba37abc --- /dev/null +++ b/src/description.rs @@ -0,0 +1,211 @@ +//! Reference entry description. +use crate::util::enum_with_get_inner; +use crate::xml::element::{Elements, FromElements, Tagged}; + +/// Reference entry description. +#[derive(Debug)] +pub struct Description +{ + paragraphs: Vec<Paragraph>, +} + +impl Description +{ + /// Returns a new `ReferenceDescription`. + #[must_use] + pub fn new() -> Self + { + Self { + paragraphs: Vec::new(), + } + } + + /// Returns the reference description's paragraphs. + #[must_use] + pub fn paragraphs(&self) -> &[Paragraph] + { + &self.paragraphs + } +} + +impl Default for Description +{ + fn default() -> Self + { + Self::new() + } +} + +impl FromElements for Description +{ + type Error = Error; + + fn from_elements(elements: &Elements) -> Result<Self, Self::Error> + { + let paragraphs = elements + .get_all_tagged_elements_with_name("para") + .into_iter() + .map(|paragraph_element| { + Paragraph::from_elements(paragraph_element.child_elements()) + }) + .collect::<Result<Vec<_>, _>>()?; + + Ok(Description { paragraphs }) + } +} + +/// [`Description`] error. +#[derive(Debug, thiserror::Error)] +pub enum Error +{ + /// Invalid paragraph. + #[error("Invalid paragraph")] + InvalidParagraph(#[from] ParagraphError), +} + +/// Reference entry description paragraph. +#[derive(Debug)] +pub struct Paragraph +{ + parts: Vec<ParagraphPart>, +} + +impl Paragraph +{ + /// Returns the parts of the paragraph. + #[must_use] + pub fn parts(&self) -> &[ParagraphPart] + { + &self.parts + } +} + +impl FromElements for Paragraph +{ + type Error = ParagraphError; + + fn from_elements(elements: &Elements) -> Result<Self, Self::Error> + { + let parts = elements + .into_iter() + .map(|element| { + ParagraphPart::from_elements(&Elements::from([element.clone()])) + }) + .collect::<Result<Vec<_>, _>>()?; + + Ok(Self { parts }) + } +} + +/// [`Paragraph`] error. +#[derive(Debug, thiserror::Error)] +pub enum ParagraphError +{ + /// Invalid reference description part. + #[error("Invalid part")] + InvalidPart(#[from] ParagraphPartError), +} + +enum_with_get_inner! { +inner = String; + +/// Reference entry description paragraph part. +#[derive(Debug)] +pub enum ParagraphPart +{ + /// Text part. + Text(String), + + /// <constant>..</constant> part. + Constant(String), + + /// <function>..</function> part. + Function(String), + + /// <parameter>..</parameter> part. + Parameter(String), + + /// Reference entry citation part. + Entry(String), +} +} + +impl FromElements for ParagraphPart +{ + type Error = ParagraphPartError; + + fn from_elements(elements: &Elements) -> Result<Self, Self::Error> + { + if let Some(tagged_element) = elements.get_first_tagged() { + return Self::from_tagged_element(tagged_element); + } + + let text = elements + .get_first_text_element() + .ok_or(Self::Error::InputIsComment)?; + + Ok(Self::Text(text.clone())) + } +} + +impl ParagraphPart +{ + fn from_tagged_element( + tagged_element: &Tagged, + ) -> Result<Self, <Self as FromElements>::Error> + { + let create: fn(String) -> Self = match tagged_element.name() { + "constant" => Self::Constant, + "function" => Self::Function, + "parameter" => Self::Parameter, + "citerefentry" => Self::Entry, + _ => { + return Err(<Self as FromElements>::Error::UnknownPart( + tagged_element.name().to_string(), + )); + } + }; + + if tagged_element.name() == "citerefentry" { + let title_element = tagged_element + .child_elements() + .get_first_tagged_with_name("refentrytitle") + .ok_or(<Self as FromElements>::Error::NoEntryTitleFound)?; + + let title = title_element + .child_elements() + .get_first_text_element() + .ok_or(<Self as FromElements>::Error::NoTextInTagged)?; + + return Ok(Self::Entry(title.clone())); + } + + let text_element = tagged_element + .child_elements() + .get_first_text_element() + .ok_or(<Self as FromElements>::Error::NoTextInTagged)?; + + Ok(create(text_element.clone())) + } +} + +/// [`ParagraphPart`] error. +#[derive(Debug, thiserror::Error)] +pub enum ParagraphPartError +{ + /// Input element is a comment. + #[error("Input element is a comment")] + InputIsComment, + + /// A input element is a unknown reference description part. + #[error("Input element with name '{0}' is a unknown reference description part")] + UnknownPart(String), + + /// No text was found in tagged input element. + #[error("No text was found in tagged input element")] + NoTextInTagged, + + /// No entry title found. + #[error("No entry title found")] + NoEntryTitleFound, +} diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..8e9e1e7 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,158 @@ +//! Rust API for the [OpenGL reference page sources]. +//! +//! [OpenGL reference page sources]: https://github.com/KhronosGroup/OpenGL-Refpages +#![cfg_attr(doc_cfg, feature(doc_cfg))] +#![deny(clippy::all, clippy::pedantic, missing_docs)] + +use std::os::unix::prelude::OsStrExt; + +use include_dir::{include_dir, Dir}; + +use crate::description::{Description, Error as DescriptionError}; +use crate::xml::element::{Attribute, Elements, FromElements}; +use crate::xml::parser::{Error as ParserError, Parser}; + +pub mod description; + +mod util; +mod xml; + +static GL4_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/OpenGL-Refpages/gl4"); + +/// Reference entry. +#[derive(Debug)] +pub struct ReferenceEntry +{ + purpose: String, + description: Description, +} + +impl ReferenceEntry +{ + /// Returns a function reference entry. + /// + /// # Errors + /// Returns `Err` if + /// - No reference entry file was found. + /// - Parsing the reference entry file data fails. + /// - The reference entry file data is invalid. + pub fn get_function(function_name: &str) -> Result<Self, ReferenceEntryError> + { + let function_file = GL4_DIR + .files() + .find_map(|file| { + if file.path().extension()?.as_bytes() != b"xml" { + return None; + } + + if function_name.starts_with(file.path().file_stem()?.to_str()?) { + Some(file) + } else { + None + } + }) + .ok_or_else(|| ReferenceEntryError::NoFileFound(function_name.to_string()))?; + + let function_ref_content = function_file.contents(); + + let mut parser = Parser::new(function_ref_content); + + let root_elements = parser.parse()?; + + ReferenceEntry::from_elements(&root_elements) + } + + /// Returns the reference entry purpose. + #[must_use] + pub fn purpose(&self) -> &str + { + &self.purpose + } + + /// Returns the reference entry description. + #[must_use] + pub fn description(&self) -> &Description + { + &self.description + } +} + +impl FromElements for ReferenceEntry +{ + type Error = ReferenceEntryError; + + fn from_elements(elements: &Elements) -> Result<Self, Self::Error> + { + let refentry_element = elements + .get_first_tagged_with_name("refentry") + .ok_or(ReferenceEntryError::MissingRefEntry)?; + + let refnamediv_element = refentry_element + .child_elements() + .get_first_tagged_with_name("refnamediv") + .ok_or(ReferenceEntryError::MissingRefNameDiv)?; + + let refpurpose_element = refnamediv_element + .child_elements() + .get_first_tagged_with_name("refpurpose") + .ok_or(ReferenceEntryError::MissingRefPurpose)?; + + let purpose = refpurpose_element + .child_elements() + .get_first_text_element() + .cloned() + .unwrap_or_default(); + + let description_refsect = refentry_element + .child_elements() + .get_first_tagged_with_name_and_attr( + "refsect1", + &Attribute { + key: "xml:id".to_string(), + value: b"description".to_vec(), + }, + ) + .ok_or(ReferenceEntryError::MissingDescriptionRefSect)?; + + let description = + Description::from_elements(description_refsect.child_elements())?; + + Ok(ReferenceEntry { + purpose, + description, + }) + } +} + +/// [`ReferenceEntry`] error. +#[derive(Debug, thiserror::Error)] +pub enum ReferenceEntryError +{ + /// No reference entry file was found. + #[error("No reference entry file was found for '{0}'")] + NoFileFound(String), + + /// No 'refentry' element was found. + #[error("No 'refentry' element was found")] + MissingRefEntry, + + /// No 'refnamediv' element was found. + #[error("No 'refnamediv' element was found")] + MissingRefNameDiv, + + /// No 'refpurpose' element was found. + #[error("No 'refpurpose' element was found")] + MissingRefPurpose, + + /// No 'refsect1' element was found with id 'description''. + #[error("No 'refsect1' element was found with id 'description'")] + MissingDescriptionRefSect, + + /// Invalid description. + #[error("Invalid description")] + InvalidDescription(#[from] DescriptionError), + + /// Parsing failed. + #[error("Parsing failed")] + ParsingFailed(#[from] ParserError), +} diff --git a/src/util.rs b/src/util.rs new file mode 100644 index 0000000..309a471 --- /dev/null +++ b/src/util.rs @@ -0,0 +1,34 @@ +macro_rules! enum_with_get_inner { + ( + inner = $inner: ty; + $(#[$attr: meta])* + $visibility: vis enum $enum_name: ident { + $( + $(#[$variant_attr: meta])* + $variant: ident($variant_inner: ty), + )* + } + ) => { + $(#[$attr])* + $visibility enum $enum_name { + $( + $(#[$variant_attr])* + $variant($inner) + ),* + } + + impl $enum_name { + /// Returns the inner value. + #[must_use] + pub fn inner(&self) -> &$inner { + match self { + $( + $enum_name::$variant(inner) => inner + ),* + } + } + } + }; +} + +pub(crate) use enum_with_get_inner; diff --git a/src/xml/element.rs b/src/xml/element.rs new file mode 100644 index 0000000..647fe90 --- /dev/null +++ b/src/xml/element.rs @@ -0,0 +1,186 @@ +#[derive(Debug, PartialEq, Eq, Clone)] +pub struct Elements +{ + elements: Vec<Element>, +} + +impl Elements +{ + pub fn get_first_tagged(&self) -> Option<&Tagged> + { + self.elements.iter().find_map(|element| match element { + Element::Tagged(tagged_element) => Some(tagged_element), + _ => None, + }) + } + + pub fn get_first_tagged_with_name(&self, tag_name: &str) -> Option<&Tagged> + { + self.elements.iter().find_map(|element| match element { + Element::Tagged(tagged_element) if tagged_element.name == tag_name => { + Some(tagged_element) + } + _ => None, + }) + } + + pub fn get_first_tagged_with_name_and_attr( + &self, + tag_name: &str, + attribute: &Attribute, + ) -> Option<&Tagged> + { + self.elements.iter().find_map(|element| match element { + Element::Tagged(tagged_element) + if tagged_element.name == tag_name + && tagged_element + .attributes + .iter() + .any(|attr| attr == attribute) => + { + Some(tagged_element) + } + _ => None, + }) + } + + pub fn get_all_tagged_elements_with_name(&self, tag_name: &str) -> Vec<&Tagged> + { + self.elements + .iter() + .filter_map(|element| match element { + Element::Tagged(tagged_element) if tagged_element.name == tag_name => { + Some(tagged_element) + } + _ => None, + }) + .collect() + } + + pub fn get_first_text_element(&self) -> Option<&String> + { + self.elements.iter().find_map(|element| match element { + Element::Text(text) => Some(text), + _ => None, + }) + } + + pub fn get_all_text_elements(&self) -> Vec<&String> + { + self.elements + .iter() + .filter_map(|element| match element { + Element::Text(text) => Some(text), + _ => None, + }) + .collect() + } + + pub fn has_tagged_element(&self, tag_name: &str) -> bool + { + self.elements.iter().any(|element| { + matches!( + element, + Element::Tagged(tagged_element) if tagged_element.name == tag_name + ) + }) + } +} + +impl<IntoIter: IntoIterator<Item = Element>> From<IntoIter> for Elements +{ + fn from(into_iter: IntoIter) -> Self + { + Self { + elements: into_iter.into_iter().collect(), + } + } +} + +impl<'elements> IntoIterator for &'elements Elements +{ + type IntoIter = Iter<'elements>; + type Item = &'elements Element; + + fn into_iter(self) -> Self::IntoIter + { + Self::IntoIter { + elements: self.elements.iter(), + } + } +} + +pub struct Iter<'elements> +{ + elements: std::slice::Iter<'elements, Element>, +} + +impl<'elements> Iterator for Iter<'elements> +{ + type Item = &'elements Element; + + fn next(&mut self) -> Option<Self::Item> + { + self.elements.next() + } +} + +#[derive(Debug, PartialEq, Eq, Clone)] +pub enum Element +{ + Tagged(Tagged), + Text(String), + Comment(String), +} + +#[derive(Debug, PartialEq, Eq, Clone)] +pub struct Tagged +{ + name: String, + child_elements: Elements, + attributes: Vec<Attribute>, +} + +impl Tagged +{ + pub fn new<Name, ChildElements, Attrs>( + name: &Name, + child_elements: ChildElements, + attributes: Attrs, + ) -> Self + where + Name: ToString, + ChildElements: Into<Elements>, + Attrs: IntoIterator<Item = Attribute>, + { + Self { + name: name.to_string(), + child_elements: child_elements.into(), + attributes: attributes.into_iter().collect(), + } + } + + pub fn name(&self) -> &str + { + &self.name + } + + pub fn child_elements(&self) -> &Elements + { + &self.child_elements + } +} + +#[derive(Debug, PartialEq, Eq, Clone)] +pub struct Attribute +{ + pub key: String, + pub value: Vec<u8>, +} + +pub trait FromElements: Sized +{ + type Error; + + fn from_elements(elements: &Elements) -> Result<Self, Self::Error>; +} diff --git a/src/xml/mod.rs b/src/xml/mod.rs new file mode 100644 index 0000000..12368c3 --- /dev/null +++ b/src/xml/mod.rs @@ -0,0 +1,2 @@ +pub mod element; +pub mod parser; diff --git a/src/xml/parser.rs b/src/xml/parser.rs new file mode 100644 index 0000000..9cdafb1 --- /dev/null +++ b/src/xml/parser.rs @@ -0,0 +1,221 @@ +use std::io::BufRead; + +use quick_xml::events::attributes::AttrError; +use quick_xml::events::{BytesStart, BytesText, Event}; +use quick_xml::Reader; + +use crate::xml::element::{Attribute, Element, Elements, Tagged}; + +/// XML parser. +pub struct Parser<Source> +{ + reader: Reader<Source>, +} + +impl<Source: BufRead> Parser<Source> +{ + pub fn new(src: Source) -> Self + { + Self { + reader: Reader::from_reader(src), + } + } + + pub fn parse(&mut self) -> Result<Elements, Error> + { + let mut buf = Vec::new(); + + let mut elements = Vec::new(); + + loop { + let event = self.reader.read_event_into(&mut buf)?; + + let element = match self.handle_event(event)? { + EventHandlingResult::Element(element) => element, + EventHandlingResult::Event(_) => { + continue; + } + EventHandlingResult::End => { + break; + } + }; + + elements.push(element); + } + + Ok(elements.into()) + } + + fn parse_text(text: &BytesText) -> Result<String, Error> + { + String::from_utf8(text.to_vec()).map_err(|_| Error::TextNotUTF8) + } + + fn parse_tagged(&mut self, start: &BytesStart) -> Result<Element, Error> + { + let mut child_elements = Vec::new(); + + let mut buf = Vec::new(); + + loop { + let event = self.reader.read_event_into(&mut buf)?; + + match event { + Event::End(end) if end.name() == start.name() => { + break; + } + event => match self.handle_event(event)? { + EventHandlingResult::Element(element) => { + child_elements.push(element); + } + EventHandlingResult::End => { + return Err(Error::UnexpectedEndOfFile); + } + EventHandlingResult::Event(_) => {} + }, + } + } + + let attributes = start + .attributes() + .map(|attr_result| { + let attr = attr_result?; + + Ok(Attribute { + key: String::from_utf8(attr.key.as_ref().to_vec()) + .map_err(|_| Error::TagAttributeKeyNotUTF8)?, + value: attr.value.into_owned(), + }) + }) + .collect::<Result<Vec<_>, Error>>()?; + + Ok(Element::Tagged(Tagged::new( + &String::from_utf8(start.name().as_ref().to_vec()) + .map_err(|_| Error::TagNameNotUTF8)?, + child_elements, + attributes, + ))) + } + + fn handle_event<'a>( + &'a mut self, + event: Event<'a>, + ) -> Result<EventHandlingResult, Error> + { + match event { + Event::Text(text) => Ok(EventHandlingResult::Element(Element::Text( + Self::parse_text(&text)?, + ))), + Event::Start(start) => { + Ok(EventHandlingResult::Element(self.parse_tagged(&start)?)) + } + Event::End(_) => Err(Error::UnexpectedTagEnd), + Event::Eof => Ok(EventHandlingResult::End), + Event::Comment(comment_text) => Ok(EventHandlingResult::Element( + Element::Comment(Self::parse_text(&comment_text)?), + )), + event => Ok(EventHandlingResult::Event(event)), + } + } +} + +#[derive(Debug, thiserror::Error)] +pub enum Error +{ + #[error(transparent)] + QuickXMLFailed(#[from] quick_xml::Error), + + #[error("Text is not UTF-8")] + TextNotUTF8, + + #[error("Tag name is not UTF-8")] + TagNameNotUTF8, + + #[error("Invalid attribute")] + InvalidTagAttr(#[from] AttrError), + + #[error("Tag attribute key is not UTF-8")] + TagAttributeKeyNotUTF8, + + #[error("Unexpectedly found the end of a tag")] + UnexpectedTagEnd, + + #[error("Unexpected end of file")] + UnexpectedEndOfFile, +} + +enum EventHandlingResult<'event> +{ + Element(Element), + Event(Event<'event>), + End, +} + +#[cfg(test)] +mod tests +{ + use pretty_assertions::assert_eq; + + use super::*; + + #[test] + fn can_parse() + { + let mut parser = Parser::new("<foo>Hello there</foo>".as_bytes()); + + assert_eq!( + parser.parse().expect("Expected Ok"), + Elements::from(vec![Element::Tagged(Tagged::new( + &"foo", + vec![Element::Text("Hello there".to_string())], + Vec::new() + ))]) + ); + + let mut parser = Parser::new("<foo><bar>123</bar> Hello</foo>".as_bytes()); + + assert_eq!( + parser.parse().expect("Expected Ok"), + Elements::from(vec![Element::Tagged(Tagged::new( + &"foo", + vec![ + Element::Tagged(Tagged::new( + &"bar", + Elements::from(vec![Element::Text("123".to_string())]), + Vec::new() + )), + Element::Text(" Hello".to_string()) + ], + Vec::new() + ))]) + ); + + let mut parser = Parser::new("".as_bytes()); + + assert_eq!( + parser.parse().expect("Expected Ok"), + Elements::from(Vec::new()) + ); + + let mut parser = Parser::new( + "<foo><!--XML is awful-->Hello there<bar>123</bar></foo>".as_bytes(), + ); + + assert_eq!( + parser.parse().expect("Expected Ok"), + Elements::from(vec![Element::Tagged(Tagged::new( + &"foo", + vec![ + Element::Comment("XML is awful".to_string()), + Element::Text("Hello there".to_string()), + Element::Tagged(Tagged::new( + &"bar", + vec![Element::Text("123".to_string())], + Vec::new() + )), + ], + Vec::new() + ))]) + ); + } +} |