The cl-getx Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-getx Reference Manual

This is the cl-getx Reference Manual, version 2020.7.15, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Nov 04 12:15:17 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-getx

A getf (and dig) that works with "Generalized Variables". Its simple and should not change much but no gaurentees. If you consider using it in your project ping me in the issues on gitlab so I know that I am affecting some one when I trash the api ;)

Background

To undestand what all of this is about have a look at this setf documentation

Generalized Variables see https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node80.html

Here is the first 3 paragraphs from that dock:

"In Lisp, a variable can remember one piece of data, that is, one Lisp object. The main operations on a variable are to recover that object and to alter the variable to remember a new object these operations are often called access and update operations. The concept of variables named by symbols can be generalized to any storage location that can remember one piece of data, no matter how that location is named. Examples of such storage locations are the car and cdr of a cons, elements of an array, and components of a structure."

"For each kind of generalized variable, typically there are two functions that implement the conceptual access and update operations. For a variable, merely mentioning the name of the variable accesses it, while the setq special form can be used to update it. The function car accesses the car of a cons, and the function rplaca updates it. The function symbol-value accesses the dynamic value of a variable named by a given symbol, and the function set updates it."

"Rather than thinking about two distinct functions that respectively access and update a storage location somehow deduced from their arguments, we can instead simply think of a call to the access function with given arguments as a name for the storage location. Thus, just as x may be considered a name for a storage location (a variable), so (car x) is a name for the car of some cons (which is in turn named by x). Now, rather than having to remember two functions for each kind of generalized variable (having to remember, for example, that rplaca corresponds to car), we adopt a uniform syntax for updating storage locations named in this way, using the setf macro."

Why getx

My opinion is that "they" could have done a getf for places as well. Enters getx (pronounced get x) rather than having to remember the names and syntax order of such access functions for each kind of generalized variable (having to remember, for example, that getf = (place accessor) and gethash = (accessor place), I adopt a uniform syntax for updating and fetching such storage locations, using the getx generic method.

It can be argued that most editors show you the order as you type anyway, well what happens when you have a lot of lines of code and you used one type of place lets say a hashtable and now you want to change it to plists? You are not just going to do a quick text replace :).

Generatiing such access code (for whatever reason) using getx should be simpler as well.

But WAIT there is more!!! You get a digx as well!!! :P

Not a NEW IDEA:

This is not a NEW IDEA, and examples of such a getf can be found out there. For example you can find some code in lisp21.

Trivia:

Curiously a getx function was one of the first utility functions I tried to write for my self when I started using lisp. Maybe it was because I was working on a simple object database, I was trying to see of objects or lists where better for my design and went to and fro a couple of times. It obviously left me scared ;)

Examples:

> (getx (list :eish 1) :eish)
1
> (let ((plist (list :eish 1)))
    (setf (getx plist :eish) 2)
    (getx plist :eish))
2

> (getx (list 'eish 1) 'eish)
1

> (let ((plist (list 'eish 1)))
    (setf (getx plist 'eish) 2)
    (getx plist 'eish))
2

> (getx (list 'eish 1) #'(lambda (place) (getf place 'eish)))
1

> (let ((plist (list 'eish 1)))
    (setf (getx plist #'(lambda (place value)
 			  (setf (getf place 'eish) value)))
  	2)
    (getx plist #'(lambda (place)
  		  (getf place 'eish))))
2

(defclass thingy ()
 ((eish :initarg :eish :accessor eish)))
 
(setf x (make-instance 'thingy 'eish 1))

> (getx x 'eish)
1

> (setf (getx x 'some-slot) 2)
2

> (getx x 'some-slot)
2


Doing a (setf getf) on a property that does not exist does nothing but for getx it adds the property with the new value.

Default (setf getf) behaviour:

(defun add-stuff (container) (setf (getf container :new) 234))

> (let (x) (add-stuff x) x)
NIL

> (let ((x (list :a 1))) (add-stuff x) x)
(:A 1)

(setf getx) behaviour for plist:

(defun add-stuff (container)
  (setf (getx container :new) 234))

;;Could not fix x=nil
>(let (x) (add-stuff x) x)
NIL

;;But could do something about adding properties to an a list
> (let ((x (list :a 1)))
    (add-stuff x)
    x)
(:A 1 :NEW 234)

digx examples:

> (digx (list :eish (list :huh 1)) :eish :huh)
1

> (let ((x (list :eish (list :huh 1)))) 
    (setf (cl-getx:digx x :eish :huh) 'huh) 
    x)
(:EISH (:HUH HUH))

> (let ((plist (list :eish (list 'huh (list :erm 1))))) 
  (setf (cl-getx:digx plist :eish 'huh #'(lambda (place &optional value)
					   (setf (getf place ':erm) value)))
	'huh) 
  plist)
(:EISH (HUH (:ERM HUH)))

Tests

Tests can be found in tests.lisp just load it after you quickload cl-getx and check your repl for the output.

Lots more tests are needed, especially setf ones, but the current set proves that the basics work.

Tests pass on sbcl and ecl.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-getx

Author

Phil Marneweck <phil@psychedelic.co.za>

License

MIT

Description

This is a naive, persisted, in memory (lazy loading) data store for Common Lisp.

Version

2020.7.15

Source

cl-getx.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-getx.asd

Location

cl-getx.asd

Systems

cl-getx (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-getx/packages.lisp

Parent

cl-getx (system)

Location

packages.lisp

Packages

cl-getx


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-getx/getx.lisp

Dependency

packages.lisp (file)

Parent

cl-getx (system)

Location

getx.lisp

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-getx/digx.lisp

Dependency

getx.lisp (file)

Parent

cl-getx (system)

Location

digx.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-getx

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: pick-accessor-expansion ACCESSOR PLACE DEFAULT-FORM &rest ARGS

This is used to choose between a function form or a value form of the place.

default-form can be a function name or "something" more complex.

Package

cl-getx

Source

getx.lisp (file)

Macro: pick-setf-accessor-expansion ACCESSOR PLACE VALUE DEFAULT-FORM &rest ARGS
Package

cl-getx

Source

getx.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: digx PLACE &rest INDICATORS

Hierarchical getx. You dont really need to
create specializers based on the type of place because
digx uses getx internally and getx does the type specific work.

Examples:

> (digx (list :eish (list :huh 1)) :eish :huh)
1

> (let ((x (list :eish (list :huh 1))))
(setf (cl-getx:digx x :eish :huh) ’huh)
x)
(:EISH (:HUH HUH))

Package

cl-getx

Source

digx.lisp (file)

Writer

(setf digx) (generic function)

Methods
Method: digx PLACE &rest INDICATORS
Generic Function: (setf digx) VALUE PLACE &rest INDICATORS
Package

cl-getx

Source

digx.lisp (file)

Reader

digx (generic function)

Methods
Method: (setf digx) VALUE PLACE &rest INDICATORS
Generic Function: getx PLACE ACCESSOR &key DEFAULT &allow-other-keys

Returns the data stored in a place by name or named-accessor or concrete accessor function.

Currently places, hash-tables and plists are implemented. Methods for specific types or other lisp types can be implemented easially.

Examples:

> (getx (list :eish 1) :eish)
1

> (getx (list ’eish 1) ’eish)
1

> (getx (list ’eish 1) #’(lambda (place) (getf place ’eish)))
1

(defclass thingy () ((eish :initarg :eish :accessor eish)))
(setf x (make-instance ’thingy ’eish 1))
> (getx x ’eish)
1

**EXTREME**

Or if you really want uniform thinking and syntax for your data places
This is not a good idea if you are writing a library that others will use
some one might clobber your :eish by accident or you might clobber their :eish

(defclass thingy () ((eish :initarg :eish :accessor :eish)))
(setf x (make-instance ’thingy :eish 1))
> (getx x :eish)
1

Package

cl-getx

Source

getx.lisp (file)

Writer

(setf getx) (generic function)

Methods
Method: getx (PLACE standard-object) ACCESSOR &key &allow-other-keys
Method: getx (PLACE hash-table) ACCESSOR &key DEFAULT &allow-other-keys
Method: getx PLACE ACCESSOR &key &allow-other-keys
Generic Function: (setf getx) VALUE PLACE ACCESSOR &key DEFAULT &allow-other-keys

Specialize as you need. plists, hash-tables and standard-object is taken care of.

Package

cl-getx

Source

getx.lisp (file)

Reader

getx (generic function)

Methods
Method: (setf getx) VALUE (PLACE standard-object) ACCESSOR &key &allow-other-keys

This is for use with (setf getx) of standard-objects.

Method: (setf getx) VALUE (PLACE hash-table) ACCESSOR &key DEFAULT &allow-other-keys

This is for use with (setf getx) of gethash.

Method: (setf getx) VALUE (PLACE list) ACCESSOR &key &allow-other-keys

This is for use with (setf getx) of gethash.

Generic Function: place-exists-p PLACE ACCESSOR

Returns t if the place exists. Default implementation is for plists.

Package

cl-getx

Source

getx.lisp (file)

Methods
Method: place-exists-p (PLACE standard-object) SLOT-NAME

This is a bit of a waste to do since gethash gives you the value and tells you if the key is not found, but its here for completeness.

Method: place-exists-p (PLACE hash-table) KEY

This is a bit of a waste to do since gethash gives you the value and tells you if the key is not found, but its here for completeness.

Method: place-exists-p PLACE ACCESSOR

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: dig-down PLACE INDICATORS
Package

cl-getx

Source

digx.lisp (file)

Function: set-dig-down PLACE INDICATORS VALUE
Package

cl-getx

Source

digx.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-getx.asd: The cl-getx․asd file
cl-getx/digx.lisp: The cl-getx/digx․lisp file
cl-getx/getx.lisp: The cl-getx/getx․lisp file
cl-getx/packages.lisp: The cl-getx/packages․lisp file

F
File, Lisp, cl-getx.asd: The cl-getx․asd file
File, Lisp, cl-getx/digx.lisp: The cl-getx/digx․lisp file
File, Lisp, cl-getx/getx.lisp: The cl-getx/getx․lisp file
File, Lisp, cl-getx/packages.lisp: The cl-getx/packages․lisp file

L
Lisp File, cl-getx.asd: The cl-getx․asd file
Lisp File, cl-getx/digx.lisp: The cl-getx/digx․lisp file
Lisp File, cl-getx/getx.lisp: The cl-getx/getx․lisp file
Lisp File, cl-getx/packages.lisp: The cl-getx/packages․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
D   F   G   M   P   S  
Index Entry  Section

(
(setf digx): Exported generic functions
(setf digx): Exported generic functions
(setf getx): Exported generic functions
(setf getx): Exported generic functions
(setf getx): Exported generic functions
(setf getx): Exported generic functions

D
dig-down: Internal functions
digx: Exported generic functions
digx: Exported generic functions

F
Function, dig-down: Internal functions
Function, set-dig-down: Internal functions

G
Generic Function, (setf digx): Exported generic functions
Generic Function, (setf getx): Exported generic functions
Generic Function, digx: Exported generic functions
Generic Function, getx: Exported generic functions
Generic Function, place-exists-p: Exported generic functions
getx: Exported generic functions
getx: Exported generic functions
getx: Exported generic functions
getx: Exported generic functions

M
Macro, pick-accessor-expansion: Exported macros
Macro, pick-setf-accessor-expansion: Exported macros
Method, (setf digx): Exported generic functions
Method, (setf getx): Exported generic functions
Method, (setf getx): Exported generic functions
Method, (setf getx): Exported generic functions
Method, digx: Exported generic functions
Method, getx: Exported generic functions
Method, getx: Exported generic functions
Method, getx: Exported generic functions
Method, place-exists-p: Exported generic functions
Method, place-exists-p: Exported generic functions
Method, place-exists-p: Exported generic functions

P
pick-accessor-expansion: Exported macros
pick-setf-accessor-expansion: Exported macros
place-exists-p: Exported generic functions
place-exists-p: Exported generic functions
place-exists-p: Exported generic functions
place-exists-p: Exported generic functions

S
set-dig-down: Internal functions

Jump to:   (  
D   F   G   M   P   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-getx: The cl-getx system
cl-getx: The cl-getx package

P
Package, cl-getx: The cl-getx package

S
System, cl-getx: The cl-getx system

Jump to:   C   P   S