The cl-heredoc Reference Manual

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

The cl-heredoc Reference Manual

This is the cl-heredoc Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 04:48:50 2022 GMT+0.

Table of Contents


1 Introduction

cl-heredoc - Common Lisp reader heredoc dispatcher

cl-heredoc is an implementation of "here documents" that allow the user to embed literal strings into code or data without any need for quoting, something that is missing in both ANSI CL and popular implementations.

cl-heredoc is completely written in Common Lisp and licensed under the GPLv3+. Please see the file COPYING in the top-level directory of the distribution tarball or the online version if you didn't receive a copy along with this file.

Usage

cl-heredoc primarily exports a single function, READ-HEREDOC, that is meant to be used with the CL reader by attaching it to a dispatch character, e.g.

CL-USER> (set-dispatch-macro-character #\# #\> #'cl-heredoc:read-heredoc)
CL-USER> #>eof>Write whatever (you) "want",
  no matter how many lines or what characters until
the magic end sequence has been reached!eof

Will read everything starting after #>eof> until the given sequence, here eof, is found and return the result as a string. The enclosed text is not subject to any kind of evaluation and needs no quoting.
If used in a non-interactive fashion, i.e. outside the REPL, an error will be signaled if EOF is reached.

The underlying function READ-UNTIL-MATCH may also be used directly: It takes two arguments, a stream and a termination string and will read from the stream until the terminating sequence is found. Everything read so far excluding the terminator is returned as a string.

Links and References

Homepage: http://www.cliki.net/cl-heredoc
Hacking: http://github.com/e-user/cl-heredoc

Copyright (C) 2009, 2010 Alexander Kahl e-user@fsfe.org This file is part of cl-heredoc. cl-heredoc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

cl-heredoc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.


2 Systems

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


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

2.1 cl-heredoc

Common Lisp reader heredoc dispatcher

Author

Alexander Kahl <e-user@fsfe.org>

License

GPLv3+

Version

0.1.0

Source

cl-heredoc.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 cl-heredoc/src

Source

cl-heredoc.asd.

Parent Component

cl-heredoc (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


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

4.1 Lisp


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

4.1.1 cl-heredoc/cl-heredoc.asd

Source

cl-heredoc.asd.

Parent Component

cl-heredoc (system).

ASDF Systems

cl-heredoc.


4.1.2 cl-heredoc/src/package.lisp

Source

cl-heredoc.asd.

Parent Component

src (module).

Packages

cl-heredoc.


4.1.3 cl-heredoc/src/ring-buffer.lisp

Dependency

package.lisp (file).

Source

cl-heredoc.asd.

Parent Component

src (module).

Internals

4.1.4 cl-heredoc/src/heredoc.lisp

Dependency

ring-buffer.lisp (file).

Source

cl-heredoc.asd.

Parent Component

src (module).

Public Interface

5 Packages

Packages are listed by definition order.


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

5.1 cl-heredoc

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


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

6.1 Public Interface


6.1.1 Ordinary functions

Function: read-heredoc (stream char arg)

read-heredoc stream char arg => string

Return string from STREAM up to the point where the string read first until CHAR is encountered. All evaluation is completely turned off so no quoting is required at all.
Example:
CL-USER> (set-dispatch-macro-character ## #> #’cl-heredoc:read-heredoc) CL-USER> #>eof>Write whatever (you) "want"!eof => Write whatever (you) "want"!

Package

cl-heredoc.

Source

heredoc.lisp.

Function: read-until-match (stream terminal)

read-until-match stream terminal => string

Read characters from STREAM until a sequence equal to string TERMINAL is read. Return all characters read as string omitting TERMINAL itself. Signal error upon EOF.

Package

cl-heredoc.

Source

heredoc.lisp.


6.2 Internals


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

6.2.1 Ordinary functions

Function: copy-ring-buffer (instance)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: make-ring-buffer (&key vector start used new end)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: new-ring-buffer (length)

new-ring-buffer length => ring-buffer

Create a new RING-BUFFER containing a simple character vector of fixed size LENGTH.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: rbref (buffer index)

rbref buffer index => character or #Nul

Return character stored at INDEX in ring BUFFER.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: (setf rbref) (buffer index)

setf (rbref buffer index) value => value

SETF for RBREF. If INDEX > LENGTH of BUFFER, start over at the beginning.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: ring-buffer-clear (buffer)

ring-buffer-clear buffer => -1

Reset all indices of BUFFER to their initial state.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Reader: ring-buffer-end (instance)
Writer: (setf ring-buffer-end) (instance)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Target Slot

end.

Function: ring-buffer-flush (buffer)

ring-buffer-flush buffer => string

Flush all unused characters in BUFFER.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: ring-buffer-insert (buffer value)

ring-buffer-insert buffer value => value

Increment END of BUFFER inserting VALUE at the new index.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Reader: ring-buffer-new (instance)
Writer: (setf ring-buffer-new) (instance)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Target Slot

new.

Function: ring-buffer-next (buffer)

ring-buffer-next buffer => character or nil

Return next match character incrementing USED in BUFFER or simply NIL if none are left.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: ring-buffer-p (object)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: ring-buffer-pop (buffer)

ring-buffer-pop buffer => character

Increment START of BUFFER returning VALUE at the new index. Additionally, reset the BUFFER match indices.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Function: ring-buffer-reset (buffer)

ring-buffer-reset buffer => end-index

Reset match beginning/end indices USED and NEW in BUFFER to START and END.

Package

cl-heredoc.

Source

ring-buffer.lisp.

Reader: ring-buffer-start (instance)
Writer: (setf ring-buffer-start) (instance)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Target Slot

start.

Reader: ring-buffer-used (instance)
Writer: (setf ring-buffer-used) (instance)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Target Slot

used.

Reader: ring-buffer-vector (instance)
Writer: (setf ring-buffer-vector) (instance)
Package

cl-heredoc.

Source

ring-buffer.lisp.

Target Slot

vector.


6.2.2 Structures

Structure: ring-buffer

Structure defining ring buffers utilizing a simple VECTOR of fixed size and four indices:
START: Index of first live value
END: Index of last live value
USED: Beginning of current match
NEW: End of current match

Package

cl-heredoc.

Source

ring-buffer.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: vector
Package

common-lisp.

Readers

ring-buffer-vector.

Writers

(setf ring-buffer-vector).

Slot: start
Initform

-1

Readers

ring-buffer-start.

Writers

(setf ring-buffer-start).

Slot: used
Initform

-1

Readers

ring-buffer-used.

Writers

(setf ring-buffer-used).

Slot: new
Initform

-1

Readers

ring-buffer-new.

Writers

(setf ring-buffer-new).

Slot: end
Initform

-1

Readers

ring-buffer-end.

Writers

(setf ring-buffer-end).


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

Jump to:   (  
C   F   M   N   R  
Index Entry  Section

(
(setf rbref): Private ordinary functions
(setf ring-buffer-end): Private ordinary functions
(setf ring-buffer-new): Private ordinary functions
(setf ring-buffer-start): Private ordinary functions
(setf ring-buffer-used): Private ordinary functions
(setf ring-buffer-vector): Private ordinary functions

C
copy-ring-buffer: Private ordinary functions

F
Function, (setf rbref): Private ordinary functions
Function, (setf ring-buffer-end): Private ordinary functions
Function, (setf ring-buffer-new): Private ordinary functions
Function, (setf ring-buffer-start): Private ordinary functions
Function, (setf ring-buffer-used): Private ordinary functions
Function, (setf ring-buffer-vector): Private ordinary functions
Function, copy-ring-buffer: Private ordinary functions
Function, make-ring-buffer: Private ordinary functions
Function, new-ring-buffer: Private ordinary functions
Function, rbref: Private ordinary functions
Function, read-heredoc: Public ordinary functions
Function, read-until-match: Public ordinary functions
Function, ring-buffer-clear: Private ordinary functions
Function, ring-buffer-end: Private ordinary functions
Function, ring-buffer-flush: Private ordinary functions
Function, ring-buffer-insert: Private ordinary functions
Function, ring-buffer-new: Private ordinary functions
Function, ring-buffer-next: Private ordinary functions
Function, ring-buffer-p: Private ordinary functions
Function, ring-buffer-pop: Private ordinary functions
Function, ring-buffer-reset: Private ordinary functions
Function, ring-buffer-start: Private ordinary functions
Function, ring-buffer-used: Private ordinary functions
Function, ring-buffer-vector: Private ordinary functions

M
make-ring-buffer: Private ordinary functions

N
new-ring-buffer: Private ordinary functions

R
rbref: Private ordinary functions
read-heredoc: Public ordinary functions
read-until-match: Public ordinary functions
ring-buffer-clear: Private ordinary functions
ring-buffer-end: Private ordinary functions
ring-buffer-flush: Private ordinary functions
ring-buffer-insert: Private ordinary functions
ring-buffer-new: Private ordinary functions
ring-buffer-next: Private ordinary functions
ring-buffer-p: Private ordinary functions
ring-buffer-pop: Private ordinary functions
ring-buffer-reset: Private ordinary functions
ring-buffer-start: Private ordinary functions
ring-buffer-used: Private ordinary functions
ring-buffer-vector: Private ordinary functions

Jump to:   (  
C   F   M   N   R