A simple YAML parsing and stringifying library for MoonBit, support a simplified YAML subset which can be convert to JSON.

Author

Version

0.0.7

License

MIT

Repository

github.com/moonbit-community/yaml.mbt

Last updated

15 hours ago

Downloads

76K

#YAML

A simple YAML parsing and stringifying library for MoonBit, support a simplified YAML subset which can be convert to JSON.

This library is ported from yaml-rust2.

#Usage

#Basic Example

///|
test {
  let source =
    #|%YAML 1.2
    #|---
    #|YAML: YAML Ain't Markup Language™
    #|
    #|What It Is:
    #|  YAML is a human-friendly data serialization
    #|  language for all programming languages.
    #|
    #|YAML Resources:
    #|  YAML Specifications:
    #|  - YAML 1.2:
    #|    - Revision 1.2.2      # Oct 1, 2021 *New*
    #|    - Revision 1.2.1      # Oct 1, 2009
    #|    - Revision 1.2.0      # Jul 21, 2009
    #|  - YAML 1.1
    #|  - YAML 1.0
  json_inspect(@yaml.Yaml::load_from_string(source), content=[
    {
      "YAML": "YAML Ain't Markup Language™",
      "What It Is": "YAML is a human-friendly data serialization language for all programming languages.",
      "YAML Resources": {
        "YAML Specifications": [
          { "YAML 1.2": ["Revision 1.2.2", "Revision 1.2.1", "Revision 1.2.0"] },
          "YAML 1.1",
          "YAML 1.0",
        ],
      },
    },
  ])
}

#YAML

A simple YAML parsing and stringifying library for MoonBit, support a simplified YAML subset which can be convert to JSON.

This library is ported from yaml-rust2.

#Usage

#Basic Example

///|
test {
  let source =
    #|%YAML 1.2
    #|---
    #|YAML: YAML Ain't Markup Language™
    #|
    #|What It Is:
    #|  YAML is a human-friendly data serialization
    #|  language for all programming languages.
    #|
    #|YAML Resources:
    #|  YAML Specifications:
    #|  - YAML 1.2:
    #|    - Revision 1.2.2      # Oct 1, 2021 *New*
    #|    - Revision 1.2.1      # Oct 1, 2009
    #|    - Revision 1.2.0      # Jul 21, 2009
    #|  - YAML 1.1
    #|  - YAML 1.0
  json_inspect(@yaml.Yaml::load_from_string(source), content=[
    {
      "YAML": "YAML Ain't Markup Language™",
      "What It Is": "YAML is a human-friendly data serialization language for all programming languages.",
      "YAML Resources": {
        "YAML Specifications": [
          { "YAML 1.2": ["Revision 1.2.2", "Revision 1.2.1", "Revision 1.2.0"] },
          "YAML 1.1",
          "YAML 1.0",
        ],
      },
    },
  ])
}

EventReceiver

source

pub(open) trait EventReceiver {
  fn on_event(Self, event : Event) -> Unit
}

Trait to be implemented in order to use the low-level parsing API.

The low-level parsing API is event-based (a push parser), calling EventReceiver::on_event for each YAML Event that occurs. The EventReceiver trait only receives events. In order to receive both events and their location in the source, use MarkedEventReceiver. Parser::load takes a MarkedEventReceiver; MoonBit has no blanket implementations, so to use an EventReceiver there, wrap it in a type whose MarkedEventReceiver::on_event forwards the event and ignores the marker.

Event hierarchy

The event stream starts with an Event::StreamStart event followed by an Event::DocumentStart event. If the YAML document starts with a mapping (an object), an Event::MappingStart event is emitted. If it starts with a sequence (an array), an Event::SequenceStart event is emitted. Otherwise, an Event::Scalar event is emitted.

In a mapping, key-values are sent as consecutive events. The first event after an Event::MappingStart will be the key, and following its value. If the mapping contains no sub-mapping or sub-sequence, then even events (starting from 0) will always be keys and odd ones will always be values. The mapping ends when an Event::MappingEnd event is received.

In a sequence, values are sent consecutively until the Event::SequenceEnd event.

If a value is a sub-mapping or a sub-sequence, an Event::MappingStart or Event::SequenceStart event will be sent respectively. Following events until the associated Event::MappingStart or Event::SequenceEnd (beware of nested mappings or sequences) will be part of the value and not another key-value pair or element in the sequence.

For instance, the following yaml:

a: b
c:
  d: e
f:
  - g
  - h

will emit (indented and commented for lisibility):

StreamStart, DocumentStart, MappingStart,
  Scalar("a", ..), Scalar("b", ..)
  Scalar("c", ..), MappingStart, Scalar("d", ..), Scalar("e", ..), MappingEnd,
  Scalar("f", ..), SequenceStart, Scalar("g", ..), Scalar("h", ..), SequenceEnd,
MappingEnd, DocumentEnd, StreamEnd

MarkedEventReceiver

source

pub(open) trait MarkedEventReceiver {
  fn on_event(Self, event : Event, _mark : Marker) -> Unit
}

YamlError

source

pub suberror YamlError {
  YamlError(mark~ : Marker, info~ : String)
} derive(@moonbitlang/core/debug.Debug
Debug)

Event

source

pub enum Event {
  StreamStart
  StreamEnd
  DocumentStart
  DocumentEnd
  Alias(id~ : Int)
  Scalar(value~ : String, style~ : TScalarStyle, id~ : Int, tag~ : Tag?)
  SequenceStart(id~ : Int, tag~ : Tag?)
  SequenceEnd
  MappingStart(id~ : Int, tag~ : Tag?)
  MappingEnd
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Marker

source

pub struct Marker {
  index : Int
  line : Int
  col : Int
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Parser

source

type Parser

Parser::keep_tags

source

fn Parser::keep_tags(self : Parser, value : Bool) -> Unit

Whether to keep tags across multiple documents when parsing.

This behavior is non-standard as per the YAML specification but can be encountered in the wild. This boolean allows enabling this non-standard extension. This would result in the parser accepting input from test QLJ7 of the yaml-test-suite:

%TAG !prefix! tag:example.com,2011:
--- !prefix!A
a: b
--- !prefix!B
c: d
--- !prefix!C
e: f

With keep_tags set to false, the above YAML is rejected. As per the specification, tags only apply to the document immediately following them. This would error on !prefix!B.

With keep_tags set to true, the above YAML is accepted by the parser.

Parser::load

source

fn[R : MarkedEventReceiver] Parser::load(self : Parser, recv : R, multi : Bool) -> Unit raise YamlError

Load the YAML from the stream in self, pushing events into recv.

The contents of the stream are parsed and the corresponding events are sent into the recveiver. For detailed explanations about how events work, see EventReceiver.

If multi is set to true, the parser will allow parsing of multiple YAML documents inside the stream.

The receiver must implement MarkedEventReceiver. An EventReceiver can be used by wrapping it in a type that implements MarkedEventReceiver and forwards each event, ignoring its marker.

Errors

Returns YamlError when loading fails.

Parser::new

source

fn Parser::new(str : StringView) -> Parser

TScalarStyle

source

pub enum TScalarStyle {
  Plain
  SingleQuoted
  DoubleQuoted
  Literal
  Folded
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Tag

source

pub struct Tag {
  handle : String
  suffix : String
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Yaml

source

pub(all) enum Yaml {
  Real(Double, repr~ : String)
  Integer(Int64)
  String(String)
  Boolean(Bool)
  Array(Array[Yaml])
  Map(Map[String, Yaml])
  Null
  BadValue
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

YAML data structure representation

impl ToJson for Yaml

Yaml::dump

source

fn Yaml::dump(self : Yaml) -> String

Convenience helper to dump a Yaml value into a string using default settings.

Yaml::load_from_parser

source

fn Yaml::load_from_parser(parser : Parser) -> Array[Yaml] raise YamlError

Yaml::load_from_string

source

fn Yaml::load_from_string(source : StringView) -> Array[Yaml] raise YamlError

YamlEmitter

source

type YamlEmitter

The YAML serializer.

This is a simplified emitter that matches the parser features supported by this package.

Example

let input = "a: b\nc: d"
let docs = Yaml::load_from_string(input)
let emitter = YamlEmitter::new()
emitter.dump(docs[0])
let output = emitter.to_string()
// output == "---\na: b\nc: d"

YamlEmitter::compact

source

fn YamlEmitter::compact(self : YamlEmitter, compact : Bool) -> Unit

Set "compact inline notation" on or off for block sequences and mappings.

In this form, blocks cannot have any properties (such as anchors or tags), which should be OK, because this emitter doesn't emit those anyways.

YamlEmitter::dump

source

fn YamlEmitter::dump(self : YamlEmitter, doc : Yaml) -> Unit

Dump a YAML document into the internal buffer.

YamlEmitter::multiline_strings

source

fn YamlEmitter::multiline_strings(self : YamlEmitter, multiline_strings : Bool) -> Unit

Render strings containing multiple lines in literal block style.

Example

let input = "{foo: \"bar!\\nbar!\", baz: 42}"
let parsed = Yaml::load_from_string(input)
let emitter = YamlEmitter::new()
emitter.multiline_strings(true)
emitter.dump(parsed[0])
let output = emitter.to_string()
// output is:
// ---
// foo: |-
//   bar!
//   bar!
// baz: 42

YamlEmitter::new

source

fn YamlEmitter::new(writer? : StringBuilder) -> YamlEmitter

Create a new emitter serializing into writer.

YamlEmitter::to_string

source

fn YamlEmitter::to_string(self : YamlEmitter) -> String

Get the current emitted output as a string.

Source Files

Site source Report issue Packages Build queue Skills Statistics

yaml

#YAML

#Usage

#Basic Example

#YAML

#Usage

#Basic Example

#EventReceiver

Event hierarchy

#MarkedEventReceiver

#YamlError

#Event

#Marker

#Parser

#Parser::keep_tags

#Parser::load

Errors

#Parser::new

#TScalarStyle

#Tag

#Yaml

#Yaml::dump

#Yaml::load_from_parser

#Yaml::load_from_string

#YamlEmitter

Example

#YamlEmitter::compact

#YamlEmitter::dump

#YamlEmitter::multiline_strings

Example

#YamlEmitter::new

#YamlEmitter::to_string

Source Files

EventReceiver

MarkedEventReceiver

YamlError

Event

Marker

Parser

Parser::keep_tags

Parser::load

Parser::new

TScalarStyle

Tag

Yaml

Yaml::dump

Yaml::load_from_parser

Yaml::load_from_string

YamlEmitter

YamlEmitter::compact

YamlEmitter::dump

YamlEmitter::multiline_strings

YamlEmitter::new

YamlEmitter::to_string