The cl-locatives Reference Manual

Table of Contents

The cl-locatives Reference Manual

This is the cl-locatives Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:00:20 2021 GMT+0.

1 Introduction

                             CL-LOCATIVES
                             ============

                           By Robert Smith

Locatives are the Lisp equivalent of pointers, minus the
arithmetic. In Lisp terms, they make the concept of "places"
first-class.

The main API consists of the macro LOCATIVE-FOR, which takes as an
argument a place, as you would give to SETF; and the function
DEREFERENCE, which extracts the value of that place, and (SETF
DEREFERENCE), which sets the value of that place.

The following example pretty much sums up the API:

(let* ((x (make-array 5 :initial-element 0))
       (l (locative-for (aref x 2))))
  (setf (dereference l) 5)
  (list l
        x
        (dereference l)))

gives

(# #(0 0 5 0 0) 5)

as a result. We also have LOCATIVEP, and you can funcall the
LOCATIVE-WRITER of a locative if you need to deal with multiple values
(a rare case).

This code can be very useful for porting over C code which uses
pointers and by-reference values a lot.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-locatives

Author

Robert Smith <quad@symbo1ics.com>

License

BSD 3-clause (See LICENSE)

Description

Implementation of locatives, pointer-like objects in Lisp.

Source

cl-locatives.asd (file)

Components

• package.lisp (file)
• cl-locatives.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-locatives.asd

Location

cl-locatives.asd

Systems

cl-locatives (system)

3.1.2 cl-locatives/package.lisp

Parent

cl-locatives (system)

Location

package.lisp

Packages

cl-locatives

3.1.3 cl-locatives/cl-locatives.lisp

Dependency

package.lisp (file)

Parent

cl-locatives (system)

Location

cl-locatives.lisp

Exported Definitions

• dereference (function)
• (setf dereference) (setf expander)
• locative (structure)
• locative-for (macro)
• locative-writer (function)
• locativep (function)

Internal Definitions

• %make-locative (function)
• locative-reader (function)

4 Packages

Packages are listed by definition order.

4.1 cl-locatives

A package for creating and manipulating locatives.

Source

package.lisp (file)

Nickname

loc

Use List

common-lisp

Exported Definitions

• dereference (function)
• (setf dereference) (setf expander)
• locative (structure)
• locative-for (macro)
• locative-writer (function)
• locativep (function)

Internal Definitions

• %make-locative (function)
• locative-reader (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: locative-for PLACE

Return a locative for the place PLACE.

PLACE should be a form that can be passed as the first argument to SETF.

Package

cl-locatives

Source

cl-locatives.lisp (file)

5.1.2 Functions

Function: dereference LOCATIVE

Return a value that a locative LOCATIVE "points" to.

Package

cl-locatives

Source

cl-locatives.lisp (file)

Setf Expander

(setf dereference) (setf expander)

Setf Expander: (setf dereference) LOCATIVE

Package

cl-locatives

Source

cl-locatives.lisp (file)

Reader

dereference (function)

Function: locative-writer INSTANCE

Package

cl-locatives

Source

cl-locatives.lisp (file)

Function: locativep OBJECT

Package

cl-locatives

Source

cl-locatives.lisp (file)

5.1.3 Structures

Structure: locative ()

A pointer-like data structure to allow, among other things, "reference passing" programming style.

Package

cl-locatives

Source

cl-locatives.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: reader

Type

function

Initform

(error "must provide reader function.")

Readers

locative-reader (function)

Writers

(setf locative-reader) (function)

Slot: writer

Type

function

Initform

(error "must provide writer function.")

Readers

locative-writer (function)

Writers

(setf locative-writer) (function)

5.2 Internal definitions

5.2.1 Functions

Function: %make-locative &key (READER READER) (WRITER WRITER)

Package

cl-locatives

Source

cl-locatives.lisp (file)

Function: locative-reader INSTANCE

Package

cl-locatives

Source

cl-locatives.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types