This is the with-contexts Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 18:17:45 2024 GMT+0.
with-contexts/with-contexts.asdwith-contexts/with-contexts-pkg.lispwith-contexts/contexts.lispwith-contexts/with-cl.lispwith-contexts/library/with-open-file.lispwith-contexts/library/exit-stack-context.lispwith-contexts/library/suppress-context.lispwith-contexts/library/null-context.lispwith-contexts/library/delegate-context.lispwith-contexts/library/redirect-context.lispwith-contexts/library/managed-resource-context.lispThe main system appears first, followed by any subsystem dependency.
with-contextsThe WITH-CONTEXT System.
A system providing a WITH macro and ’context’ualized objects handled by a ENTER/HANDLE/EXIT protocol in the spirit of Python’s WITH macro.
Only better, or, at a minimum different, of course.
Marco Antoniotti <mantoniotti@common-lisp.net>
BSD
with-contexts-pkg.lisp (file).
contexts.lisp (file).
with-cl.lisp (file).
library (module).
Modules are listed depth-first from the system components tree.
with-contexts/librarycontexts.lisp (file).
with-cl.lisp (file).
with-contexts (system).
with-open-file.lisp (file).
exit-stack-context.lisp (file).
suppress-context.lisp (file).
null-context.lisp (file).
delegate-context.lisp (file).
redirect-context.lisp (file).
managed-resource-context.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
with-contexts/with-contexts.asdwith-contexts/with-contexts-pkg.lispwith-contexts/contexts.lispwith-contexts/with-cl.lispwith-contexts/library/with-open-file.lispwith-contexts/library/exit-stack-context.lispwith-contexts/library/suppress-context.lispwith-contexts/library/null-context.lispwith-contexts/library/delegate-context.lispwith-contexts/library/redirect-context.lispwith-contexts/library/managed-resource-context.lispwith-contexts/contexts.lispwith-contexts-pkg.lisp (file).
with-contexts (system).
context (class).
context-p (function).
is-context (generic function).
with-contexts/with-cl.lispwith-contexts-pkg.lisp (file).
contexts.lisp (file).
with-contexts (system).
with-contexts/library/with-open-file.lisplibrary (module).
with-contexts/library/exit-stack-context.lisplibrary (module).
callback (generic function).
enter (method).
enter-context (generic function).
exit (method).
exit-stack (function).
exit-stack-context (class).
exit-stack-context-p (function).
handle (method).
is-exit-stack-context (generic function).
pop-all (generic function).
push-context (generic function).
unwind (generic function).
callback-stack (reader method).
error-context (function).
error-context (class).
error-context-condition (reader method).
error-context-item (reader method).
error-context-p (function).
is-error-context (generic function).
set-callback-stack (writer method).
with-contexts/library/suppress-context.lisplibrary (module).
condition-ignoring-context (class).
condition-ignoring-context-p (function).
enter (method).
exit (method).
handle (method).
ignored (function).
is-condition-ignoring-context (generic function).
suppressed (function).
check-subtypep (reader method).
ignored-conditions (reader method).
with-contexts/library/null-context.lisplibrary (module).
enter (method).
exit (method).
handle (method).
is-null-context (generic function).
null-context (function).
null-context (class).
null-context-p (function).
enter-result (reader method).
with-contexts/library/delegate-context.lisplibrary (module).
delegate (function).
delegate-context (class).
delegate-context-p (function).
enter (method).
exit (method).
handle (method).
is-delegate-context (generic function).
enter-result (reader method).
with-contexts/library/redirect-context.lisplibrary (module).
enter (method).
enter (method).
enter (method).
error-output-redirection (function).
exit (method).
exit (method).
exit (method).
handle (method).
initialize-instance (method).
initialize-instance (method).
is-redirect-context (generic function).
redirect-context (class).
redirect-context-p (function).
redirect-error-output-context (class).
redirect-input-context (class).
redirect-output-context (class).
redirect-standard-output-context (class).
redirection (reader method).
standard-input-redirection (function).
standard-output-redirection (function).
%%saved-stream (reader method).
(setf %%saved-stream) (writer method).
with-contexts/library/managed-resource-context.lisplibrary (module).
acquire (generic function).
enter (method).
exit (method).
handle (method).
is-managed-resource-context (generic function).
managed-resource (function).
managed-resource-context (class).
managed-resource-context-p (function).
release (generic function).
Packages are listed by definition order.
it.unimib.disco.ma.cl.ext.dacf.with-contextsThe CL Contexts Package.
The package containing and exporting the names relating to the implementation of the WITH macro and ’contexts’ in Common Lisp.
cl-contexts
ctxts
common-lisp.
acquire (generic function).
callback (generic function).
condition-ignoring-context (class).
condition-ignoring-context-p (function).
context (class).
context-p (function).
delegate (function).
delegate-context (class).
delegate-context-p (function).
enter (generic function).
enter-context (generic function).
error-output-redirection (function).
exit (generic function).
exit-stack (function).
exit-stack-context (class).
exit-stack-context-p (function).
handle (generic function).
ignored (function).
is-condition-ignoring-context (generic function).
is-context (generic function).
is-delegate-context (generic function).
is-exit-stack-context (generic function).
is-managed-resource-context (generic function).
is-null-context (generic function).
is-redirect-context (generic function).
managed-resource (function).
managed-resource-context (class).
managed-resource-context-p (function).
null-context (function).
null-context (class).
null-context-p (function).
pop-all (generic function).
push-context (generic function).
redirect-context (class).
redirect-context-p (function).
redirect-error-output-context (class).
redirect-input-context (class).
redirect-output-context (class).
redirect-standard-output-context (class).
redirection (generic reader).
release (generic function).
standard-input-redirection (function).
standard-output-redirection (function).
suppressed (function).
unwind (generic function).
with (macro).
%%saved-stream (generic reader).
(setf %%saved-stream) (generic writer).
callback-stack (generic reader).
check-subtypep (generic reader).
enter-result (generic reader).
error-context (function).
error-context (class).
error-context-condition (generic reader).
error-context-item (generic reader).
error-context-p (function).
ignored-conditions (generic reader).
is-error-context (generic function).
set-callback-stack (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
The WITH Macro.
The actual syntax of the WITH macro is the following:
with [VAR ’=’] CTXT-ITEM ’do’ CODE
Description:
The macro establishes a ’context’ based on the nature of CTXT-ITEM,
which is the result of an evaluated expression. VAR, if supplied, is
then bound to the result of ENTERing the context; i.e., VAR is bound
to the (first) value of applying the generic function ENTER to
CTXT-ITEM and it is available within CODE. If VAR is supplied, it
’escapes’ the with construct as if SETQed in the enclosind
environment.
The WITH macro guarantees that the generic function EXIT is called as
the cleanup form in an UNWIND-PROTECT before returning the values
generated by CODE of after error conditions are signaled by it. EXIT
is called with VAR
Errors generated by CODE are passed alogside VAR to the generic function
HANDLE. This is done in a HANDLER-CASE within the UNWIND-PROTECT
that wraps CODE and uses the EXIT generic function as cleanup form.
The value(s) returned by EXIT are effectively ignored.
Notes:
The inspiration for this macro comes from Python, which reinvented and
expanded the concept from Common Lisp or Pascal or even somewhere
else. Julia may have something similar with its ’do’ blocks.
Note that, unlike Python, Common Lisp does not have a "yield"
statement or (delimited) continuations; therefore, the mapping with
Python code cannot be one-to-one.
Exceptional Situations:
If an error occurs while evaluating CTXT-ITEM, then HANDLE is not
called, while EXIT is called with NIL as argument.
See Also:
ENTER, HANDLE, EXIT, WITH-OPEN-FILE
Returns T if X is a CONDITION-IGNORING-CONTEXT, NIL otherwise.
Returns T if the argument X is a CONTEXT; NIL otherwise.
Creates a DELEGATE-CONTEXT stashing ENTER-RESULT for ENTER.
A subsequent call to ENTER on the instance will extract ENTER-RESULT and return it.
See Also:
ENTER, HANDLE, EXIT, WITH, DELEGATE-CONTEXT (Class)
Constructor for an EXIT-STACK-CONTEXT.
Returns T when the argument X is and EXIT-CONTEXT; NIL otherwise.
Returns a CONDITION-IGNORING-CONTEXT.
The argument CONDITIONS is a list of CONDITION designators (or a
single CONDITION designator) to be ingnored by the HANDLE method
within a WITH context macro.
If SUBTYPEP is T any condition/error that is a subtype/subclass of any
member in CONDITIOS will be ignored/suppressed by the HANDLE method,
otherwse only instances of the exact CONDITIONS member will be
ignored.
See Also:
ENTER, HANDLE, EXIT, SUPPRESSED
Constructs a MANAGED-RESOURCE.
The only declared parameter, ID, should be a unique identified for the resource.
Returns T if the argument X is a MANAGED-RESOURCE-CONTEXT.
Notes:
This function is a synonim of IS-MANAGED-RESOURCE-CONTEXT.
Creates a NULL-CONTEXT stashing ENTER-RESULT for ENTER.
A subsequent call to ENTER on the instance will extract ENTER-RESULT and return it.
See Also:
ENTER, HANDLE, EXIT, WITH, NULL-CONTEXT (Class)
Returns T if the argument X is a REDIRECT-CONTEXT.
Notes:
This is a synonym of IS-REDIRECT-CONTEXT.
Returns a CONDITION-IGNORING-CONTEXT.
This constructor is a synonim for IGNORED.
See Also:
IGNORED, ENTER, HANDLE, EXIT
Acquires a MANAGED-RESOURCE.
This generic function is the ’entry’ point of the ACQUIRE/RELEASE protocol.
managed-resource-context) &key) ¶Adds a FUNCTION and its ARGS to an EXIT-STACK.
exit-stack-context) (f function) &rest args) ¶The ENTER Generic Function.
The methods of this function establish a ’context’ that can be used by
the ENTER/HANDLE/EXIT protocol within the WITH context macro.
The main and simplest method is an identity operation which just
returns the argument.
Exceptional Situations:
If this method generates an error, then HANDLE is not called and EXIT
is called with NIL as an argument.
Notes:
Because of this "interpretation" of the ENTER method, NULL-CONTEXTS
become a bit redundant, but they are provided for completeness.
See Also:
HANDLE, EXIT, NULL-CONTEXT
managed-resource-context) &key) ¶redirect-input-context) &key) ¶redirect-error-output-context) &key) ¶redirect-standard-output-context) &key) ¶delegate-context) &key) ¶null-context) &key) ¶condition-ignoring-context) &key) ¶exit-stack-context) &key) ¶stream) &key) ¶Calls ENTER on a CONTEXT-MANAGER and pushes it on the EXIT-STACK callback stack.
If an error occurs while ENTERing the CONTEXT-MANAGER, then an
ERROR-CONTEXT is pushed on the EXIT-CONTEXT callback stack.
exit-stack-context) (cm context)) ¶The EXIT Generic Function.
The methods of this function dispatch on a CONTEXT-ITEM and are always
called as ’cleanup forms’ of an UNWIND-PROTECT. The values reurned by this
generic function are therefore ignored.
The main method dispatching on NIL is called when ENTER generates errors.
managed-resource-context) &key) ¶redirect-input-context) &key) ¶redirect-error-output-context) &key) ¶redirect-standard-output-context) &key) ¶delegate-context) &key) ¶null-context) &key) ¶condition-ignoring-context) &key) ¶exit-stack-context) &key) ¶stream) &key) ¶null) &key) ¶The HANDLE Generic Function.
The methods of this function dispatch on a CONTEXT-ITEM and a
CONDITION. In this way, within the confines of the the WITH macro,
there is a decoupled way of handling different exceptions.
The main and simpler method of this generic function simply re-signals the condition.
managed-resource-context) (e error) &key) ¶redirect-context) (e error) &key) ¶delegate-context) (e error) &key) ¶null-context) (e error) &key) ¶condition-ignoring-context) (e error) &key) ¶exit-stack-context) (e error) &key) ¶stream) (e error) &key) ¶error) &key) ¶Returns T if X is a CONDITION-IGNORING-CONTEXT, NIL otherwise.
condition-ignoring-context)) ¶Returns T if the argument X is a CONTEXT; NIL otherwise.
delegate-context)) ¶Returns T when the argument X is and EXIT-CONTEXT; NIL otherwise.
exit-stack-context)) ¶Returns T if the argument X is a MANAGED-RESOURCE-CONTEXT.
managed-resource-context)) ¶null-context)) ¶Returns T if the argument X is a REDIRECT-CONTEXT.
redirect-context)) ¶Creates a new EXIT-STACK-CONTEXT and transfers the callbacks to it.
The callbacks of the current exit stack are popped from it and moved to the new one.
exit-stack-context)) ¶Pushes a CONTEXT-MANAGER on the callback stack of EXIT-MANAGER.
exit-stack-context) (cm context)) ¶redirect-context)) ¶automatically generated reader method
Releases a MANAGED-RESOURCE.
This generic function is the ’exit’ point of the ACQUIRE/RELEASE protocol.
managed-resource-context) &key) ¶The callback stack of the EXIT-STACK are popped and called.
Notes:
This is the method ’close()’ in Python. The name ’UNWIND’ was chosen to be more ’lispy’ and to avoid conclictsa with CL:CLOSE.
exit-stack-context)) ¶redirect-input-context) &key stream) ¶redirect-output-context) &key stream) ¶The Condition-ignoring Context Class.
Instances of this class are used to ignore/suppress errors within a WITH context macro.
The Context Class.
A class that can be used in conjunction with the WITH macro. This class is the top of the hierarchy of "context" classes. It shuld not be directly instantiated.
The Delegate Context Class.
A context that just wraps a value to which it delegates its behavior.
Notes:
This context it necessary in Common Lisp as the ENTER/HANDLE/EXIT
protocol can be implemented indipendently of ’being a context’.
See Also:
ENTER, HANDLE, EXIT, WITH, DELEGATE-CONTEXT (Function)
| Initarg | Value |
|---|---|
:enter-result | nil |
:enter-result
This slot is read-only.
The Exit Stack Class.
A class that serves to collect and unwind code (callbacks) that are
collected within a WITH macro body. The methods of this class provide
more control over what happens with errors that may happen within
ENTER calls in non-straightforward contexts.
Notes:
This class provides much of the functionalities displayed in the Python examples.
list
The Managed Resource Context Class.
A placeholder class showing how to render, more or less, the Python examples in Common Lisp.
:resource
The Null Context Class.
A context that just wraps a value that it is then returned by ENTER.
See Also:
ENTER, HANDLE, EXIT, WITH, NULL-CONTEXT (Function)
| Initarg | Value |
|---|---|
:enter-result | nil |
:enter-result
This slot is read-only.
The Redirect Context Class.
This is the context superclass for redirecting I/O. The library
creates instances of this class subclasses.
See Also:
REDIRECT-OUTPUT-CONTEXT, REDIRECT-INPUT-CONTEXT, REDIRECT-STANDARD-OUTPUT-CONTEXT, REDIRECT-ERROR-OUTPUT-CONTEXT, ENTER, HANDLE, EXIT, WITH
Constructor for an EXIT-STACK-CONTEXT.
redirect-context)) ¶automatically generated reader method
redirect-context)) ¶automatically generated writer method
exit-stack-context)) ¶automatically generated reader method
condition-ignoring-context)) ¶automatically generated reader method
delegate-context)) ¶automatically generated reader method
null-context)) ¶automatically generated reader method
error-context)) ¶automatically generated reader method
cnd.
error-context)) ¶automatically generated reader method
ctx.
condition-ignoring-context)) ¶automatically generated reader method
error-context)) ¶exit-stack-context) exit-stack-context) ¶automatically generated writer method
| Jump to: | %
(
A C D E F G H I M N P R S U W |
|---|
| Jump to: | %
(
A C D E F G H I M N P R S U W |
|---|
| Jump to: | C E R S |
|---|
| Jump to: | C E R S |
|---|
| Jump to: | C D E F I L M N P R S W |
|---|
| Jump to: | C D E F I L M N P R S W |
|---|