vxml_pipeline - v0.2.1

vxml_pipeline

Orchestrates VXML transformation pipelines and file-oriented renderers.

This module owns pipeline execution, monitors, renderer stages, feedback, renderer options, and command-line integration.

Types

Assembler

</> 
pub type Assembler(assembler_error) =
  fn(String) -> Result(
    #(List(io_lines.InputLine), Feedback),
    assembler_error,
  )

CLIError

</> 
pub type CLIError {
  CommandLineArgumentError(CommandLineError)
  DotLastCommandReadError(String)
  DotLastCommandDecodeError(String)
  DotLastCommandWriteError(String)
  MaintenanceError(String)
  ClientSideError(String)
}

Constructors 

  • CommandLineArgumentError(CommandLineError)
  • DotLastCommandReadError(String)
  • DotLastCommandDecodeError(String)
  • DotLastCommandWriteError(String)
  • MaintenanceError(String)
  • ClientSideError(String)

CommandLineError

opaque </> 
pub opaque type CommandLineError

Emitter

</> 
pub type Emitter(fragment_classifier, emitter_error) =
  fn(OutputFragment(fragment_classifier, vxml.VXML)) -> Result(
    #(
      OutputFragment(
        fragment_classifier,
        List(io_lines.OutputLine),
      ),
      Feedback,
    ),
    emitter_error,
  )

EmitterOrWriterError

</> 
pub type EmitterOrWriterError(emitter_error, writer_error) {
  EmitterError(emitter_error)
  WriterError(writer_error)
}

Constructors 

  • EmitterError(emitter_error)
  • WriterError(writer_error)

Feedback

</> 
pub type Feedback {
  NoFeedback
  SomeFeedback(List(FeedbackBlock))
}

Constructors

FeedbackBlock

</> 
pub type FeedbackBlock {
  FeedbackBlock(lines: List(String), margin: FeedbackMargin)
}

Constructors

FeedbackMargin

</> 
pub type FeedbackMargin {
  AtRunnerMargin
  Verbatim
}

Constructors 

  • AtRunnerMargin
  • Verbatim

Filterer

</> 
pub type Filterer(filterer_error) =
  fn(vxml.VXML) -> Result(#(vxml.VXML, Feedback), filterer_error)

GhostOfOutputFragment

</> 
pub type GhostOfOutputFragment(fragment_classifier) {
  GhostOfOutputFragment(
    classifier: fragment_classifier,
    path: String,
  )
}

Constructors 

  • GhostOfOutputFragment(
  classifier: fragment_classifier,
  path: String,
)

InSituDesugaringError

</> 
pub type InSituDesugaringError {
  InSituDesugaringError(
    desugarer: core.Desugarer,
    step_no: Int,
    message: String,
    blame: blame.Blame,
  )
}

Constructors

InSituDesugaringWarning

</> 
pub type InSituDesugaringWarning {
  InSituDesugaringWarning(
    desugarer: core.Desugarer,
    step_no: Int,
    message: String,
    blame: blame.Blame,
  )
}

Constructors

Monitor

opaque </> 
pub opaque type Monitor

MonitorFactory

opaque </> 
pub opaque type MonitorFactory

MonitorFailure

</> 
pub type MonitorFailure {
  MonitorFailure(
    monitor_name: String,
    step_no: Int,
    message: String,
  )
}

Constructors 

  • MonitorFailure(
  monitor_name: String,
  step_no: Int,
  message: String,
)

OutputFragment

</> 
pub type OutputFragment(fragment_classifier, payload) {
  OutputFragment(
    classifier: fragment_classifier,
    path: String,
    payload: payload,
  )
}

Constructors 

  • OutputFragment(
  classifier: fragment_classifier,
  path: String,
  payload: payload,
)

ParsedCLIArguments

</> 
pub type ParsedCLIArguments {
  ParsedCLIArguments(
    help: Bool,
    esoteric: Bool,
    track_help: Bool,
    renumber: Bool,
    generate: Bool,
    desugarers: Bool,
    desugarer_tests: option.Option(List(String)),
    input_dir: option.Option(String),
    output_dir: option.Option(String),
    only_paths: List(String),
    only_key_vals: List(#(String, String)),
    only_path_key_vals: List(#(String, String, String)),
    prettier: option.Option(PrettifierMode),
    tracking_monitor_factory: option.Option(MonitorFactory),
    dump_monitor_factory: option.Option(MonitorFactory),
    vxml_validation_monitor_factory: option.Option(MonitorFactory),
    monitor_interactive_mode: Bool,
    table: option.Option(Bool),
    table_columns: option.Option(
      #(
        option.Option(Int),
        option.Option(Int),
        option.Option(Int),
      ),
    ),
    times: option.Option(
      #(option.Option(Int), option.Option(Int)),
    ),
    verbose: option.Option(Bool),
    artifacts: option.Option(Bool),
    warnings: option.Option(Bool),
    dump_assembled: Bool,
    dump_parsed: Bool,
    dump_filtered: Bool,
    splitter_fragment_path_matches: option.Option(List(String)),
    emitter_fragment_path_matches: option.Option(List(String)),
    user_args: dict.Dict(String, List(String)),
  )
}

Constructors

Parser

</> 
pub type Parser(parser_error) =
  fn(List(io_lines.InputLine)) -> Result(
    #(vxml.VXML, Feedback),
    #(blame.Blame, parser_error),
  )

PipelineExecutionError

</> 
pub type PipelineExecutionError {
  PipelineUserExit(UserExit)
  PipelineDesugaringError(InSituDesugaringError)
  PipelineMonitorError(MonitorFailure)
}

Constructors

PipelineStepContext

</> 
pub type PipelineStepContext {
  PipelineStepContext(
    step_no: Int,
    previous_desugarer: option.Option(core.Desugarer),
    next_desugarer: option.Option(core.Desugarer),
  )
}

Constructors

PipelineUXOptions

</>

Terminal presentation and interaction settings for run_pipeline.

pub type PipelineUXOptions {
  PipelineUXOptions(
    monitor_interactive_mode: Bool,
    report_long_running_desugarers: Bool,
    feedback_margin: Int,
  )
}

Constructors 

  • PipelineUXOptions(
  monitor_interactive_mode: Bool,
  report_long_running_desugarers: Bool,
  feedback_margin: Int,
)

Prettifier

</> 
pub type Prettifier(fragment_classifier) =
  fn(
    String,
    GhostOfOutputFragment(fragment_classifier),
    option.Option(String),
  ) -> option.Option(PrettifierFeedback)

PrettifierFeedback

</> 
pub type PrettifierFeedback {
  PrettifierFeedback(
    warnings: List(String),
    errors: List(String),
  )
}

Constructors 

  • PrettifierFeedback(warnings: List(String), errors: List(String))

PrettifierMode

</> 
pub type PrettifierMode {
  PrettifierOff
  PrettifierOverwriteOutputDir
  PrettifierToBespokeDir(option.Option(String))
}

Constructors 

  • PrettifierOff
  • PrettifierOverwriteOutputDir
  • PrettifierToBespokeDir(option.Option(String))

Renderer

</>

Wires source ingress, parsing, filtering, desugaring, splitting, emitting, writing, and optional prettification.

pub type Renderer(assembler_error, parser_error, filterer_error, splitter_error, emitter_error, writer_error, fragment_classifier) {
  Renderer(
    assembler: fn(String) -> Result(
      #(List(io_lines.InputLine), Feedback),
      assembler_error,
    ),
    parser: fn(List(io_lines.InputLine)) -> Result(
      #(vxml.VXML, Feedback),
      #(blame.Blame, parser_error),
    ),
    filterer: fn(vxml.VXML) -> Result(
      #(vxml.VXML, Feedback),
      filterer_error,
    ),
    pipeline: List(core.Desugarer),
    splitter: fn(vxml.VXML) -> Result(
      #(
        List(OutputFragment(fragment_classifier, vxml.VXML)),
        Feedback,
      ),
      splitter_error,
    ),
    emitter: fn(OutputFragment(fragment_classifier, vxml.VXML)) -> Result(
      #(
        OutputFragment(
          fragment_classifier,
          List(io_lines.OutputLine),
        ),
        Feedback,
      ),
      emitter_error,
    ),
    writer: fn(
      String,
      OutputFragment(fragment_classifier, String),
    ) -> Result(
      #(GhostOfOutputFragment(fragment_classifier), Feedback),
      writer_error,
    ),
    prettifier: fn(
      String,
      GhostOfOutputFragment(fragment_classifier),
      option.Option(String),
    ) -> option.Option(PrettifierFeedback),
  )
}

Constructors

RendererError

</> 
pub type RendererError(assembler_error, parser_error, filterer_error, splitter_error, emitter_error, writer_error) {
  AssemblerError(assembler_error)
  ParserError(blame.Blame, parser_error)
  FiltererError(filterer_error)
  DesugarerNameNotFoundError(String)
  PipelineError(InSituDesugaringError)
  MonitorError(MonitorFailure)
  UserExitError(Int)
  SplitterError(splitter_error)
  EmittingOrWritingErrors(
    List(EmitterOrWriterError(emitter_error, writer_error)),
  )
}

Constructors 

  • AssemblerError(assembler_error)
  • ParserError(blame.Blame, parser_error)
  • FiltererError(filterer_error)
  • DesugarerNameNotFoundError(String)
  • PipelineError(InSituDesugaringError)
  • MonitorError(MonitorFailure)
  • UserExitError(Int)
  • SplitterError(splitter_error)
  • EmittingOrWritingErrors(
  List(EmitterOrWriterError(emitter_error, writer_error)),
)

RendererOptions

</> 
pub type RendererOptions(fragment_classifier) {
  RendererOptions(
    verbose: Bool,
    artifacts: Bool,
    steps_table: Bool,
    pipeline_table_default_desugarer_name_columns: Int,
    pipeline_table_default_param_columns: Int,
    pipeline_table_default_outside_columns: Int,
    profiling_table: Bool,
    pipeline_timing_table_default_desugarer_name_columns: Int,
    pipeline_timing_table_default_duration_columns: Int,
    monitor_interactive_mode: Bool,
    warnings: Bool,
    report_long_running_desugarers: Bool,
    only_paths: List(String),
    only_key_vals: List(#(String, String)),
    only_path_key_vals: List(#(String, String, String)),
    monitors: List(Monitor),
    monitor_factories: List(MonitorFactory),
    output_lines_table_default_comment_columns: Int,
    output_lines_table_default_blame_columns: Int,
    dump_assembled_lines: Bool,
    dump_parsed_vxml: Bool,
    dump_filtered_vxml: Bool,
    dump_splitter_fragments: fn(
      OutputFragment(fragment_classifier, vxml.VXML),
    ) -> Bool,
    dump_emitter_fragments: fn(
      OutputFragment(
        fragment_classifier,
        List(io_lines.OutputLine),
      ),
    ) -> Bool,
  )
}

Constructors 

  • RendererOptions(
  verbose: Bool,
  artifacts: Bool,
  steps_table: Bool,
  pipeline_table_default_desugarer_name_columns: Int,
  pipeline_table_default_param_columns: Int,
  pipeline_table_default_outside_columns: Int,
  profiling_table: Bool,
  pipeline_timing_table_default_desugarer_name_columns: Int,
  pipeline_timing_table_default_duration_columns: Int,
  monitor_interactive_mode: Bool,
  warnings: Bool,
  report_long_running_desugarers: Bool,
  only_paths: List(String),
  only_key_vals: List(#(String, String)),
  only_path_key_vals: List(#(String, String, String)),
  monitors: List(Monitor),
  monitor_factories: List(MonitorFactory),
  output_lines_table_default_comment_columns: Int,
  output_lines_table_default_blame_columns: Int,
  dump_assembled_lines: Bool,
  dump_parsed_vxml: Bool,
  dump_filtered_vxml: Bool,
  dump_splitter_fragments: fn(
    OutputFragment(fragment_classifier, vxml.VXML),
  ) -> Bool,
  dump_emitter_fragments: fn(
    OutputFragment(fragment_classifier, List(io_lines.OutputLine)),
  ) -> Bool,
)

RendererParameters

</> 
pub type RendererParameters {
  RendererParameters(
    input_dir: String,
    output_dir: String,
    prettifier_behavior: PrettifierMode,
  )
}

Constructors 

  • RendererParameters(
  input_dir: String,
  output_dir: String,
  prettifier_behavior: PrettifierMode,
)

Splitter

</> 
pub type Splitter(fragment_classifier, splitter_error) =
  fn(vxml.VXML) -> Result(
    #(
      List(OutputFragment(fragment_classifier, vxml.VXML)),
      Feedback,
    ),
    splitter_error,
  )

UserExit

</> 
pub type UserExit {
  UserExit(step_no: Int)
}

Constructors 

  • UserExit(step_no: Int)

Writer

</> 
pub type Writer(fragment_classifier, writer_error) =
  fn(String, OutputFragment(fragment_classifier, String)) -> Result(
    #(GhostOfOutputFragment(fragment_classifier), Feedback),
    writer_error,
  )

Values

advanced_cli_usage

</> 
pub fn advanced_cli_usage(header: String) -> Nil

amend_renderer_options_by_arguments

</> 
pub fn amend_renderer_options_by_arguments(
  options: RendererOptions(fragment_classifier),
  arguments: ParsedCLIArguments,
) -> RendererOptions(fragment_classifier)

amend_renderer_parameters_by_arguments

</> 
pub fn amend_renderer_parameters_by_arguments(
  parameters: RendererParameters,
  arguments: ParsedCLIArguments,
) -> RendererParameters

basic_cli_usage

</> 
pub fn basic_cli_usage(header: String) -> Nil

cli_error_message

</> 
pub fn cli_error_message(error: CLIError) -> String

default_file_assembler

</> 
pub fn default_file_assembler(
  path: String,
) -> Result(
  #(List(io_lines.InputLine), Feedback),
  simplifile.FileError,
)

default_filterer

</> 
pub fn default_filterer(
  vxml: vxml.VXML,
  options: RendererOptions(fragment_classifier),
  saving: List(String),
) -> Result(#(vxml.VXML, Feedback), String)

default_html_parser

</> 
pub const default_html_parser: fn(List(io_lines.InputLine)) -> Result(
  #(vxml.VXML, Feedback),
  #(blame.Blame, String),
)

default_prettier_prettifier

</> 
pub fn default_prettier_prettifier(
  output_dir: String,
  ghost: GhostOfOutputFragment(fragment_classifier),
  prettier_dir: option.Option(String),
) -> option.Option(PrettifierFeedback)

default_writer

</> 
pub fn default_writer(
  output_dir: String,
  fragment: OutputFragment(fragment_classifier, String),
) -> Result(
  #(GhostOfOutputFragment(fragment_classifier), Feedback),
  String,
)

default_xml_parser

</> 
pub fn default_xml_parser(
  lines: List(io_lines.InputLine),
) -> Result(#(vxml.VXML, Feedback), #(blame.Blame, String))

empty_prettifier

</> 
pub fn empty_prettifier(
  arg: String,
  arg: GhostOfOutputFragment(fragment_classifier),
  arg: option.Option(String),
) -> option.Option(PrettifierFeedback)

empty_text_node_monitor

</> 
pub fn empty_text_node_monitor() -> Monitor

Builds a monitor that rejects empty VXML text nodes.

Unlike vxml_validation_monitor, this monitor does not validate tags, attributes, or text-line contents.

handle_help_requests

</> 
pub fn handle_help_requests(
  arguments: ParsedCLIArguments,
  local_cli_usage: fn() -> String,
) -> Result(Bool, CLIError)

Print requested help sections.

Each requested help section is printed at most once. local_cli_usage is evaluated and appended only when --help is present.

handle_maintenance_requests

</> 
pub fn handle_maintenance_requests(
  arguments: ParsedCLIArguments,
  local_desugarer_tests: List(
    fn() -> testing.AssertiveTestCollection,
  ),
) -> Result(Bool, CLIError)

Run requested local-desugarer maintenance.

Each operation runs at most once. --desugarers requests blame renumbering, local-library generation, and all local desugarer tests.

help_message_margin

</> 
pub const help_message_margin: Int

new_monitor

</> 
pub fn new_monitor(
  name: String,
  state: state,
  update: fn(vxml.VXML, state, PipelineStepContext) -> Result(
    #(state, Feedback),
    String,
  ),
) -> Monitor

process_command_line_arguments

</> 
pub fn process_command_line_arguments(
  arguments: List(String),
  user_keys: List(String),
) -> Result(ParsedCLIArguments, CLIError)

read_from_dot_last_command

</> 
pub fn read_from_dot_last_command(
  arguments: List(String),
) -> Result(List(String), CLIError)

Replace the lone --last-command option with the arguments saved in .last-command. All other argument lists are returned unchanged.

run_pipeline

</> 
pub fn run_pipeline(
  vxml: vxml.VXML,
  pipeline: List(core.Desugarer),
  monitors: List(Monitor),
  ux_options: PipelineUXOptions,
) -> Result(
  #(
    vxml.VXML,
    List(InSituDesugaringWarning),
    List(duration.Duration),
  ),
  PipelineExecutionError,
)

run_renderer

</> 
pub fn run_renderer(
  renderer: Renderer(
    assembler_error,
    parser_error,
    filterer_error,
    splitter_error,
    emitter_error,
    writer_error,
    fragment_classifier,
  ),
  parameters: RendererParameters,
  options: RendererOptions(fragment_classifier),
) -> Result(
  List(String),
  RendererError(
    assembler_error,
    parser_error,
    filterer_error,
    splitter_error,
    emitter_error,
    writer_error,
  ),
)

stub_html_emitter

</> 
pub fn stub_html_emitter(
  fragment: OutputFragment(fragment_classifier, vxml.VXML),
) -> Result(
  #(
    OutputFragment(fragment_classifier, List(io_lines.OutputLine)),
    Feedback,
  ),
  emitter_error,
)

stub_jsx_emitter

</> 
pub fn stub_jsx_emitter(
  fragment: OutputFragment(fragment_classifier, vxml.VXML),
) -> Result(
  #(
    OutputFragment(fragment_classifier, List(io_lines.OutputLine)),
    Feedback,
  ),
  emitter_error,
)

stub_splitter

</> 
pub fn stub_splitter(
  suffix: String,
) -> fn(vxml.VXML) -> Result(
  #(List(OutputFragment(Nil, vxml.VXML)), Feedback),
  Nil,
)

emits 1 fragment whose ‘path’ is the tag of the VXML root concatenated with a provided suffix, e.g., “<> Book” -> “Book.html”

track_cli_usage

</> 
pub fn track_cli_usage(header: String) -> Nil

vanilla_options

</> 
pub fn vanilla_options() -> RendererOptions(fragment_classifier)

vxml_validation_monitor

</> 
pub fn vxml_validation_monitor(
  warn_about_leading_attribute_whitespace: Bool,
) -> Monitor

Builds a monitor that validates VXML before and after every pipeline step.

Invalid VXML stops the pipeline. When warn_about_leading_attribute_whitespace is True, the monitor also emits feedback for attribute values with leading whitespace. Leading whitespace is valid VXML and is not otherwise rejected.

write_to_dot_last_command

</> 
pub fn write_to_dot_last_command(
  arguments: List(String),
) -> Result(Nil, CLIError)

Overwrite .last-command with an unambiguous encoding of arguments.

✨ Search Document