The reader Reference Manual

Table of Contents

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

The reader Reference Manual

This is the reader Reference Manual, version 0.10.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:37:07 2021 GMT+0.


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

1 Introduction

Installation

Download from the Releases section.

I'll promote v0.10.0 to v1.0.0 if there are no significant changes over the next year.

Getting Started

(reader:enable-reader-syntax &rest reader-macro-identifiers)
;; OR
(reader+swank:enable-package-local-reader-syntax &rest reader-macro-identifiers)
;; (describe 'reader:enable-reader-syntax) ; for a list of identifiers

;; Complementory macros
;; (reader:disable-reader-syntax) ; is complementary
;; OR
;; (reader+swank-disable-package-local-reader-syntax)

Examples

CL-USER> #[[1 2 3
            4 5 6]
           [3 2 1
            7 8 9]]
#3A(((1 2 3) (4 5 6)) ((3 2 1) (7 8 9)))        ; cleaner syntax for arrays
CL-USER> (gethash 'a {eq 'a 1 'b 2})            ; hash-tables
1
T
CL-USER> (hash-set:hs-memberp #{"a" "b" "c"} "c") ; hash-set - can change in future
T
CL-USER> [#2A((1 2 3) (4 5 6)) 1 0]             ; accessors
4
CL-USER> (setf reader:*get-val-array-function* 'select:select)
SLCT:SELECT
CL-USER> (let ((arr #2A((1 2 3) (4 5 6))))
           [arr t 0])
#(1 4)
CL-USER> [{"a" 1 "b" 2} "a"]
1
T
CL-USER> [(cl-json:decode-json-from-string "{\"a\":1, \"b\":2}") :b] ; works with alists
2
CL-USER> (-> {"a" "apple" "b" "ball"} ["b"] [1]); accessors can be chained using arrows:->
#\a
CL-USER> #!echo -n hello world
hello world                                     ; Captures until the end of line
NIL                                             ; Should be possible to capture into a string
NIL                                             ; but not ideal for speed
0
CL-USER> (let ((a t)) !a)                       ; not
NIL
CL-USER> (let ((a 5.0d0)) $a)                   ; write-to-string
"5.0d0"                   ; should this be "ensure-string"? raise an issue!
CL-USER> ?reader:enable-reader-syntax           ; variable use not intended
READER:ENABLE-READER-SYNTAX
  [symbol]
ENABLE-READER-SYNTAX names a macro:
  Lambda-list: (&REST READER::READER-MACRO-IDENTIFIERS)
  Documentation:
    READER-MACRO-IDENTIFIERS are any of the following symbols:
      GET-VAL, HASH-TABLE, NOT, STRING, DESCRIBE, ARRAY, SET, RUN-PROGRAM
  Source file: /home/user/quicklisp/local-projects/reader/reader.lisp

Notes

The functions used for constructing arrays, hash-tables, sets, accessing array elements or accessors in general can be specified by

This should allow users to use fset or access or other libraries for the respective functions.

By default, alists and plists are treated distinct from lists whenever possible (see the get-val method specialized on lists). To disable this behavior, set each of these to T:

Hash Tables

Setting alists and plists

array vs get-val

Notes for existing users upgrading to v0.10.0 from v0.9.1

Lambda

CL-USER> (mapcar λ(write-to-string -) '(2 3 4)) ; lambdas
("2" "3" "4")

This begins to feel like line-noise after a while and is not ideal for readability; a better equivalent is the simple macro

CL-USER> (defmacro lm (&rest var-body)
           `(lambda ,(butlast var-body)
              ,@(last var-body)))
LM
CL-USER> (mapcar (lm o (write-to-string o)) '(2 3 4))
("2" "3" "4")

Hash-table

Since the function used for constructing hash-tables is now configurable (via reader:*hash-table-function*), the first input to the hash-table may be interpreted as the equality function. Thus, hash-table syntax can take an even (with default test cl:equalp) or odd (with the first symbol being interpreted as the equality function) number of arguments.

Setting alists and plists

Now works for non-empty lists.

Testing

(ql:quickload "reader")
(5am:run :reader)
;; OR
(asdf:test-system "reader")

Emacs Indentation Support

(modify-syntax-entry ?\[ "(]" lisp-mode-syntax-table)
(modify-syntax-entry ?\] ")[" lisp-mode-syntax-table)
(modify-syntax-entry ?\{ "(}" lisp-mode-syntax-table)
(modify-syntax-entry ?\} "){" lisp-mode-syntax-table)
(define-key paredit-mode-map (kbd "{") 'paredit-open-curly)
(define-key paredit-mode-map (kbd "}") 'paredit-close-curly)
(global-set-key (kbd "C-S-l") (lambda () ; for inserting lambda
                                (interactive)
                                (insert-char (aref (symbol-name 'λ) 0))))
(setq paredit-space-for-delimiter-predicates
      (list (lambda (endp delimiter)
              (not (and (eql ?\( delimiter)
                        (member (char-before (point))
                                '(?\@ ?λ))))))))
(set-language-environment "UTF-8")

Motivation: paredit curly brace matching in swank-clojure repl - Stack OverFlow

Known Issues

Known issues include aligning hash-tables without first-element-as-key:

{"hello" 1
         "world" 2}

A work-around is to specify the test as the first element, and let that default exist for one-liners:

{equal "hello" 1
       "world" 2}
{"hello" 1 "world" 2}

Comments


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 reader

Author

<Shubhamkar Ayare (shubhamayare@yahoo.co.in)>

License

MIT

Description

A utility library intended at providing configurable reader macros for
common tasks such as accessors, hash-tables, sets, uiop:run-program, arrays and a few others.

Version

0.10.0

Dependencies
Source

reader.asd (file)

Component

reader.lisp (file)


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 reader.asd

Location

reader.asd

Systems

reader (system)


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

3.1.2 reader/reader.lisp

Parent

reader (system)

Location

reader.lisp

Packages

reader

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 reader

Source

reader.lisp (file)

Use List
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 Special variables

Special Variable: *alists-are-lists*

If T, ALISTS will not be treated specially by READER:GET-VAL method for lists.

Package

reader

Source

reader.lisp (file)

Special Variable: *array-function*

A symbol bound (at read-time) to a function that takes INITIAL-CONTENTS
as its argument and returns the array. INITIAL-CONTENTS is a list of nested-lists.

Package

reader

Source

reader.lisp (file)

Special Variable: *get-val-array-function*

A symbol bound (at read-time) to a function that takes
(ARRAY &REST SUBSCRIPTS)
as arguments and returns the corresponding value.
This is assumed to have a SETF defined.
This variable is significant if READER:*GET-VAL-FUNCTION* is bound to READER:GET-VAL.

Package

reader

Source

reader.lisp (file)

Special Variable: *get-val-function*

A symbol bound (at read-time) to a function that takes (OBJECT &REST KEY/S)
as arguments and returns the value corresponding to the KEY/S.

Package

reader

Source

reader.lisp (file)

Special Variable: *hash-table-function*

A symbol bound (at read-time) to a function that takes (PLIST &KEY TEST)
as arguments and returns the hash-table.

Package

reader

Source

reader.lisp (file)

Special Variable: *plists-are-lists*

If T, PLISTS will not be treated specially by READER:GET-VAL method for lists.

Package

reader

Source

reader.lisp (file)

Special Variable: *set-function*

A symbol bound (at read-time) to a function that takes (LIST &KEY TEST)
as arguments and returns the set.

Package

reader

Source

reader.lisp (file)


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

5.1.2 Macros

Macro: disable-reader-syntax ()
Package

reader

Source

reader.lisp (file)

Macro: enable-reader-syntax &rest READER-MACRO-IDENTIFIERS

READER-MACRO-IDENTIFIERS are any of the following symbols: GET-VAL, HASH-TABLE, NOT, STRING, DESCRIBE, ARRAY, SET, RUN-PROGRAM

Package

reader

Source

reader.lisp (file)


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

5.1.3 Generic functions

Generic Function: get-val OBJECT &rest KEY/S
Package

reader

Source

reader.lisp (file)

Writer

(setf get-val) (generic function)

Methods
Method: get-val (OBJECT array) &rest KEY/S
Method: get-val (OBJECT list) &rest KEY/S
Method: get-val (OBJECT hash-table) &rest KEY/S
Method: get-val (OBJECT sequence) &rest KEY/S
Method: get-val (OBJECT structure-object) &rest KEY/S
Generic Function: (setf get-val) G0 OBJECT &rest KEY/S
Package

reader

Reader

get-val (generic function)

Methods
Method: (setf get-val) NEW-VALUE (OBJECT array) &rest KEY/S
Source

reader.lisp (file)

Method: (setf get-val) NEW-VALUE (OBJECT list) &rest KEY/S
Source

reader.lisp (file)

Method: (setf get-val) G0 (OBJECT hash-table) &rest KEY/S
Source

reader.lisp (file)

Method: (setf get-val) G0 (OBJECT sequence) &rest KEY/S
Source

reader.lisp (file)

Method: (setf get-val) G0 (OBJECT structure-object) &rest KEY/S
Source

reader.lisp (file)

Method: (setf get-val) G0 (OBJECT standard-object) &rest KEY/S
Source

reader.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Constants

Constant: +reader-macro-doc+
Package

reader

Source

reader.lisp (file)


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

5.2.2 Special variables

Special Variable: *previous-readtables*
Package

reader

Source

reader.lisp (file)

Special Variable: *reader-macro-activation-functions*
Package

reader

Source

reader.lisp (file)


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

5.2.3 Macros

Macro: defmethods-with-setf FUN-NAME LAMBDA-LIST &rest METHODS
Package

reader

Source

reader.lisp (file)

Macro: setp NEW-VALUE PLACE
Package

reader

Source

reader.lisp (file)

Macro: with-env &body BODY
Package

reader

Source

reader.lisp (file)

Macro: with-reader-syntax READER-MACRO-IDENTIFIERS &body BODY

This macro is only made for use by read-and-eval functionality, and rather directed towards tests than users. So, do not export.

Package

reader

Source

reader.lisp (file)


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

5.2.4 Functions

Function: %enable-reader-syntax READTABLE &rest READER-MACRO-IDENTIFIERS
Package

reader

Source

reader.lisp (file)

Function: array-reader-macro STREAM CHAR N
Package

reader

Source

reader.lisp (file)

Function: describe-reader-macro STREAM CHAR
Package

reader

Source

reader.lisp (file)

Function: er STRING
Package

reader

Source

reader.lisp (file)

Function: get-val-reader-macro STREAM CHAR
Package

reader

Source

reader.lisp (file)

Function: hash-table-reader-macro STREAM CHAR
Package

reader

Source

reader.lisp (file)

Function: list-to-hash-set-with-test LIST &key TEST
Package

reader

Source

reader.lisp (file)

Function: make-t-array-from-initial-contents INITIAL-CONTENTS
Package

reader

Source

reader.lisp (file)

Function: not-reader-macro STREAM CHAR
Package

reader

Source

reader.lisp (file)

Function: read-array STREAM
Package

reader

Source

reader.lisp (file)

Function: read-row-from-string STRING
Package

reader

Source

reader.lisp (file)

Function: read-stream-as-string-until STREAM UNTIL-CHAR
Package

reader

Source

reader.lisp (file)

Function: read-stream-until STREAM UNTIL-CHAR
Package

reader

Source

reader.lisp (file)

Function: run-program-reader-macro STREAM CHAR N
Package

reader

Source

reader.lisp (file)

Function: set-reader-macro STREAM CHAR N
Package

reader

Source

reader.lisp (file)

Function: string-reader-macro STREAM CHAR
Package

reader

Source

reader.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   R  
Index Entry  Section

F
File, Lisp, reader.asd: The reader․asd file
File, Lisp, reader/reader.lisp: The reader/reader․lisp file

L
Lisp File, reader.asd: The reader․asd file
Lisp File, reader/reader.lisp: The reader/reader․lisp file

R
reader.asd: The reader․asd file
reader/reader.lisp: The reader/reader․lisp file

Jump to:   F   L   R  

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

A.2 Functions

Jump to:   %   (  
A   D   E   F   G   H   L   M   N   R   S   W  
Index Entry  Section

%
%enable-reader-syntax: Internal functions

(
(setf get-val): Exported generic functions
(setf get-val): Exported generic functions
(setf get-val): Exported generic functions
(setf get-val): Exported generic functions
(setf get-val): Exported generic functions
(setf get-val): Exported generic functions
(setf get-val): Exported generic functions

A
array-reader-macro: Internal functions

D
defmethods-with-setf: Internal macros
describe-reader-macro: Internal functions
disable-reader-syntax: Exported macros

E
enable-reader-syntax: Exported macros
er: Internal functions

F
Function, %enable-reader-syntax: Internal functions
Function, array-reader-macro: Internal functions
Function, describe-reader-macro: Internal functions
Function, er: Internal functions
Function, get-val-reader-macro: Internal functions
Function, hash-table-reader-macro: Internal functions
Function, list-to-hash-set-with-test: Internal functions
Function, make-t-array-from-initial-contents: Internal functions
Function, not-reader-macro: Internal functions
Function, read-array: Internal functions
Function, read-row-from-string: Internal functions
Function, read-stream-as-string-until: Internal functions
Function, read-stream-until: Internal functions
Function, run-program-reader-macro: Internal functions
Function, set-reader-macro: Internal functions
Function, string-reader-macro: Internal functions

G
Generic Function, (setf get-val): Exported generic functions
Generic Function, get-val: Exported generic functions
get-val: Exported generic functions
get-val: Exported generic functions
get-val: Exported generic functions
get-val: Exported generic functions
get-val: Exported generic functions
get-val: Exported generic functions
get-val-reader-macro: Internal functions

H
hash-table-reader-macro: Internal functions

L
list-to-hash-set-with-test: Internal functions

M
Macro, defmethods-with-setf: Internal macros
Macro, disable-reader-syntax: Exported macros
Macro, enable-reader-syntax: Exported macros
Macro, setp: Internal macros
Macro, with-env: Internal macros
Macro, with-reader-syntax: Internal macros
make-t-array-from-initial-contents: Internal functions
Method, (setf get-val): Exported generic functions
Method, (setf get-val): Exported generic functions
Method, (setf get-val): Exported generic functions
Method, (setf get-val): Exported generic functions
Method, (setf get-val): Exported generic functions
Method, (setf get-val): Exported generic functions
Method, get-val: Exported generic functions
Method, get-val: Exported generic functions
Method, get-val: Exported generic functions
Method, get-val: Exported generic functions
Method, get-val: Exported generic functions

N
not-reader-macro: Internal functions

R
read-array: Internal functions
read-row-from-string: Internal functions
read-stream-as-string-until: Internal functions
read-stream-until: Internal functions
run-program-reader-macro: Internal functions

S
set-reader-macro: Internal functions
setp: Internal macros
string-reader-macro: Internal functions

W
with-env: Internal macros
with-reader-syntax: Internal macros

Jump to:   %   (  
A   D   E   F   G   H   L   M   N   R   S   W  

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

A.3 Variables

Jump to:   *   +  
C   S  
Index Entry  Section

*
*alists-are-lists*: Exported special variables
*array-function*: Exported special variables
*get-val-array-function*: Exported special variables
*get-val-function*: Exported special variables
*hash-table-function*: Exported special variables
*plists-are-lists*: Exported special variables
*previous-readtables*: Internal special variables
*reader-macro-activation-functions*: Internal special variables
*set-function*: Exported special variables

+
+reader-macro-doc+: Internal constants

C
Constant, +reader-macro-doc+: Internal constants

S
Special Variable, *alists-are-lists*: Exported special variables
Special Variable, *array-function*: Exported special variables
Special Variable, *get-val-array-function*: Exported special variables
Special Variable, *get-val-function*: Exported special variables
Special Variable, *hash-table-function*: Exported special variables
Special Variable, *plists-are-lists*: Exported special variables
Special Variable, *previous-readtables*: Internal special variables
Special Variable, *reader-macro-activation-functions*: Internal special variables
Special Variable, *set-function*: Exported special variables

Jump to:   *   +  
C   S  

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

A.4 Data types

Jump to:   P   R   S  
Index Entry  Section

P
Package, reader: The reader package

R
reader: The reader system
reader: The reader package

S
System, reader: The reader system

Jump to:   P   R   S