The cl-heredoc Reference Manual

Table of Contents

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 2.4 "Will Decker" on Wed Jun 20 11:10:31 2018 GMT+0.


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

1 Introduction

cl-heredoc - Common Lisp reader heredoc dispatcher
==================================================
cl-heredoc is an implementation of "here documents" [1] 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+[2]. Please see the file COPYING in the top-level directory of the
distribution tarball or see the link at [2] 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

[1] http://en.wikipedia.org/wiki/Here_document
[2] http://www.gnu.org/licenses/gpl-3.0-standalone.html


--------------------------------------------------------------------------------
Copyright (C) 2009, 2010  Alexander Kahl 
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 .


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 cl-heredoc

Author

Alexander Kahl <e-user@fsfe.org>

License

GPLv3+

Description

Common Lisp reader heredoc dispatcher

Version

0.1.0

Source

cl-heredoc.asd (file)

Component

src (module)


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

3 Modules

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


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

3.1 cl-heredoc/src

Parent

cl-heredoc (system)

Location

src/

Components

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

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

4.1.1 cl-heredoc.asd

Location

cl-heredoc.asd

Systems

cl-heredoc (system)

Packages

cl-heredoc-system


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

4.1.2 cl-heredoc/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-heredoc


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

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

Dependency

package.lisp (file)

Parent

src (module)

Location

src/ring-buffer.lisp

Internal Definitions

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

4.1.4 cl-heredoc/src/heredoc.lisp

Dependency

ring-buffer.lisp (file)

Parent

src (module)

Location

src/heredoc.lisp

Exported Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 cl-heredoc-system

Source

cl-heredoc.asd

Use List

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

5.2 cl-heredoc

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 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 (file)

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 (file)


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

6.2 Internal definitions


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

6.2.1 Functions

Function: copy-ring-buffer INSTANCE
Package

cl-heredoc

Source

ring-buffer.lisp (file)

Function: make-ring-buffer &key (VECTOR VECTOR) (START START) (USED USED) (NEW NEW) (END END)
Package

cl-heredoc

Source

ring-buffer.lisp (file)

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 (file)

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 (file)

Writer

(setf rbref) (function)

Function: (setf rbref) VALUE 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 (file)

Reader

rbref (function)

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 (file)

Function: ring-buffer-end INSTANCE
Function: (setf ring-buffer-end) VALUE INSTANCE
Package

cl-heredoc

Source

ring-buffer.lisp (file)

Function: ring-buffer-flush BUFFER

ring-buffer-flush buffer => string

Flush all unused characters in BUFFER.

Package

cl-heredoc

Source

ring-buffer.lisp (file)

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 (file)

Function: ring-buffer-new INSTANCE
Function: (setf ring-buffer-new) VALUE INSTANCE
Package

cl-heredoc

Source

ring-buffer.lisp (file)

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 (file)

Function: ring-buffer-p OBJECT
Package

cl-heredoc

Source

ring-buffer.lisp (file)

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 (file)

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 (file)

Function: ring-buffer-start INSTANCE
Function: (setf ring-buffer-start) VALUE INSTANCE
Package

cl-heredoc

Source

ring-buffer.lisp (file)

Function: ring-buffer-used INSTANCE
Function: (setf ring-buffer-used) VALUE INSTANCE
Package

cl-heredoc

Source

ring-buffer.lisp (file)

Function: ring-buffer-vector INSTANCE
Function: (setf ring-buffer-vector) VALUE INSTANCE
Package

cl-heredoc

Source

ring-buffer.lisp (file)


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

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 (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: vector
Readers

ring-buffer-vector (function)

Writers

(setf ring-buffer-vector) (function)

Slot: start
Initform

-1

Readers

ring-buffer-start (function)

Writers

(setf ring-buffer-start) (function)

Slot: used
Initform

-1

Readers

ring-buffer-used (function)

Writers

(setf ring-buffer-used) (function)

Slot: new
Initform

-1

Readers

ring-buffer-new (function)

Writers

(setf ring-buffer-new) (function)

Slot: end
Initform

-1

Readers

ring-buffer-end (function)

Writers

(setf ring-buffer-end) (function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-heredoc.asd: The cl-heredoc<dot>asd file
cl-heredoc/src: The cl-heredoc/src module
cl-heredoc/src/heredoc.lisp: The cl-heredoc/src/heredoc<dot>lisp file
cl-heredoc/src/package.lisp: The cl-heredoc/src/package<dot>lisp file
cl-heredoc/src/ring-buffer.lisp: The cl-heredoc/src/ring-buffer<dot>lisp file

F
File, Lisp, cl-heredoc.asd: The cl-heredoc<dot>asd file
File, Lisp, cl-heredoc/src/heredoc.lisp: The cl-heredoc/src/heredoc<dot>lisp file
File, Lisp, cl-heredoc/src/package.lisp: The cl-heredoc/src/package<dot>lisp file
File, Lisp, cl-heredoc/src/ring-buffer.lisp: The cl-heredoc/src/ring-buffer<dot>lisp file

L
Lisp File, cl-heredoc.asd: The cl-heredoc<dot>asd file
Lisp File, cl-heredoc/src/heredoc.lisp: The cl-heredoc/src/heredoc<dot>lisp file
Lisp File, cl-heredoc/src/package.lisp: The cl-heredoc/src/package<dot>lisp file
Lisp File, cl-heredoc/src/ring-buffer.lisp: The cl-heredoc/src/ring-buffer<dot>lisp file

M
Module, cl-heredoc/src: The cl-heredoc/src module

Jump to:   C   F   L   M  

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

A.2 Functions

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

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

C
copy-ring-buffer: Internal functions

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

M
make-ring-buffer: Internal functions

N
new-ring-buffer: Internal functions

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

Jump to:   (  
C   F   M   N   R  

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

A.3 Variables

Jump to:   E   N   S   U   V  
Index Entry  Section

E
end: Internal structures

N
new: Internal structures

S
Slot, end: Internal structures
Slot, new: Internal structures
Slot, start: Internal structures
Slot, used: Internal structures
Slot, vector: Internal structures
start: Internal structures

U
used: Internal structures

V
vector: Internal structures

Jump to:   E   N   S   U   V  

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

A.4 Data types

Jump to:   C   P   R   S  
Index Entry  Section

C
cl-heredoc: The cl-heredoc system
cl-heredoc: The cl-heredoc package
cl-heredoc-system: The cl-heredoc-system package

P
Package, cl-heredoc: The cl-heredoc package
Package, cl-heredoc-system: The cl-heredoc-system package

R
ring-buffer: Internal structures

S
Structure, ring-buffer: Internal structures
System, cl-heredoc: The cl-heredoc system

Jump to:   C   P   R   S