The named-read-macros Reference Manual

Table of Contents

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

The named-read-macros Reference Manual

This is the named-read-macros Reference Manual, version 1.0.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:20:58 2018 GMT+0.


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

1 Introduction

NAMED-READ-MACROS License Build Status Coverage Status

Copyright (c) 2017 William Yao

Description

Read macros are pretty handy when Lispy sexps just don't cut it. Unfortunately, having to hunt around in the dispatch table or in the read macro table to avoid read macro collisions doesn't leave a whole bunch of usable characters. So instead, NAMED-READ-MACROS lets you attach a read macro to any symbol, and call it like any other function or macro.

(named-readtables:in-readtable named-read-macros:readtable)

(named-read-macros:define escapify
  (with-output-to-string (output)
    (loop for char = (read-char *standard-input* nil nil t)
          while char
          do (write-char char output))))

(escapify
  Any characters I put in here will be put into the output string, even
  things that would normally require escapes, like backslashes!

  \ \ \ \
end-escapify)
 => "Any characters I put in here will be put into the output string, even
       things that would normally require escapes, like backslashes!

       \\ \\ \\ \\"

You can hijack the Lisp reader without having to carefully avoid read macro conflicts! And since NAMED-READ-MACROS attaches read macros to symbols, you don't have to fuss about with readtables either, and you can export and import read macros the same way you do with functions and macros and all the other symbol-based stuff.

Usage

For any file which needs to use your named read macros, make sure to either switch your readtable to NAMED-READ-MACROS:READTABLE, or fuse a read table you're using with NAMED-READ-MACROS:READTABLE-MIXIN.

Then define a named read macro with NAMED-READ-MACROS:DEFINE.

Going forward

An interesting usage would be to write an LALR(1) parser generator for Common Lisp, but instead of generating a function or a standalone executable, it instead generates read macros. Any parsers generated could then be embedded directly within Lisp code, allowing for very complex read macros to be easily written, and compile directly to Lisp forms.

Another use would be something like Perl's __DATA__ directive, embedding files and data directly in Lisp code.


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 named-read-macros

Maintainer

William Yao <williamyaoh@gmail.com>

Author

William Yao <williamyaoh@gmail.com>

License

BSD-3

Description

Make read macros more Lispy. Attach read macros to symbols.

Long Description

Provide a definition facility to define read macros and attach them to symbols, avoiding the possibility of collisions in readtable characters.

Version

1.0.0

Dependency

named-readtables

Source

named-read-macros.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 named-read-macros.asd

Location

named-read-macros.asd

Systems

named-read-macros (system)


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

3.1.2 named-read-macros/packages.lisp

Parent

named-read-macros (system)

Location

packages.lisp

Packages

named-read-macros


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

3.1.3 named-read-macros/named-read-macros.lisp

Dependency

packages.lisp (file)

Parent

named-read-macros (system)

Location

named-read-macros.lisp

Exported Definitions

define (macro)

Internal Definitions

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

3.1.4 named-read-macros/readtables.lisp

Dependency

named-read-macros.lisp (file)

Parent

named-read-macros (system)

Location

readtables.lisp


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

4 Packages

Packages are listed by definition order.


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

4.1 named-read-macros

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions

define (macro)

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


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

5.1.1 Macros

Macro: define NAME &body BODY

Creates a named read macro, which executes ‘BODY‘ in a context where ‘*STANDARD-INPUT*‘ is bound to a stream containing just the contents which the read macro was called with, and associates this macro with ‘NAME‘.

Just like a normal macro, ‘BODY‘ should return a Lisp form to then get evaluated where the named read macro was called.

Because ‘NAMED-READ-MACROS‘ hijacks the Lisp reader, we can’t rely on matching parentheses to know when the newly-defined read macro *ends*, so we look for the sequence of characters ‘’END-${NAME}’‘, *immediately* followed by a close parenthesis, in order to know when the read macro ends. Case is checked against ‘NAME‘ by transforming the ending string according to the case of the current readtable; if ‘(SYMBOL-NAME NAME)‘ matches the transformed ending string exactly, we’ve found the end tag. In particular, this means that using ‘DEFINE‘ with a pipe-enclosed symbol with lowercase characters will make such a read macro impossible to end under the standard readtable (though why one would define such a macro is another question entirely!)

Leading whitespace after opening the read macro will not be passed to ‘BODY‘, but trailing whitespace before the ending tag will.

Note that ‘DEFINE‘ has no compile-time effects by default; the rationale is that doing so would also require any functions used by a read macro defined by ‘DEFINE‘ to be available at compile-time. Since this is not the usual, ‘DEFINE‘ explicitly has no compile-time effects to avoid this problem. If you want a named read macro to be available at compile-time, wrap ‘DEFINE‘ and any necessary functions in an explicit ‘EVAL-WHEN‘.

Package

named-read-macros

Source

named-read-macros.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Functions

Function: check-if-bound SYMB
Package

named-read-macros

Source

named-read-macros.lisp (file)

Function: read-maybe-read-macro STREAM &optional CHAR
Package

named-read-macros

Source

named-read-macros.lisp (file)

Function: read-string-end STREAM SYMBOL
Package

named-read-macros

Source

named-read-macros.lisp (file)

Function: readtable-case-transform-fn &optional READTABLE

Return a function which will transform any string per the given readtable’s case-sensitivity.

Package

named-read-macros

Source

named-read-macros.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   N  
Index Entry  Section

F
File, Lisp, named-read-macros.asd: The named-read-macros<dot>asd file
File, Lisp, named-read-macros/named-read-macros.lisp: The named-read-macros/named-read-macros<dot>lisp file
File, Lisp, named-read-macros/packages.lisp: The named-read-macros/packages<dot>lisp file
File, Lisp, named-read-macros/readtables.lisp: The named-read-macros/readtables<dot>lisp file

L
Lisp File, named-read-macros.asd: The named-read-macros<dot>asd file
Lisp File, named-read-macros/named-read-macros.lisp: The named-read-macros/named-read-macros<dot>lisp file
Lisp File, named-read-macros/packages.lisp: The named-read-macros/packages<dot>lisp file
Lisp File, named-read-macros/readtables.lisp: The named-read-macros/readtables<dot>lisp file

N
named-read-macros.asd: The named-read-macros<dot>asd file
named-read-macros/named-read-macros.lisp: The named-read-macros/named-read-macros<dot>lisp file
named-read-macros/packages.lisp: The named-read-macros/packages<dot>lisp file
named-read-macros/readtables.lisp: The named-read-macros/readtables<dot>lisp file

Jump to:   F   L   N  

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

A.2 Functions

Jump to:   C   D   F   M   R  
Index Entry  Section

C
check-if-bound: Internal functions

D
define: Exported macros

F
Function, check-if-bound: Internal functions
Function, read-maybe-read-macro: Internal functions
Function, read-string-end: Internal functions
Function, readtable-case-transform-fn: Internal functions

M
Macro, define: Exported macros

R
read-maybe-read-macro: Internal functions
read-string-end: Internal functions
readtable-case-transform-fn: Internal functions

Jump to:   C   D   F   M   R  

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

A.3 Variables


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

A.4 Data types

Jump to:   N   P   S  
Index Entry  Section

N
named-read-macros: The named-read-macros system
named-read-macros: The named-read-macros package

P
Package, named-read-macros: The named-read-macros package

S
System, named-read-macros: The named-read-macros system

Jump to:   N   P   S