‫معرفی InterpolatedParser: جایگزینی خواناتر برای Regex در سی شارپ

InterpolatedParser چیست؟

string name = "";
int age = 0;
InterpolatedParser.Parse($"Name: {name}, Age: {age}", "Name: Alice, Age: 30");

Console.WriteLine(name); // خروجی: Alice
Console.WriteLine(age);  // خروجی: 30

مزایای InterpolatedParser

• ایمنی نوع (Type Safety): مقادیر مستقیماً به نوع صحیح متغیرها (مانند int، DateTime) تجزیه می‌شوند، که احتمال بروز خطاهای مربوط به نوع داده را کاهش می‌دهد.
• الگوهای خوانا (Readable Templates): الگوهای مورد استفاده برای تجزیه، شباهت زیادی به فرمت خروجی مورد انتظار دارند، که درک آن‌ها را در مقایسه با عبارات پیچیده Regex آسان‌تر می‌کند.
• ادغام آسان (Easy Integration): این کتابخانه به خوبی با انواع رایج .NET و همچنین انواع سفارشی که رابط‌های IParseable<T> یا ISpanParseable<T> را پیاده‌سازی می‌کنند، سازگار است.

مقایسه InterpolatedParser و Regex: چه زمانی از کدام استفاده کنیم؟

• InterpolatedParser:

string level = "";
string message = "";
InterpolatedParser.Parse($"[{level}] {message}", "[INFO] Application started");

• Regex:

var match = Regex.Match("[INFO] Application started", @"\[(.*?)\] (.+)");
string level = match.Groups[1].Value;
string message = match.Groups[2].Value;

• InterpolatedParser:

string key = "";
string value = "";
InterpolatedParser.Parse($"{key}={value}", "username=admin");

• Regex:

var match = Regex.Match("username=admin", @"(.+?)=(.+)");
string key = match.Groups[1].Value;
string value = match.Groups[2].Value;

bool isValid = Regex.IsMatch("user@example.com", @"^[^@\s]+@[^@\s]+\.[^@\s]+$");

var match = Regex.Match("https://example.com/path", @"^(https?)://([^/]+)(/.*)?$");

چه زمانی از InterpolatedParser استفاده کنیم؟

• لاگ‌های ساختاریافته (مانند "[INFO] Application started")
• گزارش‌ها یا فرم‌ها (مانند "Name: John Doe, Age: 30")
• سطرهای ساده فایل‌های CSV (مقادیر با کاما جدا شده) (مانند "Alice,30,Female")
• رویدادهای بازی یا داده‌های تله‌متری (مانند "Event: Jump, PlayerID: 123")
• دستورات ربات‌های گفتگو (مانند "/ban @user123 reason=spam")
• فایل‌های پیکربندی (مانند "key=value")

چه زمانی از InterpolatedParser استفاده نکنیم؟

• ورودی‌های با فرمت آزاد یا ناسازگار
• وظایف اعتبارسنجی (مانند ایمیل‌ها، گذرواژه‌ها)
• الگوهای اختیاری یا تکرارشونده
• تجزیه HTML، JSON یا XML (برای این موارد، کتابخانه‌های تخصصی مانند System.Text.Json یا System.Xml.Linq مناسب‌تر هستند.)
• مسیرهای حیاتی از نظر عملکرد که نیاز به تجزیه سنگین دارند (Regex در برخی موارد می‌تواند از نظر عملکرد بهینه‌تر باشد.)

موارد استفاده واقعی (قطعه‌های کد)

string command = "";
string user = "";
InterpolatedParser.Parse($"/{command} @{user}", "/ban @user123");

string level = "";
string message = "";
InterpolatedParser.Parse($"[{level}] {message}", "[ERROR] Disk full");

int major = 0, minor = 0;
InterpolatedParser.Parse($"Version {major}.{minor}", "Version 1.2");

int cpuUsage = 0, ramUsage = 0;
InterpolatedParser.Parse($"CPU: {cpuUsage}%, RAM: {ramUsage}%", "CPU: 40%, RAM: 80%");

تجزیه داده‌های تله‌متری دستگاه‌های IoT با انواع سفارشی

// نوع سفارشی برای تجزیه زمان روشن بودن دستگاه (uptime)
public struct DeviceUptime : IParseable<DeviceUptime>
{
    public TimeSpan Value { get; set; }

    public static DeviceUptime Parse(string s, IFormatProvider? provider)
    {
        var parts = s.Split(' ');
        int days = int.Parse(parts[0].TrimEnd('d'));
        int hours = int.Parse(parts[1].TrimEnd('h'));
        int minutes = int.Parse(parts[2].TrimEnd('m'));
        return new DeviceUptime { Value = new TimeSpan(days, hours, minutes, 0) };
    }
}

// نوع سفارشی برای تجزیه لیست کدهای خطا (error codes)
public struct ErrorCodeList : IParseable<ErrorCodeList>
{
    public List<string> Codes { get; set; }

    public static ErrorCodeList Parse(string s, IFormatProvider? provider)
    {
        return new ErrorCodeList { Codes = s.Split(',').ToList() };
    }
}

// اجرای تجزیه
DateTime timestamp = DateTime.MinValue;
string deviceId = "";
double soilMoisture = 0;
double temperature = 0;
DeviceUptime uptime = new();
ErrorCodeList errorCodes = new();

string input = "[2025-04-12T11:30:00Z] AGRI-007|45.6|28.3|15d 4h 30m|ERR_001,ERR_003";

InterpolatedParser.Parse(
    $"[{timestamp}] {deviceId}|{soilMoisture}|{temperature}|{uptime}|{errorCodes}",
    input
);

// نتایج:
// timestamp = 2025-04-12 11:30:00 UTC
// deviceId = "AGRI-007"
// soilMoisture = 45.6
// temperature = 28.3
// uptime.Value = 15 روز، 4 ساعت، 30 دقیقه
// errorCodes.Codes = ["ERR_001", "ERR_003"]

• مدیریت انواع سفارشی: نشان می‌دهد که چگونه می‌توان با پیاده‌سازی رابط IParseable<T>، منطق تجزیه سفارشی را برای انواع داده‌های خاص تعریف کرد.
• ساختار پیچیده: InterpolatedParser قادر است چندین نوع داده مختلف را در یک عملیات تجزیه واحد مدیریت کند.
• الگوی واقعی: فرمت داده‌های تله‌متری شبیه‌سازی شده، یک الگوی رایج در برنامه‌های کاربردی IoT است. InterpolatedParser در این حالت با حفظ ایمنی نوع، خوانایی الگو و تخصیص مستقیم متغیرها، عملکرد خوبی ارائه می‌دهد.
• قابلیت توسعه‌پذیری: این مثال نشان می‌دهد که چگونه می‌توان IParseable<T> را برای فرمت‌های خاص دامنه پیاده‌سازی کرد.

چگونه شروع کنیم؟

1. نصب از طریق NuGet: از طریق مدیریت بسته NuGet در ویژوال استودیو یا با استفاده از دستور dotnet add package InterpolatedParser در خط فرمان، این بسته را به پروژه خود اضافه کنید.
2. انواع پشتیبانی شده: InterpolatedParser از انواع داخلی مانند int، DateTime و مجموعه‌ها (List<T>, آرایه‌ها) پشتیبانی می‌کند. همچنین، از انواع سفارشی که رابط‌های IParseable<T> یا ISpanParseable<T> را پیاده‌سازی می‌کنند نیز پشتیبانی می‌شود.
3. محدودیت‌ها: همانطور که قبلاً ذکر شد، این کتابخانه برای مسیرهای حیاتی از نظر عملکرد و الگوهای بسیار پیچیده به اندازه Regex مناسب نیست.

نتیجه‌گیری