xmloxide

إعادة تنفيذ نقي بلغة Rust لمكتبة libxml2 — مكتبة تحليل XML/HTML القياسية الفعلية في عالم المصادر المفتوحة.

أصبحت libxml2 غير مدعومة رسميًا منذ ديسمبر 2025 مع مشاكل أمنية معروفة. تهدف xmloxide إلى أن تكون بديلاً آمنًا للذاكرة وعالي الأداء ينجح في نفس مجموعات اختبار المطابقة.

المميزات

• آمن للذاكرة — شجرة قائمة على الساحة (arena) مع عدم وجود unsafe في الواجهة العامة
• مطابق للمعايير — نسبة نجاح 100% في مجموعة اختبار مطابقة XML من W3C (1727/1727 اختبارًا قابلًا للتطبيق)
• استرداد الأخطاء — تحليل XML غير صحيح مع الاستمرار في إنتاج شجرة قابلة للاستخدام، تمامًا مثل libxml2
• واجهات برمجة تحليل متعددة — شجرة DOM، دفق SAX2، سحب XmlReader، تحليل دفعي/متزايد
• محلل HTML — تحليل HTML 4.01 متسامح مع الأخطاء مع الإغلاق التلقائي والعناصر الفارغة
• محلل WHATWG HTML5 — محلل كامل وفقًا لمعيار HTML الحي (8810/8810 من اختبارات html5lib-tests ناجحة)
• دفق HTML5 — واجهة رد نداء شبيهة بـ SAX لـ HTML5 (html5::sax) تغلف المحلل دون بناء شجرة DOM
• محددات CSS — استعلام عن العناصر باستخدام صيغة CSS مألوفة (css::select) تشمل الأدوات المركبة والفئات الزائفة والبحث السريع بـ #id
• XPath 1.0+ — محلل ومقيّم تعبيرات كامل مع جميع دوال XPath 1.0 الأساسية بالإضافة إلى دوال XPath 2.0 رئيسية (matches()، replace()، tokenize()، upper-case()، lower-case()، abs()، min()، max()، والمزيد)
• التحقق — التحقق من DTD، RelaxNG، XML Schema (XSD)، و ISO Schematron (ISO/IEC 19757-3)
• التكامل مع Serde — ميزة اختيارية serde لتسلسل/إلغاء تسلسل XML من/إلى أنواع Rust
• التحليل غير المتزامن — ميزة اختيارية async للتحليل من مصادر tokio::io::AsyncRead
• XML قانوني — تسلسل C14N 1.0 و Exclusive C14N
• XInclude — معالجة تضمين المستندات
• كتالوجات XML — كتالوجات XML من OASIS لحل URIs
• أداة CLI xmllint — أداة سطر أوامر لتحليل XML والتحقق منه والاستعلام عنه
• نسخ صفري حيثما أمكن — تخزين السلاسل مؤقتًا لإجراء مقارنات سريعة
• بدون حالة عمومية — كل Document مستقل ويمكن إرساله (Send) ومشاركته بين الخيوط (Sync)
• FFI بلغة C/C++ — واجهة C كاملة مع ملف رأس (include/xmloxide.h) للتضمين في مشاريع C/C++
• أقل عدد من التبعيات — فقط encoding_rs (المكتبة ليس لها تبعيات أخرى؛ clap مخصص لسطر الأوامر فقط)

بداية سريعة

use xmloxide::Document;

let doc = Document::parse_str("<root><child>Hello</child></root>").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("root"));
assert_eq!(doc.text_content(root), "Hello");

التسلسل

use xmloxide::Document;
use xmloxide::serial::serialize;

let doc = Document::parse_str("<root><child>Hello</child></root>").unwrap();
let xml = serialize(&doc);
assert_eq!(xml, "<root><child>Hello</child></root>");

استعلامات XPath

use xmloxide::Document;
use xmloxide::xpath::{evaluate, XPathValue};

let doc = Document::parse_str("<library><book><title>Rust</title></book></library>").unwrap();
let root = doc.root_element().unwrap();
let result = evaluate(&doc, root, "count(book)").unwrap();
assert_eq!(result.to_number(), 1.0);

دفق SAX2

use xmloxide::sax::{parse_sax, SaxHandler, DefaultHandler};
use xmloxide::parser::ParseOptions;

struct MyHandler;
impl SaxHandler for MyHandler {
    fn start_element(&mut self, name: &str, _: Option<&str>, _: Option<&str>,
                     _: &[(String, String, Option<String>, Option<String>)]) {
        println!("Element: {name}");
    }
}

parse_sax("<root><child/></root>", &ParseOptions::default(), &mut MyHandler).unwrap();

تحليل HTML

use xmloxide::html::parse_html;

let doc = parse_html("<p>Hello <br> World").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("html"));

محددات CSS

use xmloxide::css::select;
use xmloxide::Document;

let doc = Document::parse_str(r#"<div><p class="intro">Hello</p><p>World</p></div>"#).unwrap();
let root = doc.root_element().unwrap();
let intros = select(&doc, root, "p.intro").unwrap();
assert_eq!(intros.len(), 1);
assert_eq!(doc.text_content(intros[0]), "Hello");

تحليل HTML5 (WHATWG)

use xmloxide::html5::parse_html5;

let doc = parse_html5("<p>Hello <b>world</b>").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("html"));

كما أن تحليل القطع (الخوارزمية التي تقف وراء innerHTML) مدعوم:

use xmloxide::html5::{parse_html5_with_options, Html5ParseOptions};

let opts = Html5ParseOptions {
    scripting: false,
    fragment_context: Some("body".to_string()),
};
let doc = parse_html5_with_options("<p>fragment</p>", &opts).unwrap();

دفق HTML5 (شبيه بـ SAX)

use xmloxide::html5::sax::{Html5SaxHandler, parse_html5_sax};

struct LinkExtractor { hrefs: Vec<String> }
impl Html5SaxHandler for LinkExtractor {
    fn start_element(&mut self, name: &str, attrs: &[(String, String)], _sc: bool) {
        if name == "a" {
            if let Some((_, href)) = attrs.iter().find(|(n, _)| n == "href") {
                self.hrefs.push(href.clone());
            }
        }
    }
}

let mut handler = LinkExtractor { hrefs: Vec::new() };
parse_html5_sax(r#"<a href="/page">Link</a>"#, &mut handler);
assert_eq!(handler.hrefs, vec!["/page"]);

استرداد الأخطاء

use xmloxide::parser::{parse_str_with_options, ParseOptions};

let opts = ParseOptions::default().recover(true);
let doc = parse_str_with_options("<root><unclosed>", &opts).unwrap();
for diag in &doc.diagnostics {
    eprintln!("{}", diag);
}

أداة سطر الأوامر

# تحليل وطباعة منسقة
xmllint --format document.xml

# تحقق مقابل مخطط
xmllint --schema schema.xsd document.xml
xmllint --relaxng schema.rng document.xml
xmllint --schematron schema.sch document.xml
xmllint --dtdvalid schema.dtd document.xml

# استعلام XPath
xmllint --xpath "//title" document.xml

# XML قانوني
xmllint --c14n document.xml

# تحليل HTML
xmllint --html page.html

نظرة عامة على الوحدات

الأداء

إنتاجية التحليل تنافسية مع libxml2 — ضمن 3-4% في معظم المستندات، وأسرع بنسبة 12% في SVG. التسلسل أسرع بين 1.5 و 2.4 مرة بفضل تصميم الشجرة القائمة على الساحة. XPath أسرع بين 1.1 و 2.7 مرة عبر جميع المعايير.

التحليل:

التسلسل:

XPath:

التحسينات الرئيسية: شجرة قائمة على الساحة للتسلسل السريع، فحوصات مسبقة على مستوى البايت للتحقق من الأحرف، مسح نصي شامل، مسارات سريعة لـ ASCII لتحليل الأسماء، تقسيم أسماء العناصر بدون نسخ، حل الكيانات المضمنة، دمج خطوات XPath // مع توسيع المحاور المدمجة، موصلات شجرة مضمنة، ومسارات سريعة لاختبار الأسماء لمحاور الطفل/السليل.

# تشغيل المعايير (يتطلب مكتبة libxml2 النظامية)
cargo bench --features bench-libxml2 --bench comparison_bench

الاختبار

• 1078 اختبار وحدة عبر جميع الوحدات
• 138 اختبار FFI تغطي كامل واجهة C API (بما في ذلك SAX وSchematron وCSS)
• مجموعة توافق libxml2 — 119/119 اختبارًا ناجحًا (100%) تغطي تحليل XML والمساحات الاسمية واكتشاف الأخطاء وتحليل HTML
• مجموعة اختبار مطابقة XML من W3C — 1727/1727 اختبارًا قابلًا للتطبيق ناجحة (100%)
• اختبارات html5lib — 7032/7032 اختبار محلل الرموز + 1778/1778 اختبار بناء الشجرة (100%)
• اختبارات تكاملية تغطي مستندات XML/HTML حقيقية وحالات الحواف واسترداد الأخطاء

cargo test --all-features

FFI بلغة C/C++

توفر xmloxide واجهة متوافقة مع C لتضمينها في مشاريع C/C++ (مثل Chromium أو محركات الألعاب أو أي قاعدة بيانات تستخدم حالياً libxml2).

# بناء المكتبات المشتركة + الثابتة (يستخدم ملف Makefile المرفق)
make

# أو البناء بشكل فردي:
make shared   # .so / .dylib / .dll
make static   # .a / .lib

# بناء وتشغيل مثال C
make example

#include "xmloxide.h"

xmloxide_document *doc = xmloxide_parse_str("<root>Hello</root>");
uint32_t root = xmloxide_doc_root_element(doc);
char *name = xmloxide_node_name(doc, root);   // "root"
char *text = xmloxide_node_text_content(doc, root); // "Hello"

xmloxide_free_string(name);
xmloxide_free_string(text);
xmloxide_free_doc(doc);

واجهة API الكاملة — بما في ذلك التنقل في الشجرة وتعديلها، تقييم XPath، التسلسل (العادي والمطبوع بشكل جميل)، تحليل HTML/HTML5، التحقق من DTD/RelaxNG/XSD/Schematron، C14N، دفق SAX، XmlReader، المحلل الدفعي، وكتالوجات XML — مُعلنة في include/xmloxide.h.

الانتقال من libxml2

سلامة الخيوط: على عكس libxml2، لا تحتوي xmloxide على حالة عمومية. كل Document مستقل ويمكن إرساله ومشاركته بين الخيوط. تستخدم طبقة FFI مخزناً محلياً للخيط لرسالة الخطأ الأخيرة — كل خيط له حالة خطأ خاصة به. لا حاجة لدوال التهيئة أو التنظيف.

اختبار الضعف (Fuzzing)

تتضمن xmloxide أهداف اختبار ضعف لاختبار الأمان:

# تثبيت cargo-fuzz (يتطلب nightly)
cargo install cargo-fuzz

# تشغيل هدف اختبار ضعف
cargo +nightly fuzz run fuzz_xml_parse
cargo +nightly fuzz run fuzz_html_parse
cargo +nightly fuzz run fuzz_html5_parse
cargo +nightly fuzz run fuzz_html5_fragment
cargo +nightly fuzz run fuzz_xpath
cargo +nightly fuzz run fuzz_roundtrip
cargo +nightly fuzz run fuzz_sax
cargo +nightly fuzz run fuzz_reader
cargo +nightly fuzz run fuzz_push
cargo +nightly fuzz run fuzz_validation
cargo +nightly fuzz run fuzz_schematron

البناء

cargo build
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo bench

الحد الأدنى من إصدار Rust المدعوم: 1.81

القيود

• بدون XML 1.1 — تنفذ xmloxide XML 1.0 (الطبعة الخامسة) فقط. XML 1.1 نادر الاستخدام وغير مخطط له.
• بدون XSLT — XSLT مواصفة منفصلة (libxslt) وخارج نطاق المشروع.
• محللات HTML — يتم توفير كل من محلل HTML 4.01 (مطابق لسلوك libxml2) ومحلل WHATWG HTML5 كامل. ينجح محلل HTML5 في 100% من اختبارات html5lib-tests.
• المحلل الدفعي يخزن داخليًا — واجهة المحلل الدفعي/المتزايد (PushParser) تقوم حالياً بتخزين جميع البيانات المدفوعة وتنفيذ التحليل الكامل عند finish()، بدلاً من التدفق الحقيقي مثل xmlParseChunk في libxml2. يتوفر دفق SAX (parse_sax لـ XML و html5::sax::parse_html5_sax لـ HTML5) كبديل لمعالجة المستندات الكبيرة المقيدة بالذاكرة.
• محور XPath namespace:: — يعيد محور namespace:: عقدة العنصر عندما تتطابق المساحات الاسمية في النطاق (بدلاً من إنشاء عقد مساحة اسمية منفصلة)، متبعاً نفس نمط محور السمة.

المساهمة

انظر CONTRIBUTING.md لإعدادات التطوير والإرشادات.

سجل التغييرات

انظر CHANGELOG.md لتاريخ الإصدارات.

الترخيص

MIT