NAME

LISP::List - Perl extension for implementing linked lists as in Lisp

SYNOPSIS

use LISP::List;

$list = LISP->new([qw(1 2 3)]);

$car = $list->car;
$cdr = $list->cdr;

$caar = $list->cddr;
$cddr = $list->cddr;
$cadr = $list->cadr; # etc.

$list->rplaca($car);
$list->rplacd($cdr);

@sub_nodes = $list->sub_nodes;
$rev_list = $list->reverse;
$new_list = $list->append(@lists);

$scalar = $list->pop;
$list->push($element);
$last_list   = $list->last;
$length      = $list->length;
$is_a_list     = $list->listp;
$is_empty_list = $list->nilp;

$new_list = $list->mapcar($code_ref, [@more_lists]);
$result   = $list->apply($code_ref);

$string   = $list->string;

DESCRIPTION

This is an implementation of linked lists, with Lisp-like functionality. Any reference to lists here refers to Lisp-like linked lists, while @variables in perl will be called arrays.

= head2 Explanation Here is a brief description of linked lists in Lisp.

(1 2 3 4) is short hand for:
(1 . (2 . (3 . (4 . NIL))))
which graphically represented as:
.--.--.--.--NIL
|  |  |  |
1  2  3  4

The list 'starts' with the node in the upper-left corner.
The car of a list node is the element below a node, and the cdr of a
node is the element to the right of a node. In a 'true' list, the cdr of
a list is always a list, and the 'last' cdr is NIL, which represents
the empty list.

List nodes are also called 'cons' cells. Cons cells do not have to have
a list (NIL or otherwise) as their cdr. Things referred to as lists below
do not always refer to a 'true' list necessarily, and may also apply to cons cells.

Methods

new (ARRAY_REF)
    Calling LISP::List->new($array_ref), or LISP->new($array_ref) for short,
    will create a new linked list of the elements of $array_ref, with each
    array reference within $array_ref itself becoming a linked list.

car
    Returns the car of a list.

cdr 
    Returns the cdr of a list.

caar, cddr, cadr, etc.
    E.g. cadr returns the car of the cdr of a list, any method matching
    /c[ad][ad]+r/ is autoloaded to return the appropriate chaining of car and cdr.

sub_nodes
    Returns all of the car's of the top-level nodes of a list in an array.

reverse
    Returns a copy of the top-level nodes of a list in reverse.

append (LISTS)
    Copies the top-level nodes of all but the last list and appends all of the
    copies, including the last list, together into a new list.

pop
    Returns the car of a list and sets the list to the cdr of itself.

push (ELEMENT)
    Creates a new cons cell with the given element as its car, and the list as
    its cdr, and sets the list to the new cons cell.

last
    Returns the last non-NIL top-level node of the LIST.

length
    Returns the number of non-NIL top-level nodes of a list.

listp
    Returns true if its argument is a list (This method may be exported and used as
    a function).

nilp
    Returns true if its argument is NIL (This method may be exported and used as
    a function).

string
    Returns a string representation of a list.

apply (CODEREF)
    Same as apply in LISP::Lambda but takes the arguments in a different order, so
    the list is the object instead of the subroutine.

mapcar (CODEREF, [@MORE_LISTS])
    Same as mapcar in LISP::Lambda but takes arguments in a different order, so the
    list is the object instead of the subroutine.

EXPORT

Nothing exported by default.

:all
    exports the methods/functions listp and nilp so they can be used as functions on
    values other than lists.

AUTHOR

Douglas Wilson, dwilson@gtemail.net

SEE ALSO

perl(1).