Neslib.Yaml
1.0.0
Neslib.yaml هي مكتبة لتحليل وبعثة YAML وبناء وثائق ودارات YAML.
Neslib.yaml تبني على الجزء العلوي من مكتبة Libyaml ويعمل على:
للتثبيت:
> git clone --recursive https://github.com/neslib/Neslib.Yamlتعتمد هذه المكتبة فقط على مستودع NESLIB ، والذي يتم تضمينه كوحدة فرعية مع هذا المستودع.
بالنسبة لجميع المنصات باستثناء MACOS 32 بت ، لا توجد تبعيات في وقت التشغيل: يتم ربط مكتبة Libyaml مباشرةً في القابل للتنفيذ. بالنسبة إلى MacOS 32 بت ، تحتاج إلى نشر مكتبة libyaml_mac32.dylib إلى ContentsMacOS .
هنا مقدمة موجزة جدا ل yaml. لمزيد من المعلومات التفصيلية ، ألقِ نظرة على موقع Yaml الرسمي أو أحد الموارد العديدة على الإنترنت مثل هذا.
Yaml (اختصار لـ "Yaml Ain't Markup Language") هي لغة تسلسل البيانات. على عكس العديد من اللغات الأخرى القائمة على النص (مثل JSON و XML) ، فإن الهدف الأساسي لـ YAML هو أن تكون قابلة للقراءة الإنسان وسهلة أيضًا إنشاء البشر. لهذا السبب يستخدم عادة لملفات التكوين. ومع ذلك ، يمكن استخدامه لجميع أنواع البيانات ، مثل هذا المثال من مواصفات YAML:
invoice : 34843
date : 2001-01-23
bill-to : &id001
given : Chris
family : Dumars
address :
lines : |
458 Walkman Dr.
Suite #292
city : Royal Oak
state : MI
postal : 48046
ship-to : *id001
product :
- sku : BL394D
quantity : 4
description : Basketball
price : 450.00
- sku : BL4438H
quantity : 1
description : Super Hoop
price : 2392.00
tax : 251.42
total : 4443.52
comments : >
Late afternoon is best.
Backup contact is Nancy
Billsmer @ 338-4338. وثيقة Yaml هي شجرة من القيم ، تسمى العقد ( TYamlNode في هذه المكتبة). هناك 4 أنواع من العقد:
التعيينات تشبه قواميس دلفي. رسم الخرائط عبارة عن مجموعة من أزواج المفاتيح/القيمة. الملاحظة الجذرية لمستند العينة أعلاه هي رسم الخرائط: إنه يرسم invoice المفتاح إلى القيمة 34843 ويحتوي على 7 أزواج مفتاح/قيمة أخرى (من date إلى comments ). يمكن أن يكون كل من المفتاحين والقيم أي نوع من أنواع YAML ، على الرغم من أنك ربما ترغب في التمسك بالسلاسل للمفاتيح.
يمكن كتابة التعيينات في تدوين الكتلة (كما في المثال) أو تدوين التدفق (باستخدام أقواس مجعد {} ).
عند استخدام تدوين الكتلة ، يستخدم Yaml المسافة البادئة للنطاق. مساحات فقط مساحات للمسافة البادئة ( وليس علامات التبويب). لا يهم عدد المساحات طالما أن جميع القيم في نفس المستوى تستخدم نفس كمية المساحات. في المثال ، فإن قيمة bill-to مفتاح آخر. تم وضع مسافة بادئة لهذا التعيين للإشارة إلى أنه ينتمي إلى مفتاح bill-to الفاتورة.
تسلسلات مثل صفائف أو قوائم دلفي. يمكن كتابة تسلسلات صغيرة باستخدام تدوين التدفق (باستخدام قوسين مربع [] ). عادة ما تتم كتابة التسلسلات الأكبر أو المعقدة في تدوين الكتلة كما في المثال: قيمة مفتاح product هي تسلسل من منتجين (كرة سلة وطوق سوبر). يبدأ كل عنصر في التسلسل مع اندفاعة ومساحة.
في هذا المثال ، يكون كل منتج في التسلسل عبارة عن رسم خرائط لـ 4 أزواج مفتاح/قيمة.
جميع العقد لها خصائص على الأقل: Tag Anchor . تُستخدم العلامات لوصف النوع الدلالي للعقدة. العلامات ليست شائعة ، لذلك سأخطيها في هذه المقدمة. NESLIB.YAML لديه دعم كامل للعلامات رغم ذلك.
يمكن استخدام مرساة لتمييز عقدة في المستند. يمكنك بعد ذلك الرجوع لاحقًا إلى هذه العقدة باستخدام الاسم المستعار .
تربى المراسي مع ampersand ( & ). في المثال ، تحتوي قيمة bill-to مرساة تسمى id001 (Ampersand ليست جزءًا من الاسم). في وقت لاحق في المستند ، يشير مفتاح ship-to إلى هذه المرساة باستخدام الاسم المستعار (علامة النجمة تليها اسم المرساة ، على سبيل المثال. *id001 ). هذه طريقة للقول إن عنوان الشحن هو نفسه عنوان الفوترة. لاحظ أن الاسم المستعار لا ينسخ القيمة المشار إليها ؛ إنه حقًا يشير فقط إلى عقدة أخرى.
يجب أن تظهر المراسي في المستند قبل الرجوع إليها. لا يجب أن تكون أسماءهم فريدة من نوعها في المستند ؛ إذا تم الإعلان عن مرساة جديدة بنفس الاسم ، فإنه يحل محل المرساة القديمة.
العدادات هي أبسط الأنواع. كل ما ليس رسم الخرائط أو التسلسل أو الاسم المستعار هو العددية. في الممارسة العملية ، العدادات هي مجرد سلاسل. جميع المفاتيح في المثال أعلاه هي أرقام سلسلة ، ولكن الكثير من القيم هي كذلك (مثل 34843 ، 2001-01-23 و Chris ).
يعامل مواصفات YAML 1.1 (وهو ما يستخدمه Libyaml) جميع هذه المقاطع كقواسل ، حتى لو كانت أرقامًا أو تواريخًا كما في هذا المثال. يمكنك استخدام العلامات لتوضيح بشكل صريح أن عددًا محددًا من نوع معين.
يوفر سجل TYamlNode في هذه المكتبة طرقًا مثل ToInteger و ToDouble إلى (محاولة) تحويل أنواع Delphi ، بغض النظر عن أي علامات قد يتم إرفاقها بعقدة.
يمكن كتابة القياس في "أنماط" مختلفة:
| ). في المثال أعلاه ، فإن قيمة bill-to.address.lines هي حرفية. يتم الحفاظ على أي خطوط جديدة في الحرفي.comments في المثال.هناك الكثير ل yaml ، ولكن هذا يجب أن يغطي العديد من حالات الاستخدام.
نقطة الدخول الرئيسية لهذه المكتبة هي واجهة IYamlDocument أو IYamlStream .
يمكن أن يحتوي ملف yaml على مستندات متعددة. إذا كان هذا هو الحال ، فيجب عليك استخدام IYamlStream لتحميله. الدفق هو مجرد مجموعة من المستندات (من النوع IYamlDocument ).
على الرغم من ذلك ، فإن ملف YAML يحتوي على مستند واحد فقط ، ومن الأسهل البدء بـ IYamlDocument . من السهل تحميل المستند:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; يمكنك التحميل من ملف أو دفق ، أو يمكنك تحليل نص Yaml باستخدام طريقة TYamlDocument.Parse .
يمكنك الآن استخدام خاصية IYamlDocument.Root لفحص المستند. هذه الخاصية من نوع TYamlNode ، وهي لبنة البناء لجميع المستندات.
يتم تنفيذ Tyamlnode كسجل للحفاظ على وزنه خفيفًا. جميع العقد هي "مالك" من مستند. هذا يجعل إدارة الذاكرة تلقائيًا بالكامل: بمجرد خروج المستند عن النطاق ، سيتم تحرير جميع العقد تلقائيًا. هذا يعني على الرغم من أنه لا ينبغي عليك "التمسك" بالعقد بعد خروج المستند. يؤدي القيام بذلك إلى سلوك غير محدد أو انتهاكات الوصول.
على سبيل المثال ، للوصول إلى price المنتج الأول في المثال أعلاه ، يمكنك استخدام الكود التالي:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; يمكنك استخدام خاصية Values للوصول إلى القيم حسب المفتاح في التعيين . وبالمثل ، يتم استخدام خاصية Nodes للوصول إلى القيم عن طريق الفهرس في تسلسل ، ويمكن استخدام إحدى طرق ToXXX لتحويل قيمة العددية إلى نوع بيانات Delphi.
للتحقق من نوع العقدة ، يمكنك استخدام خاصية NodeType أو واحدة من خصائص IsXXX ( IsMapping ، IsScalar وما إلى ذلك).
يمكنك أيضًا إنشاء مستند Yaml من نقطة الصفر وحفظه إلى ملف أو تحويله إلى Yaml. لإنشاء مستند yaml ، استخدم إحدى طرق TYamlDocument.CreateXXX ، اعتمادًا على نوع عقدة الجذر التي تحتاجها. إذا كنت ترغب في إعادة بناء مستند المثال ، فستبدأ برسم خرائط ومكالمة:
Doc := TYamlDocument.CreateMapping;يمكنك بعد ذلك البدء في إضافة أزواج المفتاح/القيمة:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); يتم استخدام طريقة AddOrSetValue لإضافة أزواج المفاتيح/القيمة إلى رسم الخرائط. إذا لم تكن العقدة عبارة عن رسم خرائط ، فسيتم رفع استثناء EInvalidOperation .
لإضافة قيمة غير سكانية ، استخدم إحدى أساليب AddOrSetXXX الأخرى:
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; هذا يضيف تسلسلًا إلى التعيين مع product الرئيسي. يمكنك بعد ذلك إضافة قيم إلى التسلسل باستخدام إحدى طرق AddXXX . مرة أخرى ، سيتم رفع استثناء EInvalidOperation إذا لم تكن العقدة تسلسلًا. في المثال ، نحتاج إلى إضافة تعيين آخر لهذا التسلسل:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; بمجرد إنشاء المستند الخاص بك ، يمكنك حفظه في ملف أو دفق باستخدام طريقة Save ، أو تحويله إلى YAML باستخدام طريقة ToYaml :
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; يمكنك تمرير سجل TYamlOutputSettings اختياري لتخصيص تنسيق yaml.
هناك المزيد لـ neslib.yaml مما هو موضح أعلاه. لمزيد من التفاصيل ، يمكنك إلقاء نظرة على ملف مصدر Neslib.Yaml.pas المستدير جيدًا. يمكن العثور على عينات استخدام إضافية في اختبارات الوحدة ، خاصة في ملف Tests.Neslib.Yaml.Sample.pas .
neslib.yaml مرخصة بموجب ترخيص BSD المبسط.
انظر الترخيص. txt للحصول على التفاصيل.
