Neslib.Yaml
1.0.0
Neslib.yaml adalah perpustakaan untuk parsing dan memancarkan YAML dan membangun dokumen dan aliran YAML.
Neslib.yaml dibangun di atas perpustakaan Libyaml dan bekerja di:
Untuk menginstal:
> git clone --recursive https://github.com/neslib/Neslib.YamlPerpustakaan ini hanya tergantung pada repositori NESLIB, yang disertakan sebagai submodule dengan repositori ini.
Untuk semua platform kecuali MacOS 32-bit, tidak ada dependensi run-time: Perpustakaan Libyaml ditautkan langsung ke yang dapat dieksekusi. Untuk macOS 32-bit, Anda perlu menggunakan perpustakaan libyaml_mac32.dylib ke ContentsMacOS .
Berikut adalah pengantar yang sangat singkat untuk YAML. Untuk informasi yang lebih rinci, lihat situs resmi YAML atau salah satu dari banyak sumber daya on-line seperti ini.
YAML (kependekan dari "Yaml Ain't Markup Language") adalah bahasa serialisasi data. Tidak seperti banyak bahasa berbasis teks serupa lainnya (seperti JSON dan XML), tujuan utama YAML adalah untuk dibaca manusia dan juga mudah dibuat oleh manusia. Itu sebabnya ini biasanya digunakan untuk file konfigurasi. Namun, ini dapat digunakan untuk semua jenis data, seperti contoh ini dari spesifikasi 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. Dokumen YAML adalah pohon nilai, yang disebut node ( TYamlNode di perpustakaan ini). Ada 4 jenis node:
Pemetaan mirip dengan kamus Delphi. Pemetaan adalah kumpulan pasangan kunci/nilai. Catatan root dari dokumen sampel di atas adalah pemetaan: memetakan invoice utama ke nilai 34843 dan berisi 7 pasangan kunci/nilai lainnya (dari date hingga comments ). Baik kunci dan nilai dapat berupa jenis YAML apa pun, meskipun Anda mungkin ingin tetap berpegang pada string untuk kunci.
Pemetaan dapat ditulis dalam notasi blok (seperti pada contoh) atau notasi aliran (menggunakan kawat gigi keriting {} ).
Saat menggunakan notasi blok, YAML menggunakan indentasi untuk melingkupi. Hanya spasi yang diizinkan untuk lekukan ( bukan tab). Jumlah ruang tidak masalah selama semua nilai pada level yang sama menggunakan jumlah ruang yang sama. Dalam contoh, nilai kunci bill-to adalah pemetaan lain. Pemetaan ini indentasi untuk menunjukkan bahwa itu milik kunci bill-to .
Urutan seperti array atau daftar Delphi. Urutan kecil dapat ditulis menggunakan notasi aliran (menggunakan braket persegi [] ). Urutan yang lebih besar atau kompleks biasanya ditulis dalam notasi blok seperti pada contoh: nilai kunci product adalah urutan dua produk (bola basket dan super hoop). Setiap item dalam urutan dimulai dengan tanda hubung dan ruang.
Dalam contoh ini, setiap produk dalam urutan adalah pemetaan 4 pasangan kunci/nilai.
Semua node memiliki setidaknya dua properti: Tag dan Anchor . Tag digunakan untuk menggambarkan jenis node semantik. Tag tidak begitu umum, jadi saya akan melewatkannya dalam pengantar ini. Neslib.yaml memiliki dukungan penuh untuk tag.
Jangkar dapat digunakan untuk menandai node dalam dokumen. Anda kemudian dapat merujuk kembali ke node ini menggunakan alias .
Jangkar diawali dengan ampersand ( & ). Dalam contoh, nilai kunci bill-to memiliki jangkar yang disebut id001 (ampersand bukan bagian dari nama). Kemudian dalam dokumen, kunci ship-to mengacu kembali ke jangkar ini menggunakan alias (tanda bintang diikuti dengan nama jangkar, mis. *id001 ). Ini adalah cara untuk mengatakan bahwa alamat pengirimannya sama dengan alamat penagihan. Perhatikan bahwa alias tidak menyalin nilai yang direferensikan; Itu benar -benar hanya mengacu pada simpul lain.
Jangkar harus muncul dalam dokumen sebelum dapat dirujuk. Nama mereka tidak harus unik dalam dokumen; Jika jangkar baru dinyatakan dengan nama yang sama, itu menggantikan jangkar lama.
Skalar adalah tipe yang paling sederhana. Segala sesuatu yang bukan pemetaan, urutan atau alias adalah skalar. Dalam praktiknya, skalar hanyalah string. Semua kunci dalam contoh di atas adalah skalar string, tetapi banyak nilainya juga (seperti 34843 , 2001-01-23 dan Chris ).
Spesifikasi YAML 1.1 (yang digunakan Libyaml) memperlakukan semua skalar ini sebagai string, bahkan jika mereka adalah angka atau tanggal seperti dalam contoh ini. Anda dapat menggunakan tag untuk secara eksplisit menyatakan bahwa skalar tertentu adalah jenis tertentu.
Catatan TYamlNode di perpustakaan ini menyediakan metode seperti ToInteger dan ToDouble untuk (mencoba) dikonversi ke tipe Delphi, terlepas dari tag apa pun yang mungkin dilampirkan ke node.
Skalar dapat ditulis dengan "gaya" yang berbeda:
| ). Dalam contoh di atas, nilai bill-to.address.lines adalah literal. Setiap garis baru dalam literal dilestarikan.comments dalam contoh.Ada lebih banyak lagi untuk YAML, tetapi ini harus mencakup banyak kasus penggunaan.
Titik masuk utama ke perpustakaan ini adalah IYamlDocument atau antarmuka IYamlStream .
File YAML dapat berisi beberapa dokumen. Jika itu masalahnya, Anda harus menggunakan IYamlStream untuk memuatnya. Aliran hanyalah kumpulan dokumen (tipe IYamlDocument ).
Namun sebagian besar waktu, file YAML hanya berisi satu dokumen dan lebih mudah untuk memulai dengan IYamlDocument . Memuat dokumen itu mudah:
var
Doc: IYamlDocument;
begin
Doc := TYamlDocument.Load( ' invoice.yaml ' );
end ; Anda dapat memuat dari file atau streaming, atau Anda dapat menguraikan teks YAML menggunakan metode TYamlDocument.Parse .
Anda sekarang dapat menggunakan properti IYamlDocument.Root untuk memeriksa dokumen. Properti ini adalah tipe TYamlNode , yang merupakan blok bangunan untuk semua dokumen.
Tyamlnode diimplementasikan sebagai catatan untuk membuatnya tetap ringan. Semua node adalah "pemilik" oleh dokumen. Ini membuat manajemen memori sepenuhnya otomatis: Setelah dokumen keluar dari ruang lingkup, semua node akan dibebaskan secara otomatis. Ini berarti meskipun Anda tidak boleh "bertahan" ke node setelah dokumen keluar dari ruang lingkup. Melakukan hal itu menghasilkan perilaku yang tidak terdefinisi atau pelanggaran akses.
Misalnya, untuk mengakses price produk pertama dalam contoh di atas, Anda dapat menggunakan kode berikut:
Price := Doc.Root.Values[ ' product ' ].Nodes[ 0 ].Values[ ' price ' ].ToDouble; Anda menggunakan properti Values untuk mengakses nilai dengan kunci dalam pemetaan . Demikian juga properti Nodes digunakan untuk mengakses nilai dengan indeks dalam urutan , dan salah satu metode ToXXX dapat digunakan untuk mengonversi nilai skalar menjadi tipe data Delphi.
Untuk memeriksa jenis node, Anda dapat menggunakan properti NodeType atau salah satu properti IsXXX ( IsMapping , IsScalar dll.).
Anda juga dapat membuat dokumen YAML dari awal dan menyimpannya ke file atau mengonversinya ke YAML. Untuk membuat dokumen YAML, gunakan salah satu metode TYamlDocument.CreateXXX , tergantung pada jenis simpul akar yang Anda butuhkan. Jika Anda ingin merekonstruksi dokumen contoh, Anda akan memulai dengan pemetaan dan menelepon:
Doc := TYamlDocument.CreateMapping;Anda kemudian dapat mulai menambahkan pasangan kunci/nilai:
Doc.Root.AddOrSetValue( ' invoice ' , 34843 );
Doc.Root.AddOrSetValue( ' date ' , ' 2001-01-23 ' ); Metode AddOrSetValue digunakan untuk menambahkan pasangan kunci/nilai ke pemetaan. Jika node bukan pemetaan, maka pengecualian EInvalidOperation akan dinaikkan.
Untuk menambahkan nilai non-skalar, gunakan salah satu metode AddOrSetXXX lainnya:
var
Products: TYamlNode;
begin
Products := Doc.Root.AddOrSetSequence( ' product ' );
end ; Ini menambahkan urutan ke pemetaan dengan product utama. Anda kemudian dapat menambahkan nilai ke urutan menggunakan salah satu metode AddXXX . Sekali lagi, pengecualian EInvalidOperation akan dinaikkan jika simpul bukan urutan. Dalam contoh, kita perlu menambahkan pemetaan lain ke urutan ini:
var
Product: TYamlNode;
begin
Product := Products.AddMapping;
Product.AddOrSetValue( ' sku ' , ' BL394D ' );
Product.AddOrSetValue( ' quantity ' , 4 );
// etc...
end ; Setelah Anda membuat dokumen, Anda dapat menyimpannya ke file atau streaming menggunakan metode Save , atau mengonversinya ke YAML menggunakan metode ToYaml :
var
Yaml: String;
begin
Yaml := Doc.ToYaml;
end ; Anda dapat melewati catatan TYamlOutputSettings opsional untuk menyesuaikan pemformatan YAML.
Ada lebih banyak ke neslib.yaml dari yang dijelaskan di atas. Untuk detail lebih lanjut Anda dapat melihat file sumber Neslib.Yaml.pas yang terdokumentasi dengan baik. Sampel penggunaan tambahan dapat ditemukan dalam uji unit, terutama di file Tests.Neslib.Yaml.Sample.pas .
Neslib.yaml dilisensikan di bawah lisensi BSD yang disederhanakan.
Lihat lisensi.txt untuk detailnya.
