calamine

 
 

کتابخانهٔ Rust خالص برای صفحات گسترده

خواندن XLS، XLSX، XLSM، XLSB، ODS و موارد بیشتر با تجزیهٔ بدون کپی در Rust.

کالامین چیست؟

calamine یک کتابخانهٔ با عملکرد بالا و خالص Rust برای خواندن و تجزیهٔ فایل‌های صفحه‌گسترده Excel و OpenDocument است. این کتابخانه فرمت‌هایی مانند XLS، XLSX، XLSM، XLSB، ODS و موارد دیگر را پشتیبانی می‌کند و بر استخراج داده‌های سریع، ایمن و بدون کپی‌برداری تمرکز دارد. برای قابلیت اطمینان و وابستگی‌های کم طراحی شده است؛ calamine از کتابخانه‌های سیستمی خارجی اجتناب می‌کند و صرفاً به پیاده‌سازی‌های خالص Rust متکی است. API آن به توسعه‌دهندگان امکان می‌دهد به‌صورت کارآمد مقادیر سلول‌ها را استخراج کنند، پروژه‌های VBA را مدیریت کنند و فرمول‌ها را بدون تنظیمات پیچیده یا بار اجرایی اضافی تجزیه کنند.

این کتابخانه در برنامه‌های حساس به عملکرد برتری دارد و پردازش را نسبت به گزینه‌های Python، C# و Go به‌طور قابل‌توجهی سریع‌تر می‌کند. با ادغام داخلی Serde، calamine امکان نگاشت یکپارچهٔ داده‌های صفحه‌گسترده به ساختارهای Rust را فراهم می‌آورد. از بارگذاری تنبل برای فایل‌های بزرگ، پیکربندی ردیف سرعنوان، و ویژگی‌های اختیاری مانند پشتیبانی از تاریخ/زمان chrono و استخراج داده‌های تصویر پشتیبانی می‌کند. چه در حال ساخت ابزارهای خط فرمان، بک‌اندهای وب یا سیستم‌های تعبیه‌شده باشید، calamine عملکردی قوی، پیش‌بینی‌پذیر و سازگار بر روی همهٔ پلتفرم‌ها ارائه می‌دهد.

Previous Next

شروع کار با کالامین

برای شروع استفاده از کالامین، آن را از طریق Cargo به پروژه Rust خود اضافه کنید. می‌توانید آن را به‌صورت مستقیم با استفاده از cargo add calamine نصب کنید یا به‌صورت دستی وابستگی را به فایل Cargo.toml خود اضافه کنید. این کتابخانه در crates.io موجود است و کد منبع آن در GitHub کالامین میزبانی می‌شود. برای استفاده پیشرفته، ویژگی‌های اختیاری مانند chrono برای پشتیبانی از تاریخ/زمان یا picture برای استخراج داده‌های تصویر را فعال کنید. کتابخانه به‌راحتی بر روی Rust پایدار کامپایل می‌شود و نیازی به باینری‌ها یا کتابخانه‌های سیستمی خارجی ندارد.

نصب کالامین از طریق 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 را از ماژول‌ها بازیابی کنند، ارجاعات خراب را شناسایی کنند و نام‌های تعریف‌شده و فرمول‌های آن‌ها را بررسی کنند. این قابلیت برای ابزارهای مهاجرت، ابزارهای حسابرسی و تحلیل سیستم‌های قدیمی ضروری است. API دسترسی ساختار یافته به متادیتای 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 از بارگذاری تنبل (lazy loading) برای فایل‌های XLSX و XLSB پشتیبانی می‌کند و امکان پردازش کارآمد صفحات گسترده بزرگ را بدون بارگذاری تمام شیت‌ها در حافظه به‌صورت همزمان فراهم می‌سازد. با پیکربندی ردیف‌های سرصفحه و استفاده از تکرار مبتنی بر بازه، توسعه‌دهندگان می‌توانند ردپای حافظه را به حداقل رسانده و بازدهی را حداکثر کنند. این ویژگی به‌ویژه برای توابع بدون سرور، ابزارهای خط فرمان (CLI) و استقرارهای جاسازی‌شده که منابع محدود هستند، ارزشمند است. بنچمارک‌ها نشان می‌دهند که calamine می‌تواند بیش از 1 میلیون ردیف را با مصرف حافظه کم نسبت به گزینه‌هایی مانند 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 میلیون سلول را در کمتر از ۲۵ ثانیه پردازش می‌کند—که تا ۹٫۴ برابر بهتر از کتابخانه‌های Python، C# و Go است. طراحی صفر‑کپی و تخصیص‌های کم‌حافظه‌ای آن باعث کاهش قابل توجه مصرف CPU و حافظه می‌شود. بنچمارک‌ها روی یک فایل XLSX با حجم ۱۸۶ MB نشان می‌دهد که calamine تنها ۱۸۶ MB خواندن دیسک استفاده می‌کند در حالی که excelize به ۱٫۵ GB نیاز دارد. رفتار حافظهٔ deterministic کتابخانه و فشار کم GC آن، این کتابخانه را برای برنامه‌های زمان‑واقعی و حساس به تأخیر مناسب می‌سازد. توسعه‌دهندگان از استفاده پیش‌بینی‌پذیر منابع و توان پردازشی ثابت در بارهای کاری متنوع بهره‌مند می‌شوند.

 فارسی