The mstrings Reference Manual

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

The mstrings Reference Manual

This is the mstrings Reference Manual, version 0.1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 06:43:10 2022 GMT+0.

Table of Contents


1 Introduction

Mstrings - Pretty Multliline Strings for Common Lisp

builds.sr.ht status

Mstrings defines a reader macro for strings with a small handful of features to provide visually appealing multiline blocks. An M-string:

When writing strings that take multiple lines, for example an extensive docstring, it feels natural to align them up. However, the Lisp reader will keep all leading whitespace in the string:

* (defun grab-config (use-default)
    (if use-default
        "foo=1
         bar=2
         qux=3"
        (read-file-into-string +config-filepath+)))

* (grab-config t)
"foo=1
         bar=2
         qux=3"

The workaround is to shove all subsequent lines to the beginning of the file, which could appear quite unsightly:

* (defun grab-config (use-default)
    (if use-default
        "foo=1
bar=2
qux=3"
        (read-file-into-string +config-filepath+))

* (grab-config t)
"foo=1
bar=2
qux=3"

M-strings allow a plain method to remove the whitespace while keeping content aligned in the source code:

* (defun grab-config (use-default)
    (if use-default
        #M"foo=1
           bar=2
           qux=3"
        (read-file-into-string +config-filepath+)))

* (grab-config t)
"foo=1
bar=2
qux=3"

Contributions

Any comments, questions, issues, or patches are greatly appreciated! I do my main development on Sourcehut, with a mailing list and issue tracker.

Install and Enable It

M-strings' sole dependency is named-readtables, available on Quicklisp.

Install M-strings locally, until it is added to Quicklisp:

$ cd ~/common-lisp/ # Or wherever you store your systems
$ git clone https://git.sr.ht/~shunter/mstrings

This library uses named readtables to expose the reader:

* (use-package :named-readtables)
* (in-readtable mstrings:mstring-syntax)

* (princ #M"Hello
            World!")
Hello
World!

Features

M-strings trim leading whitespace from lines:

* (princ #M"Hello
            World!")
Hello
World!

M-strings respect escaped characters and keeps them untrimmed:

* (princ #M"keys:
           \  foo: \"apple\"
           \  bar: \"banana\"")
keys:
  foo: "apple"
  bar: "banana"

M-strings concatenates lines together when they're joined by an escaped Newline - useful for very long single-line values:

* (princ #M"NB2HI4DTHIXS653XO4XHS33VOR2WEZJOMNXW\
            2L3XMF2GG2B7OY6WIULXGR3TSV3HLBRVC===")
NB2HI4DTHIXS653XO4XHS33VOR2WEZJOMNXW2L3XMF2GG2B7OY6WIULXGR3TSV3HLBRVC===

By default, M-strings are read in "literal-block mode", where newlines are read as literal newlines. Prefixing a string with a > sets the reader to "folding-block mode", where multiple non-empty lines are folded into one, joined by spaces:

* (princ #M>"The quick brown fox
             jumps over
             the lazy dog.

             Sphinx of black quartz,
             judge my vow!")
The quick brown fox jumps over the lazy dog.
Sphinx of black quartz, judge my vow!

* (princ #M>"Escaped newlines
             \
             still prevent
             \
             line breaks")
Escaped Newlines still prevent line breaks

Shorthand notation: #"..." and #>"..."

The reader macro function understands #"..." and #>"..." as shorthands for #M"..." and #M>"...", respectively. They're defined separately to prevent macro collisions from other systems:

* (in-readtable mstrings:shorthand-mstring-syntax)
* ;; Or, for both shorthand and long-hand:
* (in-readtable mstrings:full-mstring-syntax)

*    #"Literal-block
       Mode"
"Literal-block
Mode"
*    #>"Folding-block
        Mode"
"Folding-block Mode"

Be aware, #" is also used by the string-escape library, and #> is used by Clozure CL 1.2 and later (and therefore elided from the shorthand-mstrings syntax).

API

[Function] mstring-reader stream subchar arg

Reader macro accepts multiline strings. It ignores and warns on any provided arg, and provides a few quality-of-life features depending on the value of subchar:

[Readtable] mstring-syntax

The standard readtable with the longhand mstring syntax:

[Readtable] shorthand-mstring-syntax

The standard readtable with both #" and #> dispatch character pairs bound to mstring-reader:

[Readtable] full-mstring-syntax

The standard readtable with additions from both mstring-syntax and shorthand-mstring-syntax:


2 Systems

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


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

2.1 mstrings

Pretty multiline strings Reader Macro

Author

Samuel Hunter

Contact

~shunter/public-inbox@lists.sr.ht

Home Page

https://sr.ht/~shunter/mstrings/

Source Control

(GIT https://git.sr.ht/~shunter/mstrings/)

Bug Tracker

https://todo.sr.ht/~shunter/mstrings/

License

BSD 3-Clause

Long Description

Mstrings defines a reader macro for strings with a small handful of features to provide visually appealing multiline blocks.

Version

0.1.1

Dependency

named-readtables (system).

Source

mstrings.asd.

Child Component

mstrings.lisp (file).


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   [Contents][Index]

3.1.1 mstrings/mstrings.asd

Source

mstrings.asd.

Parent Component

mstrings (system).

ASDF Systems

mstrings.


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

3.1.2 mstrings/mstrings.lisp

Source

mstrings.asd.

Parent Component

mstrings (system).

Packages

xyz.shunter.mstrings.

Public Interface

mstring-reader (function).

Internals

4 Packages

Packages are listed by definition order.


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

4.1 xyz.shunter.mstrings

Reader macro for friendlier multiline strings

Source

mstrings.lisp.

Nickname

mstrings

Use List

common-lisp.

Public Interface

mstring-reader (function).

Internals

5 Definitions

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


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

5.1 Public Interface


5.1.1 Ordinary functions

Function: mstring-reader (stream subchar arg)

Multiline string reader function to be installed as a dispatching macro character.
It ignores and warns on any provided ARG, and provides a few quality-of-life features depending on the value of SUBCHAR:

- If SUBCHAR is #\", it is always literal-block mode (‘#M"..."‘) and reads the rest of the string.
- If SUBCHAR is #\>, it is always folding-block mode (‘#M>"..."‘).
- If SUBCHAR is anything else, it reverts to its default behavior: it assumes literal-block mode unless there is a greater-than-sign preceding the string, in which case it switches to folding-block mode.

Package

xyz.shunter.mstrings.

Source

mstrings.lisp.


5.2 Internals


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

5.2.1 Macros

Macro: do@ (varlist endlist &body body)

Anaphoric DO. An @ in the then-form replays the init-form.

Package

xyz.shunter.mstrings.

Source

mstrings.lisp.


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

5.2.2 Ordinary functions

Function: peek-char! (peek-type stream)
Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: read-char! (stream)
Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: read-folding-mstring (stream)
Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: read-line-until-delim (stream out)

Read mstring contets from STREAM until a Newline or string delimiter ".
Read from STREAM until it consumes a Newline or reaches the string delimiter ", and write to OUT. Escaped quotes and whitespaces are treated as a non-whitespace character.

Returns two values:
- Whether there should be a linebreak at the block mode’s discretion;
- Whether it has written any contents to OUT.

Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: read-literal-mstring (stream)
Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: skip-empty-lines (stream out)

Skip all lines that contain only unescaped whitespaces, and write them out as a singular Newline. Return whether any newlines were written.

Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: skip-spaces (stream)

Skip until the first Newline or non-whitespace character and return it, unconsumed.

Package

xyz.shunter.mstrings.

Source

mstrings.lisp.

Function: whitespacep (c)
Package

xyz.shunter.mstrings.

Source

mstrings.lisp.


Appendix A Indexes


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

A.1 Concepts


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

A.3 Variables