// Manages state for parsing operations outside of a Parser.
//
// The state is immutable; all update operations return a new state.
//
// Since #x is covariant, any ParseState can convert to ParseState<any>, and
// ParseState<all> can convert to all other ParseState.
concrete ParseState<|#x> {
  // Consumes all input and returns the result.
  @category consumeAll<#y> (Parser<#y>,String) -> (ErrorOr<#y>)
}

// A self-contained parser operation.
//
// Since #x is covariant, any Parser can convert to Parser<any>, and Parser<all>
// can convert to all other Parser.
@value interface Parser<|#x> {
  run (ParseContext<any>) -> (ParseState<#x>)
}

// Parser context available when running a Parser.
//
// Since #x is covariant, any ParseContext can convert to ParseContext<any>, and
// ParseContext<all> can convert to all other ParseContext.
@value interface ParseContext<|#x> {
  // Continue computation.
  run<#y>       (Parser<#y>) -> (ParseContext<#y>)
  runAndGet<#y> (Parser<#y>) -> (ParseContext<any>,ErrorOr<#y>)
  getValue      ()           -> (ErrorOr<#x>)

  // End computation and pass on the next state.
  convertError   ()            -> (ParseState<all>)
  setValue<#y>   (ErrorOr<#y>) -> (ParseState<#y>)
  setBrokenInput (Formatted)   -> (ParseState<all>)
  toState        ()            -> (ParseState<#x>)

  // Context metadata.
  getPosition    () -> (String)
  atEof          () -> (Bool)
  hasAnyError    () -> (Bool)
  hasBrokenInput () -> (Bool)

  // Reading data.
  current () -> (Char)
  advance () -> (#self)
}