The deferred Reference Manual

Table of Contents

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

The deferred Reference Manual

This is the deferred Reference Manual, version 0.9.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:41:02 2018 GMT+0.


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

1 Introduction

About Deferred

Sometimes I would like to include code in my project that is only available if certain libraries are loaded. Since I don't want to require these libraries as dependencies, but can't refer to their symbols either without them being loaded, things get a bit messy. This library attempts to provide a much more convenient way.

How To

Deferred uses two components: a dispatch reader macro on #^ and two macros, WITH-DEFERRED-LIBRARY or WHEN-PACKAGES. #^ is used to circumvent the reader problem of being unable to refer to symbols in packages that don't exist at read-time. The macro is used to then acquire access to the symbol's environment to figure out the proper transformation for the symbol into proper values.

WITH-DEFERRED-LIBRARY is used to specify deferred libraries that are needed at execution time. Meaning the required library can be loaded only just when the code block is executed.

(with-deferred-library (:drakma)
  (#^http-request "http://google.com"))

Deferred symbols can be used in function calls, with FUNCTION and QUOTE and as values (f.e. special variables). Currently unsupported are deferred SETF functions as it's impossible to properly defer a SETF-expander until execution-time.

If instead you are looking for code that is only compiled when certain libraries are already loaded before yours, there is WHEN-PACKAGES. This macro only outputs code when the specified list of packages can be found, otherwise it expands to NIL. This is useful if you don't want to encounter the edge-cases and performance penalties of WITH-DEFERRED-LIBRARY and can depend on the fact that if the deferred feature is needed, its dependencies are loaded before your system.

(defun frillneckedlizard ()
  (error "NOT IMPLEMENTED!"))

(when-packages (:drakma)
  (defun frillneckedlizard ()
    (#^drakma:http-request "http://frillneckedlizard.moe")))

If the default dispatch reader macro has been overwritten in your readtable for one reason or another, you can use (named-readtables:in-readtable :deferred).


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 deferred

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/deferred/

License

Artistic

Description

A simple library allowing you to write code using deferred libraries.

Version

0.9.0

Dependency

named-readtables

Source

deferred.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 deferred.asd

Location

deferred.asd

Systems

deferred (system)


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

3.1.2 deferred/package.lisp

Parent

deferred (system)

Location

package.lisp

Packages

deferred


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

3.1.3 deferred/deferred.lisp

Dependency

package.lisp (file)

Parent

deferred (system)

Location

deferred.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 deferred

Source

package.lisp (file)

Nickname

org.tymoonnext.deferred

Use List

common-lisp

Exported Definitions
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


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

5.1.1 Special variables

Special Variable: *deferred-package*

The default package to use for deferred symbols.

Package

deferred

Source

deferred.lisp (file)


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

5.1.2 Macros

Macro: when-packages PACKAGES &body BODY

Similar to WITH-DEFERRED-LIBRARY, except to be used to compile optional code.

The macro returns the transformed body if it can find all packages, otherwise NIL.

Package

deferred

Source

deferred.lisp (file)

Macro: with-deferred-library (ASDF-SYSTEM &key PACKAGE IF-NOT-LOADED) &body BODY

Turns the body into one capable of using deferred symbols.

Specifying deferred symbols works just like other symbols, except prefixing them with #^ . If the #^ reader macro has been overwritten in the standard readtable, please use (named-readtables:in-readtable :deferred)

ASDF-SYSTEM — An ASDF system designator.
PACKAGE — A package designator to use as the default package for deferred symbols. IF-NOT-LOADED ::= NIL | :QUICKLOAD | :LOAD | :AUTO | T
NIL will simply skip executing the body if the library has not been loaded. :LOAD will try to use ASDF:LOAD-SYSTEM and :QUICKLISP QL:QUICKLOAD.
:AUTO or T will try to do the right thing by checking for Quicklisp and ASDF presence first. If neither can be found, an error is signalled. If the loading operation fails, a warning is signalled and the body is NOT executed.

The only place I can think of that deferred symbols are currently not supported for is SETF accessors. This is left out since there’s no way to defer SETF-expanders to runtime.
You can still SETF symbol-values (special variables f.e.), but an error is signalled if
a deferred function is used within SETF.

Package

deferred

Source

deferred.lisp (file)


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

5.1.3 Generic functions

Generic Function: process THING

Processes THING to transform all deferred symbols within into their proper representations.

Package

deferred

Source

deferred.lisp (file)

Methods
Method: process THING
Method: process (LIST list)
Generic Function: process-compile THING

Processes THING to transform all deferred symbols within into their proper compile-able representations.

Package

deferred

Source

deferred.lisp (file)

Methods
Method: process-compile THING
Method: process-compile (LIST list)

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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *identifier-symbol*

Symbol used at the beginning of a list to identify a deferred symbol construct. READ-DEFERRED and PROCESS use these to handle the transformations.

Package

deferred

Source

deferred.lisp (file)


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

5.2.2 Functions

Function: read-deferred S A C

Reads a deferred symbol from the reader stream and outputs the appropriate data structure.

Package

deferred

Source

deferred.lisp (file)

Function: terminating-p CHAR

Returns NIL if the character is not considered to be a symbol-terminating character.

Package

deferred

Source

deferred.lisp (file)

Function: transform-token TOKEN-STREAM

Transforms the TOKEN-STREAM into the proper stream, minding the current READTABLE-CASE.

Package

deferred

Source

deferred.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
deferred.asd: The deferred<dot>asd file
deferred/deferred.lisp: The deferred/deferred<dot>lisp file
deferred/package.lisp: The deferred/package<dot>lisp file

F
File, Lisp, deferred.asd: The deferred<dot>asd file
File, Lisp, deferred/deferred.lisp: The deferred/deferred<dot>lisp file
File, Lisp, deferred/package.lisp: The deferred/package<dot>lisp file

L
Lisp File, deferred.asd: The deferred<dot>asd file
Lisp File, deferred/deferred.lisp: The deferred/deferred<dot>lisp file
Lisp File, deferred/package.lisp: The deferred/package<dot>lisp file

Jump to:   D   F   L  

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

A.2 Functions

Jump to:   F   G   M   P   R   T   W  
Index Entry  Section

F
Function, read-deferred: Internal functions
Function, terminating-p: Internal functions
Function, transform-token: Internal functions

G
Generic Function, process: Exported generic functions
Generic Function, process-compile: Exported generic functions

M
Macro, when-packages: Exported macros
Macro, with-deferred-library: Exported macros
Method, process: Exported generic functions
Method, process: Exported generic functions
Method, process-compile: Exported generic functions
Method, process-compile: Exported generic functions

P
process: Exported generic functions
process: Exported generic functions
process: Exported generic functions
process-compile: Exported generic functions
process-compile: Exported generic functions
process-compile: Exported generic functions

R
read-deferred: Internal functions

T
terminating-p: Internal functions
transform-token: Internal functions

W
when-packages: Exported macros
with-deferred-library: Exported macros

Jump to:   F   G   M   P   R   T   W  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*deferred-package*: Exported special variables
*identifier-symbol*: Internal special variables

S
Special Variable, *deferred-package*: Exported special variables
Special Variable, *identifier-symbol*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   D   P   S  
Index Entry  Section

D
deferred: The deferred system
deferred: The deferred package

P
Package, deferred: The deferred package

S
System, deferred: The deferred system

Jump to:   D   P   S