Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the transparent-wrap Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:40:44 2018 GMT+0.
• Introduction: | What transparent-wrap is all about | |
• Systems: | The systems documentation | |
• Modules: | The modules documentation | |
• Files: | The files documentation | |
• Packages: | The packages documentation | |
• Definitions: | The symbols documentation | |
• Indexes: | Concepts, functions, variables and data types |
This is a small utility for generating wrapper functions that have the same signature as the functions they wrap so that you can still interactively see the same function signature in the SLIME minibuffer. (It also offers the same feature for macros, which is not quite as difficult but is included for completeness' sake.)
When using lispbuilder-sdl
on SBCL, you may encounter all kinds of floating point errors, but you don't want to disable those errors globally - you want to do your own math before calling out to foreign functions. In that case you can do something like this:
(defpackage :sdl-wrap
(:use :cl)
#.`(:export
,@(loop for symbol being the external-symbols of :sdl
when (and (fboundp symbol)
(eql (symbol-package symbol) (find-package :sdl)))
collect symbol)))
#.`(progn
,@(loop for symbol being the external-symbols of :sdl
when (and (fboundp symbol)
(eql (symbol-package symbol) (find-package :sdl)))
collect
(transparent-wrap:create-transparent-defun
symbol
(lambda (real-function-call)
`(sb-int:with-float-traps-masked (:invalid :overflow :divide-by-zero)
,real-function-call))
:sdl-wrap)))
and fix it without having to massively edit the package's source code or your client code. Just import the wrapper package instead. Now you can get the functionality you need and see that sdl-wrap:draw-string-solid-*
has the signature (string x y &key (justify :left) (surface lispbuilder-sdl:*default-surface*) (font lispbuilder-sdl:*default-font*) (color lispbuilder-sdl:*default-color*))
without manually searching for it!
;; function
(create-transparent-defun 'package:function
(lambda (code)
`(wrap ,code))
:wrapping-package)
(defmacro wrapper (code)
`(wrap ,code))
;; macro
(transparent-defun package:function wrapper :wrapping-package)
;; function
(create-transparent-defmacro package:macro
(lambda (code)
``(wrap ,,code))
:wrapping-package)
(defmacro wrapper (code)
`(wrap ,code))
;; macro
(transparent-defmacro package:macro wrapper :wrapping-package)
For some argument lists, the wrapping layer imposes a considerable overhead, since we have to manually ensure that we only pass exactly the same optional and keyword arguments that appeared in the outer call in case the wrapped function explicitly checks whether any of those arguments were supplied. There are two ways to mitigate this overhead:
Set the keyword argument :force-rest
to t
in create-transparent-defun
. This adds a &rest
parameter when wrapping a function that has &key
arguments but no &rest
argument. This way, the keyword arguments can be passed through with apply
without checking which ones are present, with minimal clutter added to the function signature.
When turning a development build into a production build, you can swap out create-transparent-defun
for create-opaque-defun
to include the same wrapping logic but strip out all the infrastructure for imitating the function signature.
This library uses trivial-arguments
to retrieve function and macro signatures. On some implementations, this will not retrieve default arguments for some parameters. When no signature can be found, transparent-defun
falls back to basic opaque-defun
functionality and creates a wrapper with a &rest
parameter only.
Init-forms can have side effects, and they are normally evaluated in left-to-right order. This library will only hoist init-forms into wrappers until it reaches the first parameter, either optional or keyword, that has a supplied-p check. If you're confident that the ordering of your init-forms won't matter, you can set the keyword argument :allow-reordered-init-forms
to t
and see later parameters' init-forms in the wrapper function signature. You will still not see init-forms for any parameters that have supplied-p checks, since this can still affect the behavior of the wrapped function.
Wrappers for generic functions with &rest
and/or &key
parameters will have those parameters subsumed by a single &rest
parameter to allow for variations in congruent method lambda lists.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The transparent-wrap system: |
Kyle Littler
LLGPL
A signature-preserving wrapper generator for functions and macros.
transparent-wrap
================
[](https://travis-ci.org/DalekBaldwin/transparent-wrap)
This is a small utility for generating wrapper functions that have the same signature as the functions they wrap so that you can still interactively see the same function signature in the SLIME minibuffer. (It also offers the same feature for macros, which is not quite as difficult but is included for completeness’ sake.)
## Table of Contents
* [Example](#example)
* [Basic Usage](#basic-usage)
* [Performance](#performance)
* [Limitations](#limitations)
Example
——-
When using ‘lispbuilder-sdl‘ on SBCL, you may encounter all kinds of floating point errors, but you don’t want to disable those errors globally - you want to do your own math before calling out to foreign functions. In that case you can do something like this:
“‘lisp
(defpackage :sdl-wrap
(:use :cl)
#.‘(:export
,@(loop for symbol being the external-symbols of :sdl
when (and (fboundp symbol)
(eql (symbol-package symbol) (find-package :sdl)))
collect symbol)))
#.‘(progn
,@(loop for symbol being the external-symbols of :sdl
when (and (fboundp symbol)
(eql (symbol-package symbol) (find-package :sdl)))
collect
(transparent-wrap:create-transparent-defun
symbol
(lambda (real-function-call)
‘(sb-int:with-float-traps-masked (:invalid :overflow :divide-by-zero)
,real-function-call))
:sdl-wrap)))
“‘
and fix it without having to massively edit the package’s source code or your client code. Just import the wrapper package instead. Now you can get the functionality you need and see that ‘sdl-wrap:draw-string-solid-*‘ has the signature ‘(string x y &key (justify :left) (surface lispbuilder-sdl:*default-surface*) (font lispbuilder-sdl:*default-font*) (color lispbuilder-sdl:*default-color*))‘ without manually searching for it!
Basic Usage
———–
“‘lisp
;; function
(create-transparent-defun ’package:function
(lambda (code)
‘(wrap ,code))
:wrapping-package)
“‘
“‘lisp
(defmacro wrapper (code)
‘(wrap ,code))
;; macro
(transparent-defun package:function wrapper :wrapping-package)
“‘
“‘lisp
;; function
(create-transparent-defmacro package:macro
(lambda (code)
“(wrap ,,code))
:wrapping-package)
“‘
“‘lisp
(defmacro wrapper (code)
‘(wrap ,code))
;; macro
(transparent-defmacro package:macro wrapper :wrapping-package)
“‘
Performance
———–
For some argument lists, the wrapping layer imposes a considerable overhead, since we have to manually ensure that we only pass exactly the same optional and keyword arguments that appeared in the outer call in case the wrapped function explicitly checks whether any of those arguments were supplied. There are two ways to mitigate this overhead:
1. Set the keyword argument ‘:force-rest‘ to ‘t‘ in ‘create-transparent-defun‘. This adds a ‘&rest‘ parameter when wrapping a function that has ‘&key‘ arguments but no ‘&rest‘ argument. This way, the keyword arguments can be passed through with ‘apply‘ without checking which ones are present, with minimal clutter added to the function signature.
2. When turning a development build into a production build, you can swap out ‘create-transparent-defun‘ for ‘create-opaque-defun‘ to include the same wrapping logic but strip out all the infrastructure for imitating the function signature.
Limitations
———–
This library uses ‘trivial-arguments‘ to retrieve function and macro signatures. On some implementations, this will not retrieve default arguments for some parameters. When no signature can be found, ‘transparent-defun‘ falls back to basic ‘opaque-defun‘ functionality and creates a wrapper with a ‘&rest‘ parameter only.
Init-forms can have side effects, and they are normally evaluated in left-to-right order. This library will only hoist init-forms into wrappers until it reaches the first parameter, either optional or keyword, that has a supplied-p check. If you’re confident that the ordering of your init-forms won’t matter, you can set the keyword argument ‘:allow-reordered-init-forms‘ to ‘t‘ and see later parameters’ init-forms in the wrapper function signature. You will still not see init-forms for any parameters that have supplied-p checks, since this can still affect the behavior of the wrapped function.
Wrappers for generic functions with ‘&rest‘ and/or ‘&key‘ parameters will have those parameters subsumed by a single ‘&rest‘ parameter to allow for variations in congruent method lambda lists.
transparent-wrap.asd (file)
Modules are listed depth-first from the system components tree.
• The transparent-wrap/src module: |
transparent-wrap.asd (file)
transparent-wrap (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files: | ||
• Other files: |
Next: Other files, Previous: Files, Up: Files [Contents][Index]
• The transparent-wrap.asd file: | ||
• The transparent-wrap/src/package.lisp file: | ||
• The transparent-wrap/src/match.lisp file: | ||
• The transparent-wrap/src/transparent-wrap.lisp file: |
Next: The transparent-wrap/src/package<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
transparent-wrap.asd
transparent-wrap (system)
Next: The transparent-wrap/src/match<dot>lisp file, Previous: The transparent-wrap<dot>asd file, Up: Lisp files [Contents][Index]
src (module)
src/package.lisp
Next: The transparent-wrap/src/transparent-wrap<dot>lisp file, Previous: The transparent-wrap/src/package<dot>lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
src (module)
src/match.lisp
Previous: The transparent-wrap/src/match<dot>lisp file, Up: Lisp files [Contents][Index]
match.lisp (file)
src (module)
src/transparent-wrap.lisp
Previous: Lisp files, Up: Files [Contents][Index]
• The transparent-wrap/transparent-wrap.asd file: |
Previous: Other files, Up: Other files [Contents][Index]
transparent-wrap (system)
transparent-wrap.asd
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The transparent-wrap-system package: | ||
• The transparent-wrap package: |
Next: The transparent-wrap package, Previous: Packages, Up: Packages [Contents][Index]
transparent-wrap.asd
Previous: The transparent-wrap-system package, Up: Packages [Contents][Index]
package.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions: | ||
• Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros: | ||
• Exported functions: |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
Previous: Exported macros, Up: Exported definitions [Contents][Index]
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables: | ||
• Internal functions: | ||
• Internal structures: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
Next: Internal structures, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
transparent-wrap.lisp (file)
transparent-wrap.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
match.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
match.lisp (file)
structure-object (structure)
aux-param-whole (function)
(setf aux-param-whole) (function)
aux-param-name (function)
(setf aux-param-name) (function)
aux-param-init-form (function)
(setf aux-param-init-form) (function)
match.lisp (file)
structure-object (structure)
key-param-whole (function)
(setf key-param-whole) (function)
key-param-name (function)
(setf key-param-name) (function)
key-param-keyword-name (function)
(setf key-param-keyword-name) (function)
key-param-init-form (function)
(setf key-param-init-form) (function)
key-param-supplied-p-parameter (function)
(setf key-param-supplied-p-parameter) (function)
match.lisp (file)
structure-object (structure)
optional-param-whole (function)
(setf optional-param-whole) (function)
optional-param-name (function)
(setf optional-param-name) (function)
optional-param-init-form (function)
(setf optional-param-init-form) (function)
optional-param-supplied-p-parameter (function)
(setf optional-param-supplied-p-parameter) (function)
match.lisp (file)
structure-object (structure)
specialized-param (structure)
required-param-name (function)
(setf required-param-name) (function)
match.lisp (file)
structure-object (structure)
rest-param-name (function)
(setf rest-param-name) (function)
match.lisp (file)
required-param (structure)
specialized-param-whole (function)
(setf specialized-param-whole) (function)
specialized-param-specializer (function)
(setf specialized-param-specializer) (function)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index: | ||
• Function index: | ||
• Variable index: | ||
• Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L M O T |
---|
Jump to: | F L M O T |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
A C F K M O R S T |
---|
Jump to: | (
A C F K M O R S T |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
I K N S W |
---|
Jump to: | *
I K N S W |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | A K O P R S T |
---|
Jump to: | A K O P R S T |
---|