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).