Qwiratry β€” WalkCursor

Overview

Walkable position/movement contract (WalkCursor): a first-class position and movement API in the same conceptual slot as Iterator / Supply.

A WalkCursor answers where a walk is and how it can move. It is distinct from pull result streams (Qwiratry::QueryIterator) and from tree shape adaptors (Qwiratry::Tree::Navigator::Base). Qwiratry’s first specialization is Qwiratry::QueryCursor. Design notes live in docs/rakudoc/Developing/Cursor-Proposal.md.

Note: Raku already binds CORE::Cursor to Match, so this contract cannot ship as a bare Cursor role/module. WalkCursor is the short name until/unless core frees that symbol. See Cursor-Proposal.md.

This module exports:

  • Sector β€” oriented half-lines from the current node (child, following, …)

  • Axis β€” a matched pair of opposite Sectors (one bidirectional line)

  • WalkCursor β€” the position / fetch-* / move-* role

  • direction-args β€” helper to build optional :axis / :sector captures

Sector and Axis

Sector names XPath/Qwiratry navigation half-lines (child, parent, following, …). Prefer Sector::… qualification so barewords do not collide with query-slang infixes.

Axis pairs opposite sectors for signed motion:

Axis Forward (+) Backward (βˆ’)
preceding-following following preceding
preceding-following-sibling following-sibling preceding-sibling
ancestor-descendant descendant ancestor

Sector::child / Sector::parent do not get their own Axis; they are one-step moves on Axis.ancestor-descendant (fetch/move-relative(Β±1)).

An advertised Axis is always bidirectional. One-way-only backends advertise Sectors instead of an Axis.

Fetch vs Move

PostgreSQL-class scroll comes in two families:

  • fetch-* β€” reposition and return the item at the new position (Mu), or IterationEnd when the step is empty. Count-taking forms are multis on Int (single item) and Range (Seq over the span; * / Inf = until exhausted; open and closed ranges both allowed).

  • move-* β€” same repositioning algebra, return an Int step count (how many positions advanced; 0 if none). Count-taking move-* take Int only.

Passing both :axis and :sector is an error. With :sector, steps must be $n >= 0 (0 = self). With :axis / default axis, positive steps use the forward sector and negative steps the backward sector.

Implementing

Compose WalkCursor and implement the stubbed (...) methods at minimum: current, fetch-first, fetch-last, fetch-absolute, fetch-relative, fetch-backward(Range), and clone-position. Default bodies already provide fetch-next / fetch-prior / fetch-forward(Int) and the move-* family in terms of those.

Example

use WalkCursor;

class PointCursor does WalkCursor {
    has @.items;
    has Int $.index is rw = 0;

    method current(--> Mu) { @!items[$!index] }

    method fetch-relative(Int $n, Axis :$axis, Sector :$sector --> Mu) {
        my $i = $!index + $n;
        return IterationEnd unless 0 <= $i < @!items.elems;
        $!index = $i;
        self.current
    }
    # ... other required multis / first / last / clone-position ...
}

Class Axis

Matched opposite pair of Sectors β€” one bidirectional navigation line.

Type methods preceding-following, preceding-following-sibling, and ancestor-descendant return the standard Axes.

Sub direction-args

Build a Hash of defined :axis / :sector pairs for |-flattening into scroll method calls. Omits undefined direction arguments.

Role WalkCursor

Position and PostgreSQL-class fetch-* / move-* movement.

Attributes

  • $.default-axis β€” Axis used when neither :axis nor :sector is passed (default Axis.preceding-following).

Capability probing

cursor-capabilities() returns an Associative (same pattern as Walker capabilities). Typical keys: axes, sectors, absolute. first / last are always supported.

Required stubs

Methods whose bodies are ... must be supplied by the composing class.

current()

method current(--> Mu)
The node or row at the Cursor’s position.

cursor-capabilities()

method cursor-capabilities(--> Associative)
Structured capability metadata for this Cursor implementation.

Scroll methods

PostgreSQL-class repositioning. C<fetch-*> return the item at the new
	position; C<move-*> return how many positions advanced. See also the module
	overview I<Fetch vs Move>.

Shared parameters

These named arguments appear on every scroll method (except where noted).
	Pass at most one of C<:axis> or C<:sector>; both together is an error.
	When neither is passed, C<$.default-axis> is used.
  • :$axis

An L<Axis> selecting the bidirectional line. Positive steps use
	 C<$axis.forward>; negative steps use C<$axis.backward>.
  • :$sector

A single L<Sector> half-line. Steps must be C<< $n >= 0 >> (C<0> means
	 self / no move along that sector).
  • $n

Count or span for absolute / relative / forward / backward forms:
  • Int β€” one step of that magnitude (sign selects direction on an Axis; must be non-negative with :sector).

  • Range β€” fetch-* only; yield a Seq over the span. Open and closed ranges are allowed; * / Inf means until exhausted. move-* do not take Range.

fetch-next / fetch-prior / fetch-previous

method fetch-next(Axis :$axis, Sector :$sector --> Mu)
method fetch-prior(Axis :$axis, Sector :$sector --> Mu)
method fetch-previous(|c)   # alias of fetch-prior
One step forward or backward along the chosen line. Implemented as
	C<fetch-relative(+1)> / C<fetch-relative(-1)>.

fetch-first / fetch-last

method fetch-first(Axis :$axis, Sector :$sector --> Mu)
method fetch-last(Axis :$axis, Sector :$sector --> Mu)
Jump to the first or last position on the chosen line. Required stubs for
	composing classes.

fetch-absolute / fetch-relative

multi method fetch-absolute(Int $n, Axis :$axis, Sector :$sector --> Mu)
multi method fetch-absolute(Range $n, Axis :$axis, Sector :$sector --> Seq)
multi method fetch-relative(Int $n, Axis :$axis, Sector :$sector --> Mu)
multi method fetch-relative(Range $n, Axis :$axis, Sector :$sector --> Seq)
  • $n

Absolute: 1-based (or implementation-defined) index on the line, or a
	 C<Range> of such indices. Relative: signed step count from C<current>, or
	 a C<Range> of relative steps.
Required stubs for composing classes.

fetch-forward / fetch-backward

multi method fetch-forward(Int $n = 1, Axis :$axis, Sector :$sector --> Mu)
multi method fetch-forward(Range $n, Axis :$axis, Sector :$sector --> Seq)
multi method fetch-backward(Int $n = 1, Axis :$axis, Sector :$sector --> Mu)
multi method fetch-backward(Range $n, Axis :$axis, Sector :$sector --> Seq)
  • $n

Defaults to C<1> for the C<Int> candidates. Forward is
	 C<fetch-relative($n)>; backward is C<fetch-relative(-$n)> for C<Int>, with
	 a Range multi stubbed for composing classes.

move-*

method move-next(Axis :$axis, Sector :$sector --> Int)
method move-prior(Axis :$axis, Sector :$sector --> Int)
method move-previous(|c)   # alias of move-prior
method move-first(Axis :$axis, Sector :$sector --> Int)
method move-last(Axis :$axis, Sector :$sector --> Int)
method move-absolute(Int $n, Axis :$axis, Sector :$sector --> Int)
method move-relative(Int $n, Axis :$axis, Sector :$sector --> Int)
method move-forward(Int $n = 1, Axis :$axis, Sector :$sector --> Int)
method move-backward(Int $n = 1, Axis :$axis, Sector :$sector --> Int)
Same repositioning as the matching C<fetch-*>, but return an C<Int> step
	count instead of the item. Count-taking forms take C<Int> only (no
	C<Range>). Default bodies wrap the corresponding C<fetch-*>.
  • $n

As for C<fetch-absolute> / C<fetch-relative> / C<fetch-forward> /
	 C<fetch-backward>, restricted to C<Int>. C<move-forward> /
	 C<move-backward> default C<$n> to C<1>.

Return Value

  • fetch-* with Int (or no count)

The item at the new position (C<Mu>), or C<IterationEnd> when the step is
	 empty. Unsupported operations should throw (Qwiratry uses
	 C<X::Qwiratry::Cursor::*>).
  • fetch-* with Range

A C<Seq> of items along the span.
  • move-*

An C<Int> count of positions advanced (C<0> if none).

clone-position()

method clone-position(--> ::?CLASS)
Return a new WalkCursor with the same position-relevant state and independent
	mutable position (for backtracking). Must not share live position or
	walk-local Navigator caches with the original.

Qwiratry v0.11.0

Declarative query and data-walking architecture for Raku, with transformers, molds, walkers, I/O pipelines, and aggregate functions.

Authors

  • Tim Nelson

License

Dependencies

SlangifyImplementation::Loader:ver<0.0.9+>Glob::Grammar

Test Dependencies

Provides

  • Qwiratry
  • Qwiratry::Aggregate::AggSub
  • Qwiratry::Aggregate::AggSub::Compiler
  • Qwiratry::Aggregate::Avg
  • Qwiratry::Aggregate::BodyRewrite
  • Qwiratry::Aggregate::Count
  • Qwiratry::Aggregate::DenseRank
  • Qwiratry::Aggregate::Driver
  • Qwiratry::Aggregate::Rank
  • Qwiratry::Aggregate::Sum
  • Qwiratry::AggregateFunction
  • Qwiratry::Context
  • Qwiratry::DatabaseStorage
  • Qwiratry::DatabaseStorage::CSVdemo
  • Qwiratry::DatabaseStorage::Location
  • Qwiratry::DatabaseStorage::Location::Tree
  • Qwiratry::DatabaseStorage::Memory
  • Qwiratry::FieldMode
  • Qwiratry::Format
  • Qwiratry::Format::Base
  • Qwiratry::Format::CSVdemo
  • Qwiratry::Format::HalfHuman
  • Qwiratry::Format::JSONdemo
  • Qwiratry::Format::NDJSONdemo
  • Qwiratry::Format::Textish::RenderWalkable
  • Qwiratry::Implementation::Loader
  • Qwiratry::Location
  • Qwiratry::Location::Base
  • Qwiratry::Location::File
  • Qwiratry::Mold
  • Qwiratry::Mold::Compiler
  • Qwiratry::Mold::Registry
  • Qwiratry::Mold::Slang
  • Qwiratry::MovingFrameAggregateFunction
  • Qwiratry::Operator::Capability
  • Qwiratry::Operator::IO
  • Qwiratry::Operator::MapReduce
  • Qwiratry::Operator::Navigation
  • Qwiratry::Operator::Set
  • Qwiratry::Query::Evaluator::Eager
  • Qwiratry::Query::Evaluator::Filter
  • Qwiratry::Query::Evaluator::Join
  • Qwiratry::Query::Evaluator::Lazy
  • Qwiratry::Query::Evaluator::MapReduce
  • Qwiratry::Query::Evaluator::Navigation
  • Qwiratry::Query::Evaluator::Relational
  • Qwiratry::Query::Evaluator::Row
  • Qwiratry::Query::Evaluator::Set
  • Qwiratry::Query::Evaluator::Union
  • Qwiratry::Query::Extract
  • Qwiratry::Query::NamedJoins
  • Qwiratry::Query::RelationCommon
  • Qwiratry::Query::Runtime
  • Qwiratry::Query::Selector
  • Qwiratry::Query::Slang
  • Qwiratry::Query::Slang::Ops
  • Qwiratry::Query::Slang::Topic
  • Qwiratry::Query::Specificity
  • Qwiratry::Query::Topic
  • Qwiratry::QueryCursor
  • Qwiratry::QueryIterator
  • Qwiratry::QueryMatch
  • Qwiratry::Setup
  • Qwiratry::Singleton
  • Qwiratry::Strategy
  • Qwiratry::Strategy::ControlSignal
  • Qwiratry::Strategy::FinishResult
  • Qwiratry::Strategy::RewriteSpec
  • Qwiratry::Strategy::Traversal
  • Qwiratry::Suggest
  • Qwiratry::TaOP
  • Qwiratry::Table
  • Qwiratry::Table::Schema
  • Qwiratry::Transformer
  • Qwiratry::Transformer::Copy
  • Qwiratry::Transformer::TreeRewrite
  • Qwiratry::Tree::Navigator
  • Qwiratry::Tree::Navigator::Base
  • Qwiratry::Tree::Navigator::Filesystem
  • Qwiratry::Tree::Navigator::Match
  • Qwiratry::Tree::Navigator::RakuAST
  • Qwiratry::Tree::Replace
  • Qwiratry::Walker
  • Qwiratry::Walker::Capabilities
  • Qwiratry::Walker::Factory
  • Qwiratry::Walker::Implementation::Table
  • Qwiratry::Walker::Implementation::Tree
  • Qwiratry::Walker::Implementation::TreeWithPath
  • Qwiratry::Walker::Master
  • Qwiratry::Walker::Providing
  • TypedIterator
  • WalkCursor
  • X::Qwiratry

The Camelia image is copyright 2009 by Larry Wall. "Raku" is a trademark of the Yet Another Society. All rights reserved.

Built with Podlite β€” the markup and publishing tools behind this site.