The reader Reference Manual

Table of Contents

The reader Reference Manual

This is the reader Reference Manual, version 0.9.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Apr 28 12:50:31 2020 GMT+0.

1 Introduction

Examples

(named-readtables:in-readtables reader:reader) ; not recommended with slime
;;  OR 
(reader:enable-reader-syntax &rest reader-macro-identifiers) ; check (describe)
;; another way, until SLIME allows changing readtables more than twice
;; (disable-reader-syntax) ; is complementary

CL-USER> (mapcar λ(write-to-string -) '(2 3 4)) ; lambdas
("2" "3" "4")
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> (let ((arr #2A((1 2 3) (4 5 6))))      ; arrays are unsimplified by default
           [arr t 0])                           ; and numcl:aref is used
#(1 4)                                          ; see reader:*automatically-unsimplify-array*
CL-USER> [{"a" 1 "b" 2} "a"]                    ; accessors
1
T
CL-USER> [(cl-json:decode-json-from-string "{\"a\":1, \"b\":2}") :b]
2                                               ; works with alists
CL-USER> (-> {"a" "apple" "b" "ball"} ["b"] [1]); accessors can be chained using arrow-macros:->
#\a                                             ; arrow-macros is not included
CL-USER> #!echo -n hello world                  ; execute shell commands 
hello world                                     ; using uiop:run-program
NIL                                             ; not intended for using variables
NIL
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:
      LAMBDA, GET-VAL, HASH-TABLE, NOT, STRING, DESCRIBE, ARRAY, HASH-SET, RUN-PROGRAM
  Source file: /home/user/portacle/projects/reader/reader.lisp

See reader-test.lisp for more examples.

Notes

• {"a" 1 "b" 2} - hash tables use 'equal as the default test. The intended test function (one of (:eq :eql :equalp :equal) can be specified as the first element of the literal syntax; conversely, these cannot be used as the first keys of the hash table. Besides providing with a choice, this also gets the indentation correct (see Modification for emacs.
• (setf [] ...) does not work with alists and plists. Modifying alists and plists destructively would likely require compiler macros.
• λ can take up to 3 arguments, and the remaining are captured by &rest args. Further, an optional integer (from 0 to 3 both inclusive) can be put in front of λ to indicate the number of arguments before &rest args: (λ2(identity args) 1 2 3 4) => (3 4) vs (λ(identity args) 1 2 3 4) => (1 2 3 4)
• [...] (get-val) does not work inside #[...] (array) syntax. I do not have a plan or haven't figured out how to combine the two; and I find that okay since the array syntax is meant for cleaner representation in works involving matrices.

Testing

(ql:quickload :reader-test)
(reader-test:run)

Modifications for emacs

(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

I'm aware of the lambda syntax in rutils and clojure. However, emacs seems to treat ^ specially and something like (member ?\^ '(?\^)) gives an "End of file during parsing" error. This is an issue with the modification marked ; for inserting lambda. Regarding - instead of %1: the former is easier to type than the latter. The λ() can take up to 3 (optional) arguments - -- ---.

• cl-interpol is a prominent library providing perl / shell-like string interpolation facilities.
• cl-json can be used for parsin

2 Systems

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

2.1 reader

Author

Shubhamkar Ayare (shubhamayare@yahoo.co.in)

License

MIT

Description

A utility library intended at providing reader macros for lambda, get-val, hash-table, not, string, describe, array, hash-set and run-program.

Version

0.9.1

Dependencies

• iterate
• named-readtables
• hash-set
• alexandria
• trivial-types
• select
• str
• uiop

Source

reader.asd (file)

Component

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

Location

reader.asd

Systems

reader (system)

3.1.2 reader/reader.lisp

Parent

reader (system)

Location

reader.lisp

Packages

reader

Exported Definitions

• disable-reader-syntax (macro)
• enable-reader-syntax (macro)
• get-val (generic function)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• (setf get-val) (method)

Internal Definitions

• %disable-reader-syntax (function)
• %enable-reader-syntax (function)
• *previous-readtables* (special variable)
• array-reader-macro (function)
• construct-parameter-list (function)
• defmethods-with-setf (macro)
• describe-reader-macro (function)
• get-val-reader-macro (function)
• hash-set-reader-macro (function)
• hash-table-reader-macro (function)
• lambda-reader-macro (function)
• not-reader-macro (function)
• read-array (function)
• read-row-from-string (function)
• read-stream-as-string-until (function)
• read-stream-until (function)
• run-program-reader-macro (function)
• string-reader-macro (function)

4 Packages

Packages are listed by definition order.

4.1 reader

Source

reader.lisp (file)

Use List

• hash-set
• iterate
• common-lisp
• editor-hints.named-readtables

Exported Definitions

• disable-reader-syntax (macro)
• enable-reader-syntax (macro)
• get-val (generic function)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• get-val (method)
• (setf get-val) (method)
• (setf get-val) (generic function)
• (setf get-val) (method)

Internal Definitions

• %disable-reader-syntax (function)
• %enable-reader-syntax (function)
• *previous-readtables* (special variable)
• array-reader-macro (function)
• construct-parameter-list (function)
• defmethods-with-setf (macro)
• describe-reader-macro (function)
• get-val-reader-macro (function)
• hash-set-reader-macro (function)
• hash-table-reader-macro (function)
• lambda-reader-macro (function)
• not-reader-macro (function)
• read-array (function)
• read-row-from-string (function)
• read-stream-as-string-until (function)
• read-stream-until (function)
• run-program-reader-macro (function)
• string-reader-macro (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: 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:
LAMBDA, GET-VAL, HASH-TABLE, NOT, STRING, DESCRIBE, ARRAY, HASH-SET, RUN-PROGRAM

Package

reader

Source

reader.lisp (file)

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

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *previous-readtables*

Package

reader

Source

reader.lisp (file)

5.2.2 Macros

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

Package

reader

Source

reader.lisp (file)

5.2.3 Functions

Function: %disable-reader-syntax ()

Package

reader

Source

reader.lisp (file)

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

Package

reader

Source

reader.lisp (file)

Function: array-reader-macro STREAM CHAR N

Package

reader

Source

reader.lisp (file)

Function: construct-parameter-list BODY MAY-BE-BODY

Package

reader

Source

reader.lisp (file)

Function: describe-reader-macro STREAM CHAR

Package

reader

Source

reader.lisp (file)

Function: get-val-reader-macro STREAM CHAR

Package

reader

Source

reader.lisp (file)

Function: hash-set-reader-macro STREAM CHAR N

Package

reader

Source

reader.lisp (file)

Function: hash-table-reader-macro STREAM CHAR

Package

reader

Source

reader.lisp (file)

Function: lambda-reader-macro STREAM CHAR

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: string-reader-macro STREAM CHAR

Package

reader

Source

reader.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types