Neslib.Yaml
1.0.0
Neslib.yaml เป็นห้องสมุดสำหรับการแยกวิเคราะห์และเปล่ง Yaml และสร้างเอกสารและสตรีม Yaml
neslib.yaml สร้างขึ้นที่ด้านบนของไลบรารี Libyaml และทำงานบน:
ในการติดตั้ง:
> git clone --recursive https://github.com/neslib/Neslib.Yamlห้องสมุดนี้ขึ้นอยู่กับที่เก็บ Neslib ซึ่งรวมอยู่ใน submodule กับที่เก็บนี้
สำหรับแพลตฟอร์มทั้งหมดยกเว้น 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 ชนิด:
การแมปคล้ายกับพจนานุกรม Delphi การทำแผนที่เป็นชุดของคู่คีย์/ค่า โน้ตรูทของเอกสารตัวอย่างด้านบนคือการแมป: มันแมปใบ invoice หนี้คีย์กับค่า 34843 และมีคู่คีย์/ค่าอีก 7 คู่ (จาก date ถึง comments ) ทั้งปุ่มและค่าอาจเป็นประเภท YAML ใด ๆ แม้ว่าคุณอาจต้องการยึดสายสำหรับคีย์
การแมปสามารถเขียนได้ในสัญกรณ์บล็อก (เช่นในตัวอย่าง) หรือสัญกรณ์การไหล (ใช้การจัดฟันแบบหยิก {} )
เมื่อใช้สัญลักษณ์บล็อก Yaml ใช้การเยื้องสำหรับการกำหนดขอบเขต อนุญาตเฉพาะช่องว่างสำหรับการเยื้อง ( ไม่ใช่ แท็บ) จำนวนช่องว่างไม่สำคัญตราบใดที่ค่าทั้งหมดในระดับเดียวกันใช้ช่องว่างในปริมาณเท่ากัน ในตัวอย่างค่าของ bill-to เป็นการแมปอื่น การทำแผนที่นี้มีการเยื้องเพื่อระบุว่ามันเป็นของ bill-to
ลำดับเป็นเหมือนอาร์เรย์หรือรายการ Delphi ลำดับขนาดเล็กสามารถเขียนได้โดยใช้โน้ตการไหล (ใช้วงเล็บเหลี่ยม [] ) ลำดับที่ใหญ่กว่าหรือซับซ้อนมักจะเขียนในสัญกรณ์บล็อกเช่นในตัวอย่าง: ค่าของคีย์ product คือลำดับของผลิตภัณฑ์สองรายการ (บาสเก็ตบอลและซุปเปอร์ห่วง) แต่ละรายการในลำดับเริ่มต้นด้วยเส้นประและพื้นที่
ในตัวอย่างนี้แต่ละผลิตภัณฑ์ในลำดับคือการแมปคู่คีย์/ค่า 4 คู่
โหนดทั้งหมดมีคุณสมบัติอย่างน้อยสองอย่าง: Tag และ Anchor แท็กใช้เพื่ออธิบายประเภทความหมายของโหนด แท็กไม่ได้เป็นเรื่องธรรมดาดังนั้นฉันจะข้ามพวกเขาในบทนำนี้ neslib.yaml ได้รับการสนับสนุนอย่างเต็มที่สำหรับแท็กแม้ว่า
สมอ สามารถใช้ทำเครื่องหมายโหนดในเอกสาร จากนั้นคุณสามารถอ้างอิงกลับไปที่โหนดนี้โดยใช้ นามแฝง
จุดยึด จะถูกนำหน้าด้วยแอมป์แซนด์ ( & ) ในตัวอย่างค่าของ bill-to มีจุดยึดที่เรียกว่า id001 (แอมป์แซนด์ไม่ได้เป็นส่วนหนึ่งของชื่อ) ต่อมาในเอกสาร ship-to ถึงกลับไปที่จุดยึดนี้โดยใช้ นามแฝง (เครื่องหมายดอกจันตามด้วยชื่อสมอเช่น *id001 ) นี่เป็นวิธีการบอกว่าที่อยู่จัดส่งนั้นเหมือนกับที่อยู่การเรียกเก็บเงิน โปรดทราบว่านามแฝง ไม่ได้ คัดลอกค่าอ้างอิง; มันหมายถึงโหนดอื่นจริงๆ
จุดยึด จะต้อง ปรากฏในเอกสารก่อนที่พวกเขาจะสามารถอ้างอิงได้ ชื่อของพวกเขา ไม่ จำเป็นต้องไม่ซ้ำกันภายในเอกสาร หากมีการประกาศจุดยึดใหม่ด้วยชื่อเดียวกันมันจะแทนที่สมอเก่า
สเกลาร์เป็นประเภทที่ง่ายที่สุด ทุกสิ่งที่ไม่ใช่การทำแผนที่ลำดับหรือนามแฝงเป็นสเกลาร์ ในทางปฏิบัติสเกลาร์เป็นเพียงสตริง คีย์ทั้งหมดในตัวอย่างข้างต้นคือ String Scalars แต่ค่าจำนวนมากก็เช่นกัน (เช่น 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 ที่ง่ายขึ้น
ดู License.txt สำหรับรายละเอียด
