
calamine
مكتبة Rust نقيّة للجداول
قراءة XLS و XLSX و XLSM و XLSB و ODS وأكثر مع فك تسلسل بدون نسخ في Rust.
ما هو calamine؟
calamine هي مكتبة Rust نقية وعالية الأداء لقراءة وتحويل ملفات جداول البيانات Excel و OpenDocument. تدعم صيغًا مثل XLS و XLSX و XLSM و XLSB و ODS وغيرها، مع التركيز على استخراج البيانات بسرعة وأمان ودون نسخ. صُممت للموثوقية واعتماد أقل قدر من التبعيات، حيث تتجنب calamine المكتبات النظامية الخارجية وتعتمد فقط على تنفيذات Rust النقية. يتيح API الخاص بها للمطورين استخراج قيم الخلايا، التعامل مع مشاريع VBA، وتحليل الصيغ دون إعداد معقد أو عبء تشغيل إضافي.
تتفوق المكتبة في التطبيقات التي تتطلب أداءً عاليًا، حيث توفر معالجة أسرع بكثير مقارنةً ببدائل Python و C# و Go. مع تكامل Serde المدمج، تسمح calamine بربط بيانات جداول البيانات بسلاسة إلى هياكل Rust. تدعم التحميل الكسول للملفات الكبيرة، تكوين صف العنوان، وميزات اختيارية مثل دعم التاريخ/الوقت من chrono واستخراج بيانات الصور. سواء كنت تبني أدوات سطر الأوامر، خلفيات ويب، أو أنظمة مدمجة، تقدم calamine أداءً قويًا ومتوقعًا عبر المنصات.
البدء مع calamine
لبدء استخدام calamine، أضفه إلى مشروع Rust الخاص بك عبر Cargo. يمكنك تثبيته مباشرةً باستخدام cargo add calamine أو إضافة الاعتماد يدويًا إلى ملف Cargo.toml الخاص بك. المكتبة متاحة على crates.io ومصدر الشيفرة مستضاف على GitHub الخاص بـ calamine. للاستخدام المتقدم، فعّل الميزات الاختيارية مثل chrono لدعم التاريخ/الوقت أو picture لاستخراج بيانات الصور. تُجمع المكتبة بنجاح على Rust المستقر ولا تتطلب أي ملفات تنفيذية أو مكتبات نظام خارجية.
تثبيت calamine عبر Cargo
cargo add calamineإلغاء تسلسل جداول البيانات المستند إلى Serde
توفر مكتبة calamine تكاملًا قويًا مع Serde لتخطيط بيانات الجداول مباشرة إلى هياكل Rust. باستخدام RangeDeserializerBuilder، يمكن للمطورين تعريف نماذج بيانات ذات نوعية قوية وتفكيك الصفوف تلقائيًا إلى سجلات منظمة. تشمل المكتبة وظائف مساعدة مثل deserialize_as_f64_or_none و deserialize_as_f64_or_string للتعامل مع الأعمدة المختلطة الأنواع بسلاسة. يضمن هذا النهج سلامة النوع، يقلل من الكود المتكرر، ويفعل التحقق من صحة هياكل البيانات في وقت التجميع. إنه مفيد بشكل خاص لأنابيب البيانات، أدوات التقارير، وتطبيقات ETL حيث تكون الموثوقية والأداء أمرًا حاسمًا.
إلغاء تسلسل صفوف جداول البيانات إلى هياكل Rust
use calamine::{deserialize_as_f64_or_none, open_workbook, RangeDeserializerBuilder, Reader, Xlsx};
use serde::Deserialize;
#[derive(Deserialize)]
struct Record {
metric: String,
#[serde(deserialize_with = "deserialize_as_f64_or_none")]
value: Option,
}
let mut excel: Xlsx<_> = open_workbook("file.xlsx")?;
let range = excel.worksheet_range("Sheet1")?;
let iter = RangeDeserializerBuilder::with_headers(&["metric", "value"]).from_range(&range)?;
for result in iter {
let record: Record = result?;
println!("{:?}", record);
} استخراج مشروع VBA والصيغ
تمكن calamine من استخراج وحدات مشروع VBA وتعريفات الصيغ من ملفات Excel. يمكن للمطورين استرجاع كود VBA من الوحدات، واكتشاف المراجع المكسورة، وفحص الأسماء المعرفة وصيغها. هذه القدرة أساسية لأدوات الترحيل، وأدوات التدقيق، وتحليل الأنظمة القديمة. توفر الواجهة البرمجية وصولًا منظمًا إلى بيانات تعريف VBA وتدعم سيناريوهات فحص المصنف البسيطة والمعقدة. سواءً كنت تحلل الماكرو للأمان أو تحول منطق Excel القديم، فإن calamine تقدم وصولًا دقيقًا ومنخفض المستوى إلى محتوى المصنف المخفي.
استخراج كود VBA والأسماء المعرفة
use calamine::{open_workbook_auto, Reader};
let mut workbook = open_workbook_auto("file.xlsx")?;
if let Ok(Some(vba)) = workbook.vba_project() {
let module = vba.get_module("Module1").unwrap();
println!("{}", module);
for ref in vba.get_references() {
if ref.is_missing() { println!("Broken: {}", ref.name); }
}
}
for (name, formula) in workbook.defined_names() {
println!("{}: {}", name, formula);
}التحميل الكسول ومعالجة الملفات الكبيرة
تدعم calamine التحميل الكسول لملفات XLSX و XLSB، مما يتيح معالجة فعّالة لجداول البيانات الكبيرة دون تحميل جميع الأوراق في الذاكرة دفعة واحدة. من خلال تكوين صفوف العناوين واستخدام التكرار القائم على النطاق، يمكن للمطورين تقليل استهلاك الذاكرة وتعظيم الإنتاجية. هذه الميزة ذات قيمة خاصة للوظائف بدون خادم، وأدوات سطر الأوامر، والنشر المدمج حيث تكون الموارد محدودة. تُظهر المعايير أن calamine تقرأ أكثر من مليون صف بحد أدنى من استهلاك الذاكرة مقارنةً بالبدائل مثل openpyxl و ClosedXML، مما يجعلها مثالية لأنابيب استيعاب البيانات على نطاق واسع.
معالجة جداول البيانات الكبيرة بكفاءة
use calamine::{open_workbook, Reader, Xlsx};
let mut excel: Xlsx<_> = open_workbook("large.xlsx")?;
let range = excel
.worksheet_range("Sheet1")?
.expect("Sheet not found");
for row in range.rows() {
// Process row without loading entire file
process_row(row);
}تحسين الأداء والمعايير
توفر calamine أداءً استثنائياً، حيث تعالج 41 مليون خلية في أقل من 25 ثانية—متفوقة على مكتبات Python و C# و Go بما يصل إلى 9.4 مرة. تصميمها بدون نسخ (zero-copy) والحد الأدنى من تخصيصات الكومة يقللان بشكل كبير من استهلاك وحدة المعالجة المركزية والذاكرة. تُظهر المعايير على ملف XLSX بحجم 186 ميغابايت أن calamine تستخدم فقط قراءات قرص بحجم 186 ميغابايت مقارنةً بـ 1.5 جيجابايت لـ excelize. سلوك الذاكرة الحتمي للمكتبة والضغط المنخفض على جامع القمامة (GC) يجعلها مناسبة للتطبيقات ذات الوقت الحقيقي والحساسة للكمون. يستفيد المطورون من استخدام موارد متوقع وثابت وإنتاجية مستمرة عبر أحمال عمل متنوعة.
