Overview

Abstract base classes for format implementations.

Qwiratry::Format discovers concrete format modules dynamically and verifies that each operation class inherits from the matching walkable base class here. A format module normally provides ::Parse and/or ::Render classes under its format namespace, for example Qwiratry::Format::MyFormat::Parse, which inherit ParseWalkable / RenderWalkable.

Formats whose parser emits a custom tree model should also provide a Qwiratry::Tree::Navigator::* class that does Qwiratry::Tree::Navigator::Base.

These classes are contracts rather than useful implementations. The default methods throw so an incomplete plugin fails at the first attempted parse or render instead of silently returning an invalid value.

Optional pull roles add chunk-oriented capabilities alongside the walkable whole-value path. "Streaming" as a capability means a pull (or, later, push) path is available.

Methods

parse-walkable(Str $input-string)

method parse-walkable(Str $input-string --> Mu)

Parameters

• $input-string

The external text to parse into Qwiratry data.

Parses a complete external text value into structured Raku data.

Concrete parsers override this method. Callers normally reach it through Qwiratry::Operator::IO::ParseOperator or Qwiratry::Format.make(:type<Parse>, :format(...)).

render-walkable(Mu $data, Associative :%options)

method render-walkable(Mu $data, Associative :%options --> Str)

Parameters

• $data

The input data, root value, or rendered value handled by this operation.

• %options

Named format options, such as rendering preferences.

Renders structured Raku data to a complete external text value.

Concrete renderers override this method and may interpret %options in a format-specific way. Non-streaming render paths may normalize lazy query results before calling this method; pull renderers that also do RenderPull receive data without that forced materialization.

Optional capability for parsers that accept a pull stream of text chunks.

When a format parser does this role, Qwiratry::Operator::IO::ParseOperator prefers parse-pull whenever its input is already a text-chunk Iterator. Otherwise the operator falls back to joining chunks (when needed) and calling parse-walkable.

parse-pull(Iterator:D $chunks, *%options)

method parse-pull(Iterator:D $chunks, *%options --> Mu)

Parameters

• $chunks

Pull iterator of C<Str> text chunks.

• %options

Optional format-specific named arguments.

Parses a stream of text chunks into structured data.

May return a single value or a lazy Seq/Iterator of top-level values. Concrete pull parsers override this method.

Optional capability for renderers that emit a pull stream of text chunks.

When a format renderer does this role, Qwiratry::Operator::IO::RenderOperator calls render-pull and does not force upstream lazy sequences into a list.

render-pull(Mu $data, Associative :%options)

method render-pull(Mu $data, Associative :%options --> Iterator:D)

Parameters

• $data

Structured data to render, possibly still lazy.

• %options

Named format options, such as rendering preferences.

Renders structured data as a pull iterator of Str chunks.

Concrete pull renderers override this method.