use crate::error::{Result, XbrlError};
use crate::instance::{Instance, RawFact, XbrlValue};
use crate::transformations;
use quick_xml::{
Reader, Writer,
de::from_str,
events::{BytesRef, BytesStart, Event},
};
use std::borrow::Cow;
use std::collections::HashMap;
fn is_xbrl_root_element(tag_name: &str) -> bool {
tag_name == "xbrl" || tag_name.ends_with(":xbrl")
}
pub fn is_xml_instance(content: &str) -> bool {
let mut rest = content;
loop {
let Some(open) = rest.find('<') else {
return false;
};
rest = &rest[open + 1..];
if let Some(comment) = rest.strip_prefix("!--") {
rest = comment.find("-->").map_or("", |end| &comment[end + 3..]);
} else if !rest.starts_with(['?', '!']) {
break;
}
}
let name_end = rest
.find(|c: char| c.is_whitespace() || c == '>' || c == '/')
.unwrap_or(rest.len());
local_part(&rest[..name_end]).eq_ignore_ascii_case("xbrl")
}
fn local_part(tag_name: &str) -> &str {
match tag_name.rfind(':') {
Some(idx) => &tag_name[idx + 1..],
None => tag_name,
}
}
fn has_id_attribute(e: &BytesStart) -> bool {
e.attributes()
.flatten()
.any(|attr| attr.key.as_ref().eq_ignore_ascii_case("id"))
}
pub fn parse_xml(xml_content: &str) -> Result<Instance> {
let mut reader = Reader::from_str(xml_content);
reader.config_mut().trim_text(true);
reader.config_mut().expand_empty_elements = false;
let mut buf = Vec::new();
let mut xbrl = Instance::default();
loop {
match reader
.read_event_into(&mut buf)
.map_err(XbrlError::malformed)?
{
Event::Start(e) => {
let tag_name = e.name().as_ref().to_string();
if is_xbrl_root_element(&tag_name) {
process_events(&mut reader, &mut xbrl, false, |event| {
if let Event::End(end_event) = event {
let end_tag_name = end_event.name().as_ref().to_string();
return is_xbrl_root_element(&end_tag_name);
}
false
})?;
return Ok(xbrl); }
}
Event::Eof => {
return Err(XbrlError::NotXbrl(
"no <xbrl> root element in the document".to_string(),
));
}
_ => {
}
}
buf.clear();
}
}
pub fn parse_ixbrl(html_content: &str) -> Result<Instance> {
let mut reader = Reader::from_str(html_content);
reader.config_mut().trim_text(true);
reader.config_mut().expand_empty_elements = true;
reader.config_mut().check_end_names = false;
reader.config_mut().allow_unmatched_ends = true;
let mut xbrl = Instance::default();
process_events(&mut reader, &mut xbrl, true, |event| {
matches!(event, Event::Eof)
})?;
Ok(xbrl)
}
#[derive(Debug, Default)]
struct FactAttrs {
is_nil: bool,
scale: Option<i32>,
negative: bool,
continued_at: Option<String>,
escape: bool,
}
#[derive(Default)]
struct InlineState {
pending: Vec<(usize, FactAttrs, String)>,
continuations: HashMap<String, (String, Option<String>)>,
}
fn is_inline_fact_tag(lowercase_tag: &str) -> bool {
matches!(
lowercase_tag,
"ix:nonfraction" | "ix:fraction" | "ix:nonnumeric"
)
}
fn is_block_tag(lowercase_tag: &str) -> bool {
matches!(
lowercase_tag,
"p" | "div"
| "br"
| "tr"
| "td"
| "th"
| "li"
| "ul"
| "ol"
| "table"
| "h1"
| "h2"
| "h3"
| "h4"
| "h5"
| "h6"
| "hr"
| "blockquote"
)
}
fn resolve_entity(entity: &str) -> Option<&'static str> {
if let Some(predefined) = quick_xml::escape::resolve_predefined_entity(entity) {
return Some(predefined);
}
Some(match entity {
"nbsp" | "ensp" | "emsp" | "thinsp" => " ",
"ndash" => "–",
"mdash" => "—",
"lsquo" => "‘",
"rsquo" => "’",
"sbquo" => "‚",
"ldquo" => "“",
"rdquo" => "”",
"bdquo" => "„",
"laquo" => "«",
"raquo" => "»",
"hellip" => "…",
"bull" => "•",
"middot" => "·",
"sect" => "§",
"para" => "¶",
"copy" => "©",
"reg" => "®",
"trade" => "™",
"deg" => "°",
"plusmn" => "±",
"times" => "×",
"divide" => "÷",
"cent" => "¢",
"pound" => "£",
"euro" => "€",
"yen" => "¥",
"frac12" => "½",
"frac14" => "¼",
"frac34" => "¾",
"dagger" => "†",
"Dagger" => "‡",
"shy" | "zwnj" | "zwj" => "",
_ => return None,
})
}
fn decode_reference(reference: &BytesRef) -> Cow<'static, str> {
if let Ok(Some(c)) = reference.resolve_char_ref() {
return Cow::Owned(c.to_string());
}
match resolve_entity(reference) {
Some(resolved) => Cow::Borrowed(resolved),
None => Cow::Owned(format!("&{};", &**reference)),
}
}
fn attribute(e: &BytesStart, lowercase_name: &str) -> Option<String> {
e.attributes().flatten().find_map(|attr| {
attr.key
.as_ref()
.eq_ignore_ascii_case(lowercase_name)
.then(|| attr.value.clone().into_owned())
})
}
fn read_inline_fact(
e: &BytesStart,
lowercase_tag: &str,
reader: &mut Reader<&[u8]>,
xbrl: &mut Instance,
inline: &mut InlineState,
) -> Result<usize> {
let (mut fact, attrs) = parse_fact_attributes_common(e, true);
fact.local_name = local_part(&fact.full_name).to_string();
let text = read_inline_content(reader, lowercase_tag, xbrl, inline)?;
inline.pending.push((xbrl.facts.len(), attrs, text));
xbrl.facts.push(fact);
Ok(inline.pending.len() - 1)
}
fn read_inline_content(
reader: &mut Reader<&[u8]>,
lowercase_end_tag: &str,
xbrl: &mut Instance,
inline: &mut InlineState,
) -> Result<String> {
let mut text = String::new();
let mut buf = Vec::new();
let mut same_name_depth = 0usize;
loop {
buf.clear();
match reader
.read_event_into(&mut buf)
.map_err(XbrlError::malformed)?
{
Event::Text(chunk) => text.push_str(&chunk),
Event::GeneralRef(reference) => text.push_str(&decode_reference(&reference)),
Event::CData(chunk) => text.push_str(&chunk),
Event::Start(child) => {
let tag = child.name().as_ref().to_lowercase();
if is_inline_fact_tag(&tag) {
let nested = read_inline_fact(&child, &tag, reader, xbrl, inline)?;
text.push_str(&inline.pending[nested].2);
} else if tag == "ix:exclude" {
read_inline_content(reader, &tag, xbrl, inline)?;
} else if tag == "ix:continuation" {
read_continuation(&child, reader, xbrl, inline)?;
} else {
if tag == lowercase_end_tag {
same_name_depth += 1;
}
if is_block_tag(&tag) {
text.push('\n');
}
}
}
Event::End(end) => {
let tag = end.name().as_ref().to_lowercase();
if tag == lowercase_end_tag {
if same_name_depth == 0 {
break;
}
same_name_depth -= 1;
} else if is_block_tag(&tag) {
text.push('\n');
}
}
Event::Eof => break,
_ => { }
}
}
Ok(text)
}
fn read_continuation(
e: &BytesStart,
reader: &mut Reader<&[u8]>,
xbrl: &mut Instance,
inline: &mut InlineState,
) -> Result<()> {
let id = attribute(e, "id");
let continued_at = attribute(e, "continuedat");
let text = read_inline_content(reader, "ix:continuation", xbrl, inline)?;
if let Some(id) = id {
inline.continuations.insert(id, (text, continued_at));
}
Ok(())
}
fn settle_inline_facts(xbrl: &mut Instance, inline: InlineState) {
const MAX_CONTINUATIONS: usize = 4096;
let InlineState {
pending,
continuations,
} = inline;
for (index, attrs, mut text) in pending {
if attrs.is_nil {
continue;
}
let mut next = attrs.continued_at.as_deref();
for _ in 0..MAX_CONTINUATIONS {
let Some((more, then)) = next.and_then(|id| continuations.get(id)) else {
break;
};
text.push('\n');
text.push_str(more);
next = then.as_deref();
}
let fact = &mut xbrl.facts[index];
fact.value = inline_value(&text, fact.format.as_deref(), &attrs);
}
}
fn inline_value(raw: &str, format: Option<&str>, attrs: &FactAttrs) -> XbrlValue {
let text = if attrs.escape {
normalize_lines(raw)
} else {
collapse_whitespace(raw)
};
let transformed = match format {
Some(format) => {
let single_line = collapse_whitespace(&text);
transformations::apply_transformation(&single_line, format).unwrap_or(text)
}
None => text,
};
let scaled = match attrs.scale {
Some(scale) => shift_decimal(&transformed, scale).unwrap_or(transformed),
None => transformed,
};
let value = if attrs.negative {
negate(scaled)
} else {
scaled
};
if value.trim().is_empty() {
XbrlValue::Nil
} else {
XbrlValue::String(value)
}
}
fn collapse_whitespace(text: &str) -> String {
text.split_whitespace().collect::<Vec<_>>().join(" ")
}
fn normalize_lines(text: &str) -> String {
text.lines()
.map(collapse_whitespace)
.filter(|line| !line.is_empty())
.collect::<Vec<_>>()
.join("\n")
}
fn shift_decimal(value: &str, scale: i32) -> Option<String> {
let value = value.trim();
let (negative, unsigned) = match value.strip_prefix('-') {
Some(rest) => (true, rest),
None => (false, value),
};
let (int, frac) = unsigned.split_once('.').unwrap_or((unsigned, ""));
if int.is_empty() && frac.is_empty() {
return None;
}
if !int.bytes().chain(frac.bytes()).all(|b| b.is_ascii_digit()) {
return None;
}
let mut digits = format!("{int}{frac}");
let mut point = int.len() as i64 + i64::from(scale);
if point <= 0 {
digits.insert_str(0, &"0".repeat((1 - point) as usize));
point = 1;
}
let point = point as usize;
if point > digits.len() {
digits.push_str(&"0".repeat(point - digits.len()));
}
let (int, frac) = digits.split_at(point);
let int = int.trim_start_matches('0');
let int = if int.is_empty() { "0" } else { int };
let frac = frac.trim_end_matches('0');
let mut shifted = String::with_capacity(digits.len() + 2);
if negative && (int != "0" || !frac.is_empty()) {
shifted.push('-');
}
shifted.push_str(int);
if !frac.is_empty() {
shifted.push('.');
shifted.push_str(frac);
}
Some(shifted)
}
fn negate(value: String) -> String {
if let Some(positive) = value.strip_prefix('-') {
return positive.to_string();
}
let is_zero = value.parse::<f64>().is_ok_and(|number| number == 0.0);
if is_zero { value } else { format!("-{value}") }
}
fn process_events<F>(
reader: &mut Reader<&[u8]>,
xbrl: &mut Instance,
inline_document: bool,
mut should_break: F,
) -> Result<()>
where
F: FnMut(&Event) -> bool,
{
let mut buf = Vec::new();
let mut inline = InlineState::default();
loop {
buf.clear();
let event = reader
.read_event_into(&mut buf)
.map_err(XbrlError::malformed)?;
if should_break(&event) {
break;
}
match event {
Event::Start(e) => {
let tag_name = e.name().as_ref().to_string();
let lowercase_tag = tag_name.to_lowercase();
if try_handle_metadata_or_link(reader, xbrl, &e, &tag_name)? {
continue;
}
let is_continuation = lowercase_tag == "ix:continuation";
if is_continuation || is_inline_fact_tag(&lowercase_tag) {
reader.config_mut().trim_text(false);
let read = if is_continuation {
read_continuation(&e, reader, xbrl, &mut inline)
} else {
read_inline_fact(&e, &lowercase_tag, reader, xbrl, &mut inline).map(|_| ())
};
reader.config_mut().trim_text(true);
read?;
continue;
}
let lc_tag = lowercase_tag.as_str();
if tag_name.contains(':')
&& !lc_tag.starts_with("ix:")
&& !lc_tag.starts_with("link:")
&& !lc_tag.starts_with("html")
&& (!inline_document || attribute(&e, "contextref").is_some())
{
handle_start_event(reader, xbrl, e, tag_name)?;
}
}
Event::Empty(e) => {
let tag_name = e.name().as_ref().to_string();
handle_empty_event(xbrl, e, tag_name);
}
Event::Eof => break,
_ => { }
}
}
settle_inline_facts(xbrl, inline);
Ok(())
}
fn handle_start_event(
reader: &mut Reader<&[u8]>,
xbrl: &mut Instance,
e: BytesStart,
tag_name: String,
) -> Result<()> {
let (mut fact, attrs) = parse_fact_attributes_common(&e, false);
let is_explicitly_nil = attrs.is_nil;
fact.local_name = local_part(&tag_name).to_string();
fact.full_name = tag_name;
if is_explicitly_nil {
fact.value = XbrlValue::Nil;
reader
.read_to_end_into(e.name(), &mut Vec::new())
.map_err(XbrlError::malformed)?;
} else {
reader.config_mut().trim_text(false);
let content = read_instance_text(reader, &e);
reader.config_mut().trim_text(true);
fact.value = match content? {
Some(text) => parse_typed_value(text.trim()),
None => XbrlValue::Nil,
};
}
xbrl.facts.push(fact);
Ok(())
}
fn read_instance_text(reader: &mut Reader<&[u8]>, e: &BytesStart) -> Result<Option<String>> {
let mut text = String::new();
let mut buf = Vec::new();
loop {
buf.clear();
match reader
.read_event_into(&mut buf)
.map_err(XbrlError::malformed)?
{
Event::Text(chunk) => text.push_str(&chunk),
Event::CData(chunk) => text.push_str(&chunk),
Event::GeneralRef(reference) => text.push_str(&decode_reference(&reference)),
Event::End(_) => return Ok(Some(text)),
Event::Start(_) | Event::Empty(_) | Event::Eof => {
reader
.read_to_end_into(e.name(), &mut Vec::new())
.map_err(XbrlError::malformed)?;
return Ok(None);
}
_ => {}
}
}
}
fn handle_empty_event(xbrl: &mut Instance, e: BytesStart, tag_name: String) {
if tag_name.starts_with("link:") {
return;
}
let (mut fact, _) = parse_fact_attributes_common(&e, false);
fact.local_name = local_part(&tag_name).to_string();
fact.full_name = tag_name;
fact.value = XbrlValue::Nil;
xbrl.facts.push(fact);
}
fn parse_typed_value(value_str: &str) -> XbrlValue {
let trimmed_val = value_str.trim();
if trimmed_val.is_empty() {
XbrlValue::Nil
} else {
XbrlValue::String(trimmed_val.to_string())
}
}
fn reconstruct_element(
reader: &mut Reader<&[u8]>,
start_event: &BytesStart,
tag_name: &str,
) -> Result<String> {
let mut writer = Writer::new(Vec::new());
writer
.write_event(Event::Start(start_event.clone()))
.map_err(XbrlError::malformed)?;
let mut depth = 0;
let mut buf = Vec::new();
loop {
buf.clear();
let event = reader
.read_event_into(&mut buf)
.map_err(XbrlError::malformed)?;
match &event {
Event::End(e) if e.name().as_ref() == tag_name && depth == 0 => {
writer.write_event(event).map_err(XbrlError::malformed)?;
break;
}
Event::Start(_) => {
depth += 1;
}
Event::End(_) => {
depth -= 1;
}
Event::Eof => {
return Err(XbrlError::malformed(format!(
"the document ends inside <{tag_name}>"
)));
}
_ => {
}
}
writer.write_event(event).map_err(XbrlError::malformed)?;
}
let xml_bytes = writer.into_inner();
String::from_utf8(xml_bytes).map_err(XbrlError::malformed)
}
fn try_handle_metadata_or_link(
reader: &mut Reader<&[u8]>,
xbrl: &mut Instance,
e: &BytesStart,
tag_name: &str,
) -> Result<bool> {
let lowercase_tag = tag_name.to_lowercase();
let local_tag = local_part(&lowercase_tag);
if local_tag == "context" && has_id_attribute(e) {
let element_xml = reconstruct_element(reader, e, tag_name)?;
if let Ok(context) = from_str(&element_xml) {
xbrl.contexts.push(context);
}
Ok(true)
} else if local_tag == "unit" && has_id_attribute(e) {
let element_xml = reconstruct_element(reader, e, tag_name)?;
if let Ok(unit) = from_str(&element_xml) {
xbrl.units.push(unit);
}
Ok(true)
} else if lowercase_tag.starts_with("link:") {
reader
.read_to_end_into(e.name(), &mut Vec::new())
.map_err(XbrlError::malformed)?;
Ok(true)
} else {
Ok(false)
}
}
fn parse_fact_attributes_common(e: &BytesStart, is_ixbrl: bool) -> (RawFact, FactAttrs) {
let mut fact = RawFact::default();
let mut attrs = FactAttrs::default();
for attr in e.attributes().flatten() {
let key = attr.key.as_ref().to_lowercase();
let value_str = attr.value.clone();
match key.as_str() {
"contextref" => fact.context_ref = Some(value_str.into_owned()),
"unitref" => fact.unit_ref = Some(value_str.into_owned()),
"decimals" => fact.decimals = Some(value_str.into_owned()),
"id" => fact.id = Some(value_str.into_owned()),
"format" if is_ixbrl => fact.format = Some(value_str.into_owned()),
"name" if is_ixbrl => fact.full_name = value_str.into_owned(),
"scale" if is_ixbrl => attrs.scale = value_str.trim().parse::<i32>().ok(),
"sign" if is_ixbrl => attrs.negative = value_str.trim() == "-",
"continuedat" if is_ixbrl => attrs.continued_at = Some(value_str.into_owned()),
"escape" if is_ixbrl => attrs.escape = value_str.trim().eq_ignore_ascii_case("true"),
"xsi:nil" | "nil" if value_str.eq_ignore_ascii_case("true") => {
fact.value = XbrlValue::Nil;
attrs.is_nil = true;
}
_ => {
}
}
}
(fact, attrs)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_is_xbrl_root_element() {
assert!(is_xbrl_root_element("xbrl"));
assert!(is_xbrl_root_element("xbrli:xbrl"));
assert!(is_xbrl_root_element("xbrl:xbrl"));
assert!(is_xbrl_root_element("ns:xbrl"));
assert!(!is_xbrl_root_element("context"));
assert!(!is_xbrl_root_element("unit"));
assert!(!is_xbrl_root_element("xbrl:context"));
}
#[test]
fn the_root_element_tells_an_instance_from_an_inline_document() {
assert!(is_xml_instance(
"<xbrl xmlns=\"http://www.xbrl.org/2003/instance\">"
));
assert!(is_xml_instance(
"<?xml version=\"1.0\"?>\n<!-- <html> in a comment -->\n<xbrli:xbrl>"
));
assert!(!is_xml_instance(
"<?xml version=\"1.0\"?><!DOCTYPE html><html xmlns:ix=\"http://www.xbrl.org/2013/inlineXBRL\">"
));
assert!(!is_xml_instance("<HTML><body>"));
assert!(!is_xml_instance("no markup at all"));
assert!(!is_xml_instance(""));
}
#[test]
fn test_parse_typed_value() {
assert_eq!(
parse_typed_value("1500000"),
XbrlValue::String("1500000".to_string())
);
assert_eq!(
parse_typed_value("true"),
XbrlValue::String("true".to_string())
);
assert_eq!(
parse_typed_value(" See Note 1 "),
XbrlValue::String("See Note 1".to_string())
);
assert_eq!(parse_typed_value(""), XbrlValue::Nil);
assert_eq!(parse_typed_value(" "), XbrlValue::Nil);
}
#[test]
fn references_inside_an_instance_fact_are_resolved() {
let xml = r#"<?xml version="1.0"?>
<xbrl xmlns="http://www.xbrl.org/2003/instance" xmlns:dei="http://xbrl.sec.gov/dei/2024">
<dei:EntityRegistrantName> Smith & Sons Acquisition Corp </dei:EntityRegistrantName>
</xbrl>"#;
let instance = parse_xml(xml).unwrap();
let fact = &instance.facts[0];
assert_eq!(
fact.value,
XbrlValue::String("Smith & Sons\u{a0}Acquisition Corp".to_string())
);
}
#[test]
fn test_error_handling_malformed_xml() {
let malformed_content = r#"
<?xml version="1.0" encoding="utf-8"?>
<xbrl xmlns="http://www.xbrl.org/2003/instance">
<context id="c0">
<!-- Missing closing tag -->
<context>
</xbrl>
"#;
let result = parse_xml(malformed_content);
assert!(result.is_err(), "Should fail to parse malformed XML");
assert!(matches!(result, Err(XbrlError::Malformed(_))));
}
#[test]
fn test_namespace_prefix_root_element() {
let content_with_namespace = r#"
<?xml version="1.0" encoding="utf-8"?>
<xbrli:xbrl xmlns:xbrli="http://www.xbrl.org/2003/instance">
<xbrli:context id="c0">
<xbrli:entity>
<xbrli:identifier scheme="http://www.sec.gov/CIK">0001234567</xbrli:identifier>
</xbrli:entity>
<xbrli:period>
<xbrli:instant>2021-03-31</xbrli:instant>
</xbrli:period>
</xbrli:context>
</xbrli:xbrl>
"#;
let result = parse_xml(content_with_namespace);
assert!(result.is_ok(), "Should parse XBRL with namespace prefix");
let xbrl = result.unwrap();
assert_eq!(xbrl.contexts.len(), 1);
assert_eq!(xbrl.contexts[0].id, "c0");
}
#[test]
fn test_missing_root_element() {
let content_without_root = r#"
<?xml version="1.0" encoding="utf-8"?>
<document>
<context id="c0"/>
</document>
"#;
let result = parse_xml(content_without_root);
assert!(result.is_err());
assert!(matches!(result, Err(XbrlError::NotXbrl(_))));
}
}