The pythonic-string-reader Reference Manual

Table of Contents

The pythonic-string-reader Reference Manual

This is the pythonic-string-reader Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 12:14:56 2021 GMT+0.

1 Introduction

* Pythonic String Reader

This is a piece of code stolen from Yury Sulsky which has been slightly
modified/improved by myself.  It sets up some reader macros that make it simpler
to input string literals which contain backslashes and double quotes.  This is
very useful for writing complicated docstrings and, as it turns out, writing
code that contains string literals that contain code themselves.

** Enabling the syntax

Pythonic String Reader is implemented using modern read-table management
libraries like Named Readtables, so it should be even more unintrusive than it
was originally designed.

To use the this read macro, you can simply use the readtable
=pythonic-string-syntax= in the package by putting the following at the
beginning of your files:

#+begin_src lisp
(in-readtable pythonic-string-syntax)
#+end_src

Or use any of the ways Named Readtables allows you to define and combine
readtables, for instance:

#+begin_src lisp
(defreadtable my-readtable
  (:merge :standard)
  (:merge pythonic-string-syntax))
#+end_src

... or ...

#+begin_src lisp
(defreadtable my-readtable
  (:merge :standard)
  (:macro-char #\" #'pythonic-string-reader::read-multiline-string t))

(in-readtable my-readtable)
#+end_src

*** I don't want to use Named Readtables

To enable the reader syntax, run =enable-pythonic-string-syntax= and to disable
use =disable-pythonic-string-syntax=.

** Usage

The string reader will treat any bit of code that contains three consecutive
double quotes specially.  If it finds three consecutive double quotes, it will
start reading and won't stop until it finds another three consecutive double
quotes.  All text in between is taken as literal.  It is impossible to escape
anything.

As an extension, if the reader finds four consecutive double quotes (i.e. it
finds the opening three double quotes, then finds one more immediately after
those), it will do the same as above, except it will not end until it reaches
another four consecutive double quotes.  This is particularly useful if you want
to trick your text editor into treating the string you are writing as normal
code instead of a string.

*** Examples

Note that in these examples I still balance quotes.  This is needed so that
Slime doesn't get confused and think there is still input to be had.  This is
not the case when code is loaded or compiled using the =load= or =compile-file=
commands (which is what users will experience).

#+begin_src
CL-USER> """ hello\ """
" hello\\ "
CL-USER> """ hello\ """" "
" "
CL-USER> """hello"""
"hello"
CL-USER> """ \ """
" \\ "
CL-USER> """ " " """
" \" \" "
CL-USER> """" hello """"
" hello "
CL-USER> """" hello """ " """"
" hello \"\"\" \" "
#+end_src

** TODO

Perhaps I will integrate with CL-Syntactic-Sugar in the future, as that used to
be a way to wrangle all of these reader macros in a sane way.  I feel like
Named-Readtables has accomplished this in a cleaner way though.

2 Systems

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

2.1 pythonic-string-reader

Maintainer

Zach Kost-Smith <zachkostsmith@gmail.com>

Author

Yury Sulsky and Zach Kost-Smith

Description

A simple and unintrusive read table modification that allows for simple string literal definition that doesn’t require escaping characters.

Dependency

named-readtables

Source

pythonic-string-reader.asd (file)

Component

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

Location

pythonic-string-reader.asd

Systems

pythonic-string-reader (system)

3.1.2 pythonic-string-reader/pythonic-string-reader.lisp

Parent

pythonic-string-reader (system)

Location

pythonic-string-reader.lisp

Packages

pythonic-string-reader

Exported Definitions

• disable-pythonic-string-syntax (function)
• enable-pythonic-string-syntax (function)

Internal Definitions

read-multiline-string (function)

4 Packages

Packages are listed by definition order.

4.1 pythonic-string-reader

Source

pythonic-string-reader.lisp (file)

Use List

• editor-hints.named-readtables
• common-lisp

Exported Definitions

• disable-pythonic-string-syntax (function)
• enable-pythonic-string-syntax (function)

Internal Definitions

read-multiline-string (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: disable-pythonic-string-syntax ()

Package

pythonic-string-reader

Source

pythonic-string-reader.lisp (file)

Function: enable-pythonic-string-syntax ()

Package

pythonic-string-reader

Source

pythonic-string-reader.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: read-multiline-string STREAM C

Package

pythonic-string-reader

Source

pythonic-string-reader.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types