/ 
Chorus_2.0.1
/ Chorus::Collection::List

NAME

Chorus::Collection::List - Ordered, doubly-linked list of Chorus::Frame objects

VERSION

This module is part of Chorus::Engine 1.05.

SYNOPSIS

use Chorus::Frame;
use Chorus::Collection::List qw($LIST);

# Create a list from existing Frames
my $seq = Chorus::Frame->new(_ISA => $LIST);
$seq->build($f1, $f2, $f3);

# Traverse
printf "length : %d\n", $seq->length;       # 3
my $first = $seq->first_item;               # $f1
my $last  = $seq->last_item;                # $f3

# Append / prepend
$seq->push_items($f4);                      # → f1 f2 f3 f4
$seq->unshift_items($f0);                   # → f0 f1 f2 f3 f4

# Doubly-linked navigation (prev / succ slots)
$f2->connect_left($f1);                     # $f2->prev = $f1, $f1->succ = $f2
$f2->connect_right($f3);                    # $f2->succ = $f3, $f3->prev = $f2

# Predicates
if ($seq->HAS('categorie')) { ... }         # first item with truthy slot
$seq->STARTS_WITH('head') or die;
$seq->ENDS_WITH('tail')   or die;

# Merge two lists into one (source lists are emptied)
$seq->merge_right($other);

# Custom container name (default: _CONTAINER)
$seq->set_container_name('_PHRASE');

DESCRIPTION

Chorus::Collection::List provides $LIST, a Chorus::Frame prototype for building ordered, doubly-linked sequences of Frames.

Any Frame that inherits from $LIST (via _ISA => $LIST) becomes a list object. Each item added to the list automatically receives a back-reference slot (_CONTAINER by default, or the name set with "set_container_name") pointing to the list it belongs to.

Items can also be doubly linked to their neighbours with explicit prev and succ slots using "connect_left" and "connect_right".

EXPORTS

Nothing is exported by default. The following symbol is available on request:

use Chorus::Collection::List qw($LIST);
$LIST

The Frame prototype. Use _ISA => $LIST to create list instances.

METHODS

All methods are slots defined on the $LIST prototype and are therefore called as methods on any Frame that inherits from $LIST.

build

$seq->build( @frames )

Initialises the list with the given Frames. Sets _ITEMS to \@frames and writes the container back-reference slot (see "set_container_name") on every item. Returns $self.

$seq->build($f1, $f2, $f3);

push_items

$seq->push_items( @frames )

Appends one or more Frames to the right end of the list. Sets the container back-reference on each new item. Returns $self.

$seq->push_items($f4, $f5);

unshift_items

$seq->unshift_items( @frames )

Prepends one or more Frames to the left end of the list. Sets the container back-reference on each new item. Returns $self.

$seq->unshift_items($f0);

first_item

Returns the first item (leftmost) in the list, or undef if the list is empty.

last_item

Returns the last item (rightmost) in the list, or undef if the list is empty.

length

Returns the number of items currently in the list.

connect_left

$self->connect_left( $other_frame )

Establishes a doubly-linked bond to the left of $self:

$self->prev  = $other_frame
$other_frame->succ = $self

Does nothing if $other_frame is undefined.

$f2->connect_left($f1);    # f1 <-> f2

connect_right

$self->connect_right( $other_frame )

Establishes a doubly-linked bond to the right of $self:

$self->succ  = $other_frame
$other_frame->prev = $self

$f2->connect_right($f3);   # f2 <-> f3

merge_left

$self->merge_left( @lists )

Moves all items from the given lists to the left end of the current list. The source lists are emptied (their _ITEMS are reset to []). The container back-reference on each moved item is updated to point to $self. Returns $self.

$target->merge_left($list_a, $list_b);

merge_right

$self->merge_right( @lists )

Moves all items from the given lists to the right end of the current list. The source lists are emptied. Returns $self.

$target->merge_right($list_c);

HAS

$self->HAS( $slot_name )

Returns the first item for which the named slot has a truthy value, or undef if no such item exists.

my $match = $seq->HAS('is_noun');

HAS_NO

$self->HAS_NO( $slot_name )

Returns true if no item in the list has a truthy value for the named slot.

$seq->HAS_NO('error') or die "sequence contains errors";

STARTS_WITH

$self->STARTS_WITH( $slot_name )

Returns the value of the named slot on the first item of the list (truthy means the sequence starts with that property).

$seq->STARTS_WITH('determiner') or ...;

ENDS_WITH

$self->ENDS_WITH( $slot_name )

Returns the value of the named slot on the last item of the list.

$seq->ENDS_WITH('punctuation') or ...;

container_name

Returns the name of the back-reference slot written on each item when it is added to the list. Defaults to _CONTAINER.

set_container_name

$self->set_container_name( $name )

Changes the container back-reference slot name for this list. Must be called before "build" (or any push_items / unshift_items calls) to take effect on subsequent additions.

$seq->set_container_name('_PHRASE');
# each item added afterwards will have: $item->_PHRASE == $seq

INTERNAL SLOTS

_ITEMS

Arrayref holding the list items. Auto-initialised to [] via _NEEDED if accessed before "build" is called. Do not write to this slot directly — use the provided methods.

_CONTAINER_NAME

Stores the custom container name set by "set_container_name".

SEE ALSO

Chorus::Frame, Chorus::Collection::Filter, Chorus::Engine

AUTHOR

Christophe Ivorra

BUGS

Please report bugs via http://rt.cpan.org/NoAuth/Bugs.html?Dist=Chorus.

LICENSE AND COPYRIGHT

Copyright (C) 2013-2026 Christophe Ivorra.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.