///|
pub enum Event {
  /// Event generated at the very beginning of parsing.
  StreamStart
  /// Last event that will be generated by the parser. Signals EOF.
  StreamEnd
  /// The YAML start document directive (`---`).
  DocumentStart
  /// The YAML end document directive (`...`).
  DocumentEnd
  /// A YAML Alias.
  /// - id : The anchor ID the alias refers to.
  Alias(id~ : Int)
  /// Value, style, anchor id, tag
  Scalar(value~ : String, style~ : TScalarStyle, id~ : Int, tag~ : Tag?)
  /// The start of a YAML sequence (array).
  /// - id : The anchor ID of the start of the sequence.
  /// - tag : An optional tag
  SequenceStart(id~ : Int, tag~ : Tag?)
  /// The end of a YAML sequence (array).
  SequenceEnd
  /// The start of a YAML mapping (object, hash).
  /// - id : The anchor ID of the start of the mapping.
  /// - tag : An optional tag
  MappingStart(id~ : Int, tag~ : Tag?)
  /// The end of a YAML mapping (object, hash).
  MappingEnd
} derive(Eq, Debug)

///|
fn Event::empty_scalar() -> Event {
  Event::Scalar(value="", style=TScalarStyle::Plain, id=0, tag=None)
}

///|
fn Event::empty_scalar_with_anchor(anchor : Int, tag : Tag?) -> Event {
  Event::Scalar(value="", style=TScalarStyle::Plain, id=anchor, tag~)
}

///|
/// 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`. Note that `EventReceiver`s implement
/// `MarkedEventReceiver` automatically.
///
/// # 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:
/// ```yaml
/// a: b
/// c:
///   d: e
/// f:
///   - g
///   - h
/// ```
/// will emit (indented and commented for lisibility):
/// ```text
/// 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
/// ```
pub trait EventReceiver {
  /// Handler called for each YAML event that is emitted by the parser.
  fn on_event(Self, event : Event) -> Unit
}

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