The illusion Reference Manual

This is the illusion Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 05:31:46 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 illusion

Customize and manage Lisp parens reader

Author

Bo Yao <>

License

MIT

Long Description

# Illusion

Illusion is a library for customization and management of Lisp left paren reader.

# Overview

- Adding customized left paren reader macro, based on indicator (first element of list);
- Automatically use left paren reader macro when indicator satisfies user defined predicate;
- Optionally read indicator in case sensitive or customized mode and still read the rest with default reader behavior
- Delete paren left paren reader even they break reader behavior.

Why customize the reader macro of left paren? Some features are impossible without doing that, let’s see a few short examples in [Usage](#Usage) section.

# Usage
## Installation and import
Before illusion available in quicklisp, clone this repo to ‘local-projects‘ or adding to ‘asdf:*central-registry*‘ and:
“‘lisp
(ql:quickload :illusion)
“‘
If you don’t use other customized reader macros, just use ‘:illusion-readtable‘:
“‘lisp
(named-readtables:in-readtable :illusion-readtable)
“‘
Otherwise, merge ‘:illusion-readtable‘ into current one, it only changes definition of ‘#\(‘ and ‘#\)‘:
“‘lisp
(handler-bind ((named-readtables:reader-macro-conflict #’continue))
(named-readtables:merge-readtables-into your-readtable :illusion-readtable))
“‘
## Set and delete a left paren reader
“‘lisp
(illusion:set-paren-reader name predicate reader)
“‘

Use a ‘SET-PAREN-READER‘ to add or change a left paren reader. ‘NAME‘ is a keyword to identify and you can delete it by ‘(DELETE-PAREN-READER NAME)‘. ‘PREDICATE‘ is a function ‘INDICATOR -> BOOLEAN‘. Indicator is the first element of every list. It’s not necessarilly a symbol and first element of a list literal, e.g. ‘a‘ in ‘(a b)‘ is also indicator. So we must carefully check the condition that indicator satisfies in ‘PREDICATE‘. And at last, ‘READER‘ is the function ‘(STREAM INDICATOR) -> OBJECT‘ that called when ‘(PREDICATE INDICATOR)‘ satisfied. Current position of input ‘STREAM‘ is just after read ‘INDICATOR‘.

## Examples
### Temporarily change to preserve case reader after specific indicator
The first example, assume we want to write a ‘DEFINE-CLI‘ which take command line specs and produce a command line argument parser. The command line option is usually case sensitive, so this won’t work:
“‘lisp
(define-cli :main
(v version "Display version of this program")
(V verbose "Set verbose level"))
“‘
‘v‘ and ‘V‘ will both read to ‘V‘. We can use ‘"v"‘, ‘#\v‘, ‘\v‘ or ‘|v|‘, but each one is more verbose. Or we can ‘(setf (readtable-case *readtable*) :preserve)‘, but this force us to use upcase symbols for all CL symbols. What if the reader auto turns on preserve case after encounter ‘DEFINE-CLI‘ indicator? We can define it as:
“‘lisp
(set-paren-reader :define-cli
(lambda (i)
(eql i ’stub-cli:define-cli))
(lambda (stream indicator)
(cons ’stub-cli:define-cli
(cons (read stream)
(with-reader-case :preserve
(cl-read-list stream))))))
“‘
A few note about this left paren reader:
- To compare with a symbol, must given the symbol with its package name like ‘STUB-CLI:DEFINE-CLI‘
- The reader (third parameter of ‘SET-PAREN-READER‘ should return newly cons list. Avoid using ‘’‘ or backquote. Because sometimes they create lists with shared structure and cause strange behavior.
- ‘ILLUSION:WITH-READER-CASE‘ is a trivial but handy utility, that executing the body with ‘(READTABLE-CASE *READTABLE*)‘ bind to one of ‘:UPCASE‘, ‘:DOWNCASW‘, ‘:PRESERVE‘ or ‘:INVERSE‘, and unwind to previous ‘(READTABLE-CASE *READTABLE*)‘ setting after leave it.
- If you want this left paren make effect in current file, need to wrap ‘(set-paren-reader ...)‘ inside ‘(eval-when (:compile-toplevel :load-toplevel :execute) ...)‘ like changing other reader macros.

This only saving a little effort when define cli, but similar techniques can be helpful in accessing case sensitive foreign languages. For example, inline calling a JavaScript method as that in ClojureScript and inline calling a Qt method as if in C++.

### Inline calling CommonQt methods
Calling a CommonQt method need a ‘#_‘ reader macro:
“‘lisp
(#_setBrush painter "brush name")
“‘
Using [https://github.com/commonqt/commonqt](CommonQt) methods a lot is not very pleasant because of many ‘#_‘. If we’re doing GUI programming with CommonQt, usually it make sense to have a whole package dedicated to UI definition and event handling. With the following left paren reader, we can use CommonQt methods as if using Common Lisp functions while let Common Lisp’s package system and illusion do the symbol isolation:
“‘lisp
(set-paren-reader :commonqt
#’qt-symbol-p
(lambda (stream indicator)
(list* ’optimized-call t (read stream) (symbol-name indicator)
(cl-read-list stream))))
“‘

Here ‘(optimized-call t obj "methodName" arg1 arg2)‘ is how CommonQt call Qt Method ‘(#_methodName obj arg1 arg2)‘ and after this ‘SET-PAREN-READER‘ we can simply use ‘(|methodName obj arg1 arg2)‘. Even better, we can use ‘(ILLUSION:SET-INDICATOR-MODE :PRESERVE-CASE)‘ then just ‘(methodName obj arg1 arg2)‘.
In this indicator mode, it will first try the preserve case symbol and check if it satisfies any left paren reader predicate. If none, indicator will fallback to upcase, so all existing Common Lisp and user package symbols still works. In rare case if you have lower and mixed case symbol as function/macro names, try to isolate them with the scope that using CommonQt.
### CSS id and class attached to html element creation function name
In [https://github.com/ailisp/flute](flute) html generation library, HTML elements are defined with same name functions. ‘(div ...)‘ will create a div element. It’s almost shortest possible way to generate html in Common Lisp, but with illusion, we can support haml and hiccup style id/class attached to function names like ‘(div#my-div.class1.class2 ...)‘. To keep example short, we only process id here and writing this left paren reader for a sub-html package, assume stub-html package has ‘DIV‘ exported:
“‘
(set-paren-reader :html
(lambda (i)
(when (symbolp i)
(let ((name (symbol-name i)))
(when (find #\# name)
(let ((name-and-id (split-sequence #\# name)))
(multiple-value-bind (symbol access) (find-symbol (first name-and-id) :stub-html)
(eql access :external)))))))
(lambda (stream indicator)
(let ((name-and-id (split-sequence #\# (symbol-name indicator))))
(list* (find-symbol (first name-and-id) :stub-html)
:id (string-downcase (second name-and-id))
(cl-read-list stream)))))
“‘
## Set indicator mode
As showed in the CommonQt example, illusion support ‘SET-INDICATOR-MODE‘. Currently ‘:STANDARD‘ (default), ‘:PRESERVE-CASE‘ and ‘(INDICATOR-READER . INDICATOR-FALLBACK)‘ is supported. ‘INDICATOR-READER‘ is a function take a stream as only required argument and return the indicator it reads. ‘INDICATOR-FALLBACK‘ is a function called when indicator not satisfied any left paren reader and take indicator as only argument, returns the object that ‘CL:READ‘ would return when reading that indicator.

# Motivation

Illusion will obviously lead to more obscure code. It won’t slow down the generated program since it all happens at read time. But if carefully used, the syntax can be further simplified and gives an illusion of having a more versatile ability with using plain parens. The example usages above are real usage in [flute](https://github.com/ailisp/flute) for html generation and [lispy-cli](https://github.com/ailisp/lispy-cli). Hope illusion also help construct easier usage of your library!

# License

Licensed under the MIT License.
Copyright (c) 2018, Bo Yao. All rights reserved.

Version

0.1

Dependencies
  • named-readtables (system).
  • alexandria (system).
  • let-over-lambda (system).
Source

illusion.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 illusion/src

Source

illusion.asd.

Parent Component

illusion (system).

Child Component

illusion.lisp (file).


4 Files

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


4.1 Lisp


4.1.1 illusion/illusion.asd

Source

illusion.asd.

Parent Component

illusion (system).

ASDF Systems

illusion.


4.1.2 illusion/src/illusion.lisp

Source

illusion.asd.

Parent Component

src (module).

Packages

illusion.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 illusion

Source

illusion.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Macros

Macro: with-reader-case (case &body body)
Package

illusion.

Source

illusion.lisp.


6.1.2 Ordinary functions

Function: cl-read-list (stream)
Package

illusion.

Source

illusion.lisp.

Function: delete-all-paren-readers ()
Package

illusion.

Source

illusion.lisp.

Function: delete-paren-reader (name)
Package

illusion.

Source

illusion.lisp.

Function: set-indicator-mode (mode)
Package

illusion.

Source

illusion.lisp.

Function: set-paren-reader (name predicate reader)
Package

illusion.

Source

illusion.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: *in-list-p*
Package

illusion.

Source

illusion.lisp.

Special Variable: *indicator-fallback*
Package

illusion.

Source

illusion.lisp.

Special Variable: *indicator-reader*
Package

illusion.

Source

illusion.lisp.

Special Variable: *paren-readers*
Package

illusion.

Source

illusion.lisp.

Special Variable: +empty-list+
Package

illusion.

Source

illusion.lisp.


6.2.2 Ordinary functions

Function: cl-read-right-paren (stream)
Package

illusion.

Source

illusion.lisp.

Function: copy-paren-reader (instance)
Package

illusion.

Source

illusion.lisp.

Function: fallback-indicator-upcase (indicator)
Package

illusion.

Source

illusion.lisp.

Function: find-paren-reader (indicator)
Package

illusion.

Source

illusion.lisp.

Function: find-paren-reader-by-name (name)
Package

illusion.

Source

illusion.lisp.

Function: funcallable-p (name)
Package

illusion.

Source

illusion.lisp.

Function: illusion-read-list (stream ignore)
Package

illusion.

Source

illusion.lisp.

Function: illusion-read-right-paren (stream right-paren)
Package

illusion.

Source

illusion.lisp.

Function: make-paren-reader (&key name predicate reader)
Package

illusion.

Source

illusion.lisp.

Reader: paren-reader-name (instance)
Writer: (setf paren-reader-name) (instance)
Package

illusion.

Source

illusion.lisp.

Target Slot

name.

Function: paren-reader-name-matcher (name)
Package

illusion.

Source

illusion.lisp.

Function: paren-reader-p (object)
Package

illusion.

Source

illusion.lisp.

Reader: paren-reader-predicate (instance)
Writer: (setf paren-reader-predicate) (instance)
Package

illusion.

Source

illusion.lisp.

Target Slot

predicate.

Reader: paren-reader-reader (instance)
Writer: (setf paren-reader-reader) (instance)
Package

illusion.

Source

illusion.lisp.

Target Slot

reader.

Function: read-indicator-preserve-case (stream)
Package

illusion.

Source

illusion.lisp.


6.2.3 Structures

Structure: paren-reader
Package

illusion.

Source

illusion.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: name
Readers

paren-reader-name.

Writers

(setf paren-reader-name).

Slot: predicate
Readers

paren-reader-predicate.

Writers

(setf paren-reader-predicate).

Slot: reader
Readers

paren-reader-reader.

Writers

(setf paren-reader-reader).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   F   I   M   P   R   S   W  
Index Entry  Section

(
(setf paren-reader-name): Private ordinary functions
(setf paren-reader-predicate): Private ordinary functions
(setf paren-reader-reader): Private ordinary functions

C
cl-read-list: Public ordinary functions
cl-read-right-paren: Private ordinary functions
copy-paren-reader: Private ordinary functions

D
delete-all-paren-readers: Public ordinary functions
delete-paren-reader: Public ordinary functions

F
fallback-indicator-upcase: Private ordinary functions
find-paren-reader: Private ordinary functions
find-paren-reader-by-name: Private ordinary functions
funcallable-p: Private ordinary functions
Function, (setf paren-reader-name): Private ordinary functions
Function, (setf paren-reader-predicate): Private ordinary functions
Function, (setf paren-reader-reader): Private ordinary functions
Function, cl-read-list: Public ordinary functions
Function, cl-read-right-paren: Private ordinary functions
Function, copy-paren-reader: Private ordinary functions
Function, delete-all-paren-readers: Public ordinary functions
Function, delete-paren-reader: Public ordinary functions
Function, fallback-indicator-upcase: Private ordinary functions
Function, find-paren-reader: Private ordinary functions
Function, find-paren-reader-by-name: Private ordinary functions
Function, funcallable-p: Private ordinary functions
Function, illusion-read-list: Private ordinary functions
Function, illusion-read-right-paren: Private ordinary functions
Function, make-paren-reader: Private ordinary functions
Function, paren-reader-name: Private ordinary functions
Function, paren-reader-name-matcher: Private ordinary functions
Function, paren-reader-p: Private ordinary functions
Function, paren-reader-predicate: Private ordinary functions
Function, paren-reader-reader: Private ordinary functions
Function, read-indicator-preserve-case: Private ordinary functions
Function, set-indicator-mode: Public ordinary functions
Function, set-paren-reader: Public ordinary functions

I
illusion-read-list: Private ordinary functions
illusion-read-right-paren: Private ordinary functions

M
Macro, with-reader-case: Public macros
make-paren-reader: Private ordinary functions

P
paren-reader-name: Private ordinary functions
paren-reader-name-matcher: Private ordinary functions
paren-reader-p: Private ordinary functions
paren-reader-predicate: Private ordinary functions
paren-reader-reader: Private ordinary functions

R
read-indicator-preserve-case: Private ordinary functions

S
set-indicator-mode: Public ordinary functions
set-paren-reader: Public ordinary functions

W
with-reader-case: Public macros