The with-contexts Reference Manual

Table of Contents

The with-contexts Reference Manual

This is the with-contexts Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 15:30:06 2020 GMT+0.

1 Introduction

WITH-CONTEXTS

Copyright (c) 2020 Marco Antoniotti See file COPYING for licensing information

DESCRIPTION

This library contains an implementation of a WITH macro with "contexts" inspired by Python, which, in turn was obviously inspired by Common Lisp macros (and other earlier languages, like Pascal).

The Python library is described in the documentation of the contextlib documentation. The current library is an implementation that overlaps with the Python one, as a few things are available in Common Lisp that are not available in Python and two things are present in Python, that are not available in Common Lisp: the yield statement and built-in threading for asynchronous computations. Note that the yield statement could be built in Common Lisp using a delimited continuation library like cl-cont. The asynchronous extensions could instead be directly built on top of the current library.

Most of the Python examples described in the ... context of contextlib are directly translatable into Common Lisp using the present library. The main difference is that, in order to leverage the Common Lisp Condition subsystem the "protocol" that "contexts" must implement is comprised of three generic functions:

• ENTER <context>
• HANDLE <context> <condition>
• EXIT context

The WITH macro is practically expanded as follows.

(with [VAR =] CONTEXT-ITEM do CODE)

becomes

(let ((VAR NIL))
  (unwind-protect
    (progn
      (setf VAR (ENTER CONTEXT-ITEM))
      (handler-case 
          CODE
        (error (e)
          (HANDLE VAR e))
      ))
    (EXIT VAR)))

With this setup, WITH-OPEN-FILE can be immediately rewritten as

(with f = (open "some.txt") do
  (loop for line = (read-line f)
       while line
	   do (do-stuff-to line)))

provided that the proper ENTER/HANDLE/EXIT protocol is in place. Something like the following.

(defmethod enter ((s file-stream) &key)
  (if (open-stream-p s)
      s
      (error "Stream ~S is not open." context-item)))
	   
(defmethod handle ((s file-stream) (e error) &key)
  (call-next-method))
  
(defmethod exit ((s file-stream) &key)
  (when (open-stream-p s)
    (close s)))

Note that in Python, HANDLE does not exist and EXIT is called close.

More Elaborated Contexts

The contextlib Python library contains more elaborated "contexts" that can be used to perform a number of sophisticated operations in conjunction with the WITH statement.

EXIT-STACK-CONTEXT

Python introduces ExitStack as (the following is a direct quote from Python contextlib documentation) a context manager that is designed to make it easy to programmatically combine other context managers and cleanup functions, especially those that are optional or otherwise driven by input data.

For example, a set of files may easily be handled in a single with statement as follows:

(with stack = (exit-stack) do
  (let* ((files (mapcar (lambda (fname)
                          (enter-context stack (open fname)))
                         *filenames*)))

    ;; Hold on to the new exit stack (not the method pointe as in the
    ;; Python example), but don't call its UNWIND method

    (setf *close-files* (pop-all stack))

    ;; If opening any file fails, all previously opened files will be
    ;; closed automatically. If all files are opened successfully,
    ;; they will remain open even after the with statement ends.
    ;;
    ;;    (unwind *close-files*)
    ;;
    ;; can then be invoked explicitly to close them all.

    ;; ...
    )

Each instance maintains a stack of registered callbacks that are called in reverse order when the instance is closed (either explicitly or implicitly at the end of a WITH statement).

Documentation

Please refer to the full documentation of the with-contexts library for more details.

A NOTE ON FORKING

Of course you are free to fork the project subject to the current licensing scheme. However, before you do so, I ask you to consider plain old "cooperation" by asking me to become a developer. It helps keeping the entropy level at an acceptable level.

Enjoy!

Marco Antoniotti 20201212

2 Systems

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

2.1 with-contexts

Author

Marco Antoniotti <mantoniotti@common-lisp.net>

License

BSD

Description

The 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.

Source

with-contexts.asd (file)

Components

• with-contexts-pkg.lisp (file)
• contexts.lisp (file)
• with-cl.lisp (file)
• library (module)

3 Modules

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

3.1 with-contexts/library

Dependencies

• contexts.lisp (file)
• with-cl.lisp (file)

Parent

with-contexts (system)

Location

library/

Components

• 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)

4 Files

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

4.1 Lisp

4.1.1 with-contexts.asd

Location

with-contexts.asd

Systems

with-contexts (system)

4.1.2 with-contexts/with-contexts-pkg.lisp

Parent

with-contexts (system)

Location

with-contexts-pkg.lisp

Packages

it.unimib.disco.ma.cl.ext.dacf.with-contexts

4.1.3 with-contexts/contexts.lisp

Dependency

with-contexts-pkg.lisp (file)

Parent

with-contexts (system)

Location

contexts.lisp

Exported Definitions

• context (class)
• context-p (function)
• is-context (generic function)
• is-context (method)
• is-context (method)

4.1.4 with-contexts/with-cl.lisp

Dependencies

• with-contexts-pkg.lisp (file)
• contexts.lisp (file)

Parent

with-contexts (system)

Location

with-cl.lisp

Exported Definitions

• enter (generic function)
• enter (method)
• exit (generic function)
• exit (method)
• exit (method)
• handle (generic function)
• handle (method)
• with (macro)

4.1.5 with-contexts/library/with-open-file.lisp

Parent

library (module)

Location

library/with-open-file.lisp

Exported Definitions

• enter (method)
• exit (method)
• handle (method)

4.1.6 with-contexts/library/exit-stack-context.lisp

Parent

library (module)

Location

library/exit-stack-context.lisp

Exported Definitions

• callback (generic function)
• callback (method)
• enter (method)
• enter-context (generic function)
• enter-context (method)
• exit (method)
• exit-stack (function)
• exit-stack-context (class)
• exit-stack-context-p (function)
• handle (method)
• is-exit-stack-context (generic function)
• is-exit-stack-context (method)
• is-exit-stack-context (method)
• pop-all (generic function)
• pop-all (method)
• push-context (generic function)
• push-context (method)
• unwind (generic function)
• unwind (method)

Internal Definitions

• callback-stack (method)
• error-context (function)
• error-context (class)
• error-context-condition (method)
• error-context-item (method)
• error-context-p (function)
• is-error-context (generic function)
• is-error-context (method)
• is-error-context (method)
• set-callback-stack (method)

4.1.7 with-contexts/library/suppress-context.lisp

Parent

library (module)

Location

library/suppress-context.lisp

Exported Definitions

• condition-ignoring-context (class)
• condition-ignoring-context-p (function)
• enter (method)
• exit (method)
• handle (method)
• ignored (function)
• is-condition-ignoring-context (generic function)
• is-condition-ignoring-context (method)
• is-condition-ignoring-context (method)
• suppressed (function)

Internal Definitions

• check-subtypep (method)
• ignored-conditions (method)

4.1.8 with-contexts/library/null-context.lisp

Parent

library (module)

Location

library/null-context.lisp

Exported Definitions

• enter (method)
• exit (method)
• handle (method)
• is-null-context (generic function)
• is-null-context (method)
• is-null-context (method)
• null-context (function)
• null-context (class)
• null-context-p (function)

Internal Definitions

enter-result (method)

4.1.9 with-contexts/library/delegate-context.lisp

Parent

library (module)

Location

library/delegate-context.lisp

Exported Definitions

• delegate (function)
• delegate-context (class)
• delegate-context-p (function)
• enter (method)
• exit (method)
• handle (method)
• is-delegate-context (generic function)
• is-delegate-context (method)
• is-delegate-context (method)

Internal Definitions

enter-result (method)

4.1.10 with-contexts/library/redirect-context.lisp

Parent

library (module)

Location

library/redirect-context.lisp

Exported Definitions

• enter (method)
• enter (method)
• enter (method)
• error-output-redirection (function)
• exit (method)
• exit (method)
• exit (method)
• handle (method)
• is-redirect-context (generic function)
• is-redirect-context (method)
• is-redirect-context (method)
• 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 (method)
• standard-input-redirection (function)
• standard-output-redirection (function)

Internal Definitions

• %%saved-stream (method)
• (setf %%saved-stream) (method)

4.1.11 with-contexts/library/managed-resource-context.lisp

Parent

library (module)

Location

library/managed-resource-context.lisp

Exported Definitions

• acquire (generic function)
• acquire (method)
• enter (method)
• exit (method)
• handle (method)
• is-managed-resource-context (generic function)
• is-managed-resource-context (method)
• is-managed-resource-context (method)
• managed-resource (function)
• managed-resource-context (class)
• managed-resource-context-p (function)
• release (generic function)
• release (method)

5 Packages

Packages are listed by definition order.

5.1 it.unimib.disco.ma.cl.ext.dacf.with-contexts

The CL Contexts Package.

The package containing and exporting the names relating to the implementation of the WITH macro and ’contexts’ in Common Lisp.

Source

with-contexts-pkg.lisp (file)

Nicknames

• ctxts
• cl-contexts

Use List

common-lisp

Exported Definitions

• acquire (generic function)
• acquire (method)
• callback (generic function)
• callback (method)
• 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 (method)
• enter (method)
• enter (method)
• enter (method)
• enter (method)
• enter (method)
• enter (method)
• enter (method)
• enter (method)
• enter (method)
• enter-context (generic function)
• enter-context (method)
• error-output-redirection (function)
• exit (generic function)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit (method)
• exit-stack (function)
• exit-stack-context (class)
• exit-stack-context-p (function)
• handle (generic function)
• handle (method)
• handle (method)
• handle (method)
• handle (method)
• handle (method)
• handle (method)
• handle (method)
• handle (method)
• ignored (function)
• is-condition-ignoring-context (generic function)
• is-condition-ignoring-context (method)
• is-condition-ignoring-context (method)
• is-context (generic function)
• is-context (method)
• is-context (method)
• is-delegate-context (generic function)
• is-delegate-context (method)
• is-delegate-context (method)
• is-exit-stack-context (generic function)
• is-exit-stack-context (method)
• is-exit-stack-context (method)
• is-managed-resource-context (generic function)
• is-managed-resource-context (method)
• is-managed-resource-context (method)
• is-null-context (generic function)
• is-null-context (method)
• is-null-context (method)
• is-redirect-context (generic function)
• is-redirect-context (method)
• is-redirect-context (method)
• 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)
• pop-all (method)
• push-context (generic function)
• push-context (method)
• 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 function)
• redirection (method)
• release (generic function)
• release (method)
• standard-input-redirection (function)
• standard-output-redirection (function)
• suppressed (function)
• unwind (generic function)
• unwind (method)
• with (macro)

Internal Definitions

• %%saved-stream (generic function)
• %%saved-stream (method)
• (setf %%saved-stream) (method)
• (setf %%saved-stream) (generic function)
• callback-stack (generic function)
• callback-stack (method)
• check-subtypep (generic function)
• check-subtypep (method)
• enter-result (generic function)
• enter-result (method)
• enter-result (method)
• error-context (function)
• error-context (class)
• error-context-condition (generic function)
• error-context-condition (method)
• error-context-item (generic function)
• error-context-item (method)
• error-context-p (function)
• ignored-conditions (generic function)
• ignored-conditions (method)
• is-error-context (generic function)
• is-error-context (method)
• is-error-context (method)
• set-callback-stack (generic function)
• set-callback-stack (method)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: with &rest WITH-SPEC

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

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

with-cl.lisp (file)

6.1.2 Functions

Function: condition-ignoring-context-p X

Returns T if X is a CONDITION-IGNORING-CONTEXT, NIL otherwise.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

suppress-context.lisp (file)

Function: context-p X

Returns T if the argument X is a CONTEXT; NIL otherwise.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

contexts.lisp (file)

Function: delegate &optional ENTER-RESULT

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)

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

delegate-context.lisp (file)

Function: delegate-context-p X

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

delegate-context.lisp (file)

Function: error-output-redirection STREAM

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Function: exit-stack ()

Constructor for an EXIT-STACK-CONTEXT.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Function: exit-stack-context-p X

Returns T when the argument X is and EXIT-CONTEXT; NIL otherwise.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Function: ignored CONDITIONS &key SUBTYPEP &allow-other-keys

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

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

suppress-context.lisp (file)

Function: managed-resource ID &key &allow-other-keys

Constructs a MANAGED-RESOURCE.

The only declared parameter, ID, should be a unique identified for the resource.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

managed-resource-context.lisp (file)

Function: managed-resource-context-p X

Returns T if the argument X is a MANAGED-RESOURCE-CONTEXT.

Notes:

This function is a synonim of IS-MANAGED-RESOURCE-CONTEXT.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

managed-resource-context.lisp (file)

Function: null-context &optional ENTER-RESULT

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)

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

null-context.lisp (file)

Function: null-context-p X

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

null-context.lisp (file)

Function: redirect-context-p X

Returns T if the argument X is a REDIRECT-CONTEXT.

Notes:

This is a synonym of IS-REDIRECT-CONTEXT.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Function: standard-input-redirection STREAM

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Function: standard-output-redirection STREAM

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Function: suppressed CONDITIONS &key SUBTYPEP &allow-other-keys

Returns a CONDITION-IGNORING-CONTEXT.

This constructor is a synonim for IGNORED.

See Also:

IGNORED, ENTER, HANDLE, EXIT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

suppress-context.lisp (file)

6.1.3 Generic functions

Generic Function: acquire MR &key

Acquires a MANAGED-RESOURCE.

This generic function is the ’entry’ point of the ACQUIRE/RELEASE protocol.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

managed-resource-context.lisp (file)

Methods

Method: acquire (MR managed-resource-context) &key

Generic Function: callback EXIT-STACK FUNCTION &rest ARGS

Adds a FUNCTION and its ARGS to an EXIT-STACK.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: callback (ES exit-stack-context) (F function) &rest ARGS

Generic Function: enter CONTEXT-ITEM &key

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

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

with-cl.lisp (file)

Methods

Method: enter (MR managed-resource-context) &key

Source

managed-resource-context.lisp (file)

Method: enter (RIC redirect-input-context) &key after

Source

redirect-context.lisp (file)

Method: enter (REOC redirect-error-output-context) &key after

Source

redirect-context.lisp (file)

Method: enter (RSOC redirect-standard-output-context) &key after

Source

redirect-context.lisp (file)

Method: enter (NC delegate-context) &key

Source

delegate-context.lisp (file)

Method: enter (NC null-context) &key

Source

null-context.lisp (file)

Method: enter (IGN condition-ignoring-context) &key

Source

suppress-context.lisp (file)

Method: enter (ES exit-stack-context) &key

Source

exit-stack-context.lisp (file)

Method: enter (CONTEXT-ITEM stream) &key

Source

with-open-file.lisp (file)

Method: enter CONTEXT-ITEM &key

Generic Function: enter-context EXIT-STACK CONTEXT-MANAGER

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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: enter-context (ES exit-stack-context) (CM context)

Generic Function: exit CONTEXT-ITEM &key

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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

with-cl.lisp (file)

Methods

Method: exit (MR managed-resource-context) &key

Source

managed-resource-context.lisp (file)

Method: exit (RIC redirect-input-context) &key after

Source

redirect-context.lisp (file)

Method: exit (REOC redirect-error-output-context) &key after

Source

redirect-context.lisp (file)

Method: exit (RSOC redirect-standard-output-context) &key after

Source

redirect-context.lisp (file)

Method: exit (NC delegate-context) &key

Source

delegate-context.lisp (file)

Method: exit (NC null-context) &key

Source

null-context.lisp (file)

Method: exit (IGN condition-ignoring-context) &key

Source

suppress-context.lisp (file)

Method: exit (ES exit-stack-context) &key

Source

exit-stack-context.lisp (file)

Method: exit (CONTEXT-ITEM stream) &key

Source

with-open-file.lisp (file)

Method: exit CONTEXT-ITEM &key

Method: exit (CONTEXT-ITEM null) &key

Generic Function: handle CONTEXT-ITEM CONDITION &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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

with-cl.lisp (file)

Methods

Method: handle (MR managed-resource-context) (E error) &key

Source

managed-resource-context.lisp (file)

Method: handle (RC redirect-context) (E error) &key

Source

redirect-context.lisp (file)

Method: handle (NC delegate-context) (E error) &key

Source

delegate-context.lisp (file)

Method: handle (NC null-context) (E error) &key

Source

null-context.lisp (file)

Method: handle (IGN condition-ignoring-context) (E error) &key

Source

suppress-context.lisp (file)

Method: handle (ES exit-stack-context) (E error) &key

Source

exit-stack-context.lisp (file)

Method: handle (CONTEXT-ITEM stream) (E error) &key

Source

with-open-file.lisp (file)

Method: handle CONTEXT-ITEM (CONDITION error) &key

Generic Function: is-condition-ignoring-context X

Returns T if X is a CONDITION-IGNORING-CONTEXT, NIL otherwise.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

suppress-context.lisp (file)

Methods

Method: is-condition-ignoring-context (X condition-ignoring-context)

Method: is-condition-ignoring-context X

Generic Function: is-context X

Returns T if the argument X is a CONTEXT; NIL otherwise.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

contexts.lisp (file)

Methods

Method: is-context (C context)

Method: is-context C

Generic Function: is-delegate-context X

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

delegate-context.lisp (file)

Methods

Method: is-delegate-context (X delegate-context)

Method: is-delegate-context X

Generic Function: is-exit-stack-context X

Returns T when the argument X is and EXIT-CONTEXT; NIL otherwise.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: is-exit-stack-context (X exit-stack-context)

Method: is-exit-stack-context X

Generic Function: is-managed-resource-context X

Returns T if the argument X is a MANAGED-RESOURCE-CONTEXT.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

managed-resource-context.lisp (file)

Methods

Method: is-managed-resource-context (X managed-resource-context)

Method: is-managed-resource-context X

Generic Function: is-null-context X

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

null-context.lisp (file)

Methods

Method: is-null-context (X null-context)

Method: is-null-context X

Generic Function: is-redirect-context X

Returns T if the argument X is a REDIRECT-CONTEXT.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Methods

Method: is-redirect-context (X redirect-context)

Method: is-redirect-context X

Generic Function: pop-all EXIT-STACK-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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: pop-all (ES exit-stack-context)

Generic Function: push-context EXIT-STACK CONTEXT-MANAGER

Pushes a CONTEXT-MANAGER on the callback stack of EXIT-MANAGER.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: push-context (ES exit-stack-context) (CM context)

Generic Function: redirection OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: redirection (REDIRECT-CONTEXT redirect-context)

automatically generated reader method

Source

redirect-context.lisp (file)

Generic Function: release MR &key

Releases a MANAGED-RESOURCE.

This generic function is the ’exit’ point of the ACQUIRE/RELEASE protocol.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

managed-resource-context.lisp (file)

Methods

Method: release (MR managed-resource-context) &key

Generic Function: unwind EXIT-STACK

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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: unwind (ES exit-stack-context)

6.1.4 Classes

Class: condition-ignoring-context ()

The Condition-ignoring Context Class.

Instances of this class are used to ignore/suppress errors within a WITH context macro.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

suppress-context.lisp (file)

Direct superclasses

context (class)

Direct methods

• exit (method)
• handle (method)
• enter (method)
• is-condition-ignoring-context (method)
• check-subtypep (method)
• ignored-conditions (method)

Direct slots

Slot: conditions

Initargs

:conditions

Readers

ignored-conditions (generic function)

Slot: check-subtypep

Initargs

:subtypep

Readers

check-subtypep (generic function)

Direct Default Initargs

Initarg	Value
:subtypep	nil

Class: context ()

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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

contexts.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• exit-stack-context (class)
• error-context (class)
• condition-ignoring-context (class)
• null-context (class)
• delegate-context (class)
• redirect-context (class)
• managed-resource-context (class)

Direct methods

• push-context (method)
• enter-context (method)
• is-context (method)

Class: delegate-context ()

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)

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

delegate-context.lisp (file)

Direct superclasses

context (class)

Direct methods

• exit (method)
• handle (method)
• enter (method)
• is-delegate-context (method)
• enter-result (method)

Direct slots

Slot: enter-result

Initargs

:enter-result

Readers

enter-result (generic function)

Direct Default Initargs

Initarg	Value
:enter-result	nil

Class: exit-stack-context ()

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.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Direct superclasses

context (class)

Direct methods

• exit (method)
• handle (method)
• enter (method)
• unwind (method)
• pop-all (method)
• callback (method)
• push-context (method)
• enter-context (method)
• is-exit-stack-context (method)
• set-callback-stack (method)
• callback-stack (method)

Direct slots

Slot: callback-stack

Type

list

Readers

callback-stack (generic function)

Writers

set-callback-stack (generic function)

Class: managed-resource-context ()

The Managed Resource Context Class.

A placeholder class showing how to render, more or less, the Python examples in Common Lisp.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

managed-resource-context.lisp (file)

Direct superclasses

context (class)

Direct methods

• exit (method)
• handle (method)
• enter (method)
• release (method)
• acquire (method)
• is-managed-resource-context (method)

Direct slots

Slot: resource

Initargs

:resource

Class: null-context ()

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)

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

null-context.lisp (file)

Direct superclasses

context (class)

Direct methods

• exit (method)
• handle (method)
• enter (method)
• is-null-context (method)
• enter-result (method)

Direct slots

Slot: enter-result

Initargs

:enter-result

Readers

enter-result (generic function)

Direct Default Initargs

Initarg	Value
:enter-result	nil

Class: redirect-context ()

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

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Direct superclasses

context (class)

Direct subclasses

• redirect-output-context (class)
• redirect-input-context (class)

Direct methods

• handle (method)
• is-redirect-context (method)
• %%saved-stream (method)
• %%saved-stream (method)
• redirection (method)

Direct slots

Slot: stream

Type

stream

Initargs

:stream

Readers

redirection (generic function)

Slot: saved-stream

Type

stream

Readers

%%saved-stream (generic function)

Writers

(setf %%saved-stream) (generic function)

Class: redirect-error-output-context ()

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Direct superclasses

redirect-output-context (class)

Direct methods

• exit (method)
• enter (method)

Class: redirect-input-context ()

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Direct superclasses

redirect-context (class)

Direct methods

• exit (method)
• enter (method)
• initialize-instance (method)

Class: redirect-output-context ()

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Direct superclasses

redirect-context (class)

Direct subclasses

• redirect-standard-output-context (class)
• redirect-error-output-context (class)

Direct methods

initialize-instance (method)

Class: redirect-standard-output-context ()

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

redirect-context.lisp (file)

Direct superclasses

redirect-output-context (class)

Direct methods

• exit (method)
• enter (method)

6.2 Internal definitions

6.2.1 Functions

Function: error-context ITEM ERROR

Constructor for an EXIT-STACK-CONTEXT.

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Function: error-context-p X

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

6.2.2 Generic functions

Generic Function: %%saved-stream OBJECT

Generic Function: (setf %%saved-stream) NEW-VALUE OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: %%saved-stream (REDIRECT-CONTEXT redirect-context)

automatically generated reader method

Source

redirect-context.lisp (file)

Method: (setf %%saved-stream) NEW-VALUE (REDIRECT-CONTEXT redirect-context)

automatically generated writer method

Source

redirect-context.lisp (file)

Generic Function: callback-stack OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: callback-stack (EXIT-STACK-CONTEXT exit-stack-context)

automatically generated reader method

Source

exit-stack-context.lisp (file)

Generic Function: check-subtypep OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: check-subtypep (CONDITION-IGNORING-CONTEXT condition-ignoring-context)

automatically generated reader method

Source

suppress-context.lisp (file)

Generic Function: enter-result OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: enter-result (DELEGATE-CONTEXT delegate-context)

automatically generated reader method

Source

delegate-context.lisp (file)

Method: enter-result (NULL-CONTEXT null-context)

automatically generated reader method

Source

null-context.lisp (file)

Generic Function: error-context-condition OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: error-context-condition (ERROR-CONTEXT error-context)

automatically generated reader method

Source

exit-stack-context.lisp (file)

Generic Function: error-context-item OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: error-context-item (ERROR-CONTEXT error-context)

automatically generated reader method

Source

exit-stack-context.lisp (file)

Generic Function: ignored-conditions OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: ignored-conditions (CONDITION-IGNORING-CONTEXT condition-ignoring-context)

automatically generated reader method

Source

suppress-context.lisp (file)

Generic Function: is-error-context X

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Methods

Method: is-error-context (X error-context)

Method: is-error-context X

Generic Function: set-callback-stack NEW-VALUE OBJECT

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Methods

Method: set-callback-stack NEW-VALUE (EXIT-STACK-CONTEXT exit-stack-context)

automatically generated writer method

Source

exit-stack-context.lisp (file)

6.2.3 Classes

Class: error-context ()

Package

it.unimib.disco.ma.cl.ext.dacf.with-contexts

Source

exit-stack-context.lisp (file)

Direct superclasses

context (class)

Direct methods

• is-error-context (method)
• error-context-condition (method)
• error-context-item (method)

Direct slots

Slot: ctx

Initargs

:item

Readers

error-context-item (generic function)

Slot: cnd

Initargs

:condition, :error

Readers

error-context-condition (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types