The symbol-namespaces Reference Manual

Table of Contents

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

The symbol-namespaces Reference Manual

This is the symbol-namespaces Reference Manual, version 1.0, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 15:49:55 2018 GMT+0.


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

1 Introduction

Project's home: http://www.hexstreamsoft.com/projects/symbol-namespaces/


Defines a new kind of package that's named by a symbol rather than a
string and that maps from existing symbols to their respective
"implicitly managed" counterparts. The motivating use-case is to
conceptually allow multiple definitions of the same kind on a single
symbol, without conflicts.


PACKAGES
--------

symbol-namespaces exports a single package called SYMBOL-NAMESPACES,
also nicknamed SYMSPACES and SYMSPACE. This package is designed for
explicit qualification of symbols, such as symspace:namespace.
Don't (:use)!

(In this documentation, "namespace" means "symbol-namespace".)


API Overview
------------

The only strict guarantee obeyed by all namespace classes is that they
inherit from symspace:namespace and implement symspace:find-symbol and
symspace:intern-symbol.

Namespace classes may also inherit from symspace:packages, in which
case they also support at least the symspace:find-package and
symspace:intern-package operations.


The main operators of interest for "normal" users of the library are:

- Macro symspace:define defines a namespace and gives it a global name
  (symbol), or redefines an existing one;

- Function symspace:locate retrieves a namespace by name;

- Generic Function symspace:find-symbol retrieves the "implicitly
  managed" counterpart of a symbol in a namespace, if there is one, or
  else returns NIL.

- Generic Function symspace:intern-symbol attempts to
  symspace:find-symbol, and if the search is unsuccessful, creates and
  returns an appropriate implicitly managed counterpart for the
  symbol.


The rest of the API mostly has to do with making it easy to define
custom kinds of namespaces with extended behavior.

For simple uses, it's usually enough to subclass
symspace:standard-namespace and refine behavior by adding new methods
on appropriate generic functions.

For heavier customization, one can subclass symspace:namespace
directly, and define appropriate methods to implement the contract of
generic functions. It's easy to inherit standard pieces of state and
behavior with the provided mixins. symspace:standard-namespace really
just inherits from such mixins.


API Details
-----------

Macro symspace:define name &body options
=> new-or-redefined-namespace

Defines a namespace and gives it a global NAME (symbol),
or redefines an existing one.

The expansion calls symspace:ensure with the NAME and the OPTIONS,
converted from an alist to a plist. If the :class option is specified,
it must have only one argument, which is the class designator which
will be forwarded to symspace:ensure. Otherwise, the default is
symspace:standard-namespace. symspace:standard-namespace doesn't
support any options other than :class, but other subclasses of
symspace:namespace might. In that case, the value of the option in the
plist will be a list of the CDR of the option. For instance, an option
of (:option 1 2 3) would produce ":option (1 2 3)" in the plist.
Neither the option keys nor values are evaluated.


Function symspace:ensure name
  &rest keys &key (class 'symspace:standard-namespace) &allow-other-keys
=> new-or-redefined-namespace

Creates a new namespace named NAME, or redefines it if it already
exists.

If a new namespace is created, it will be of class CLASS and the other
KEYS are passed to MAKE-INSTANCE.

If a namespace with that name is already registered, then if the CLASS
is different than the class of the existing instance, CHANGE-CLASS is
called with the CLASS and other KEYS. If the CLASS is the same, then
REINITIALIZE-INSTANCE is called with the instance and the other KEYS.


Accessor symspace:LOCATE name &key (errorp t)
=> namespace-or-nil

Returns the namespace registered with name NAME. If there is no
registered namespace with name NAME, then an error is signaled if
ERRORP is true, else NIL is returned.


Generic Function symspace:NAME
=> name

Retrieves the name of a namespace. Typically implemented by
symspace:name-mixin.


Mixin Class symspace:NAME-MIXIN

Provides a slot of type SYMBOL, filled by initarg :name, whose value
is retrieved by symspace:name. Also provides a PRINT-OBJECT method
that includes the name of the namespace in its output.


Marker Class symspace:NAMESPACE

All namespace kinds inherit from this class. At least
symspace:find-symbol and symspace:intern-symbol are supported.
symspace:standard-namespace provides a ready-to-use implementation.


Generic Function symspace:INTERN-SYMBOL symbol symbol-namespace
=> symbol

Argument precedence order: symbol-namespace, symbol

Attempts to symspace:FIND-SYMBOL, and if the search is unsuccessful,
creates and returns an appropriate implicitly managed counterpart for
the symbol.


Generic Function symspace:FIND-SYMBOL symbol symbol-namespace
=> symbol-or-nil

Argument precedence order: symbol-namespace, symbol

Retrieves the "implicitly managed" counterpart of a symbol in a
namespace, if there is one, or else returns NIL.


Marker Class symspace:PACKAGES

Namespace classes inheriting from this class implicitly manage some
packages internally, and support the symspace:find-package and
symspace:intern-package operations. A related operation that might be
supported is symspace:make-package-name, potentially used by
symspace:intern-package.

See symspace:packages-identity-mixin and symspace:packages-name-mixin
for built-in implementations. symspace:standard-namespace uses the
former.


Generic Function symspace:INTERN-PACKAGE package symbol-namespace
=> package

Argument precedence order: symbol-namespace, package

Attempts to symspace:FIND-PACKAGE, and if the search is unsuccessful,
creates and returns an appropriate implicitly managed counterpart for
the package.


Generic Accessor symspace:FIND-PACKAGE package symbol-namespace
=> package-or-nil

Argument precedence order: symbol-namespace, package

Retrieves the "implicitly managed" counterpart of a package in a
namespace, if there is one, or else returns NIL.


Generic Function symspace:MAKE-PACKAGE-NAME package symbol-namespace
=> name

Computes an appropriate package name for a new "implicitly managed"
counterpart of PACKAGE.


Mixin Class symspace:PACKAGES-IDENTITY-MIXIN

Implements symspace:packages. Packages are found and interned on the
basis of their identity (EQ comparison of packages). This is what
symspace:standard-namespace uses.


Mixin Class symspace:PACKAGES-NAME-MIXIN

Implements symspace:packages. Packages are found and interned on the
basis of equality of their package names.


Class symspace:STANDARD-NAMESPACE

A ready-to-use implementation of symspace:namespace. Simply inherits
from symspace:name-mixin, symspace:packages-identity-mixin, and
symspace:namespace.



This library is in the Public Domain.
See the UNLICENSE file for details.


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 symbol-namespaces

Author

Jean-Philippe Paradis <hexstream@gmail.com>

License

Public Domain

Description

Defines a new kind of package that’s named by a symbol rather than a string and that maps from existing symbols to their respective "implicitly managed" counterparts. The motivating use-case is to conceptually allow multiple definitions of the same kind on a single symbol, without conflicts.

Version

1.0

Dependency

map-bind

Source

symbol-namespaces.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 symbol-namespaces.asd

Location

symbol-namespaces.asd

Systems

symbol-namespaces (system)


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

3.1.2 symbol-namespaces/package.lisp

Parent

symbol-namespaces (system)

Location

package.lisp

Packages

symbol-namespaces


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

3.1.3 symbol-namespaces/main.lisp

Dependency

package.lisp (file)

Parent

symbol-namespaces (system)

Location

main.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 symbol-namespaces

Source

package.lisp (file)

Nicknames
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 Macros

Macro: define NAME &body OPTIONS
Package

symbol-namespaces

Source

main.lisp (file)


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

5.1.2 Functions

Function: ensure NAME &rest KEYS &key CLASS &allow-other-keys
Package

symbol-namespaces

Source

main.lisp (file)

Function: locate NAME &key ERRORP
Function: (setf locate) NEW NAME &key ERRORP
Package

symbol-namespaces

Source

main.lisp (file)


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

5.1.3 Generic functions

Generic Function: find-package PACKAGE SYMBOL-NAMESPACE
Generic Function: (setf find-package) NEW PACKAGE SYMBOL-NAMESPACE
Package

symbol-namespaces

Source

main.lisp (file)

Methods
Method: find-package (PACKAGE package) (SYMBOL-NAMESPACE packages-identity-mixin)
Method: (setf find-package) NEW (PACKAGE package) (SYMBOL-NAMESPACE packages-identity-mixin)
Method: find-package (PACKAGE package) (SYMBOL-NAMESPACE packages-name-mixin)
Method: (setf find-package) NEW (PACKAGE package) (SYMBOL-NAMESPACE packages-name-mixin)
Generic Function: find-symbol SYMBOL SYMBOL-NAMESPACE
Package

symbol-namespaces

Source

main.lisp (file)

Methods
Method: find-symbol (SYMBOL symbol) (SYMBOL-NAMESPACE packages)
Generic Function: intern-package PACKAGE SYMBOL-NAMESPACE
Package

symbol-namespaces

Source

main.lisp (file)

Methods
Method: intern-package (PACKAGE package) (SYMBOL-NAMESPACE namespace)
Generic Function: intern-symbol SYMBOL SYMBOL-NAMESPACE
Package

symbol-namespaces

Source

main.lisp (file)

Methods
Method: intern-symbol (SYMBOL symbol) (SYMBOL-NAMESPACE packages)
Generic Function: make-package-name PACKAGE SYMBOL-NAMESPACE
Package

symbol-namespaces

Source

main.lisp (file)

Methods
Method: make-package-name (PACKAGE package) (SYMBOL-NAMESPACE namespace)
Generic Function: name NAMESPACE
Package

symbol-namespaces

Source

main.lisp (file)

Methods
Method: name (NAME-MIXIN name-mixin)

automatically generated reader method


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

5.1.4 Classes

Class: name-mixin ()
Package

symbol-namespaces

Source

main.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

standard-namespace (class)

Direct methods
  • print-object (method)
  • name (method)
Direct slots
Slot: %name
Type

symbol

Initargs

:name

Readers

name (generic function)

Class: namespace ()
Package

symbol-namespaces

Source

main.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

standard-namespace (class)

Direct methods
Class: packages ()
Package

symbol-namespaces

Source

main.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods
Class: packages-identity-mixin ()
Package

symbol-namespaces

Source

main.lisp (file)

Direct superclasses

packages (class)

Direct subclasses

standard-namespace (class)

Direct methods
Direct slots
Slot: %packages
Initform

(make-hash-table :test (quote eq))

Readers

%packages (generic function)

Class: packages-name-mixin ()
Package

symbol-namespaces

Source

main.lisp (file)

Direct superclasses

packages (class)

Direct methods
Direct slots
Slot: %packages
Initform

(make-hash-table :test (quote equal))

Readers

%packages (generic function)

Class: standard-namespace ()
Package

symbol-namespaces

Source

main.lisp (file)

Direct superclasses

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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *namespaces*
Package

symbol-namespaces

Source

main.lisp (file)


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

5.2.2 Functions

Function: %call-with-package-name FUNCTION PACKAGE
Package

symbol-namespaces

Source

main.lisp (file)

Function: %remove-keys KEYS PLIST
Package

symbol-namespaces

Source

main.lisp (file)


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

5.2.3 Generic functions

Generic Function: %packages OBJECT
Package

symbol-namespaces

Methods
Method: %packages (PACKAGES-NAME-MIXIN packages-name-mixin)

automatically generated reader method

Source

main.lisp (file)

Method: %packages (PACKAGES-IDENTITY-MIXIN packages-identity-mixin)

automatically generated reader method

Source

main.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, symbol-namespaces.asd: The symbol-namespaces<dot>asd file
File, Lisp, symbol-namespaces/main.lisp: The symbol-namespaces/main<dot>lisp file
File, Lisp, symbol-namespaces/package.lisp: The symbol-namespaces/package<dot>lisp file

L
Lisp File, symbol-namespaces.asd: The symbol-namespaces<dot>asd file
Lisp File, symbol-namespaces/main.lisp: The symbol-namespaces/main<dot>lisp file
Lisp File, symbol-namespaces/package.lisp: The symbol-namespaces/package<dot>lisp file

S
symbol-namespaces.asd: The symbol-namespaces<dot>asd file
symbol-namespaces/main.lisp: The symbol-namespaces/main<dot>lisp file
symbol-namespaces/package.lisp: The symbol-namespaces/package<dot>lisp file

Jump to:   F   L   S  

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

A.2 Functions

Jump to:   %   (  
D   E   F   G   I   L   M   N  
Index Entry  Section

%
%call-with-package-name: Internal functions
%packages: Internal generic functions
%packages: Internal generic functions
%packages: Internal generic functions
%remove-keys: Internal functions

(
(setf find-package): Exported generic functions
(setf find-package): Exported generic functions
(setf find-package): Exported generic functions
(setf locate): Exported functions

D
define: Exported macros

E
ensure: Exported functions

F
find-package: Exported generic functions
find-package: Exported generic functions
find-package: Exported generic functions
find-symbol: Exported generic functions
find-symbol: Exported generic functions
Function, %call-with-package-name: Internal functions
Function, %remove-keys: Internal functions
Function, (setf locate): Exported functions
Function, ensure: Exported functions
Function, locate: Exported functions

G
Generic Function, %packages: Internal generic functions
Generic Function, (setf find-package): Exported generic functions
Generic Function, find-package: Exported generic functions
Generic Function, find-symbol: Exported generic functions
Generic Function, intern-package: Exported generic functions
Generic Function, intern-symbol: Exported generic functions
Generic Function, make-package-name: Exported generic functions
Generic Function, name: Exported generic functions

I
intern-package: Exported generic functions
intern-package: Exported generic functions
intern-symbol: Exported generic functions
intern-symbol: Exported generic functions

L
locate: Exported functions

M
Macro, define: Exported macros
make-package-name: Exported generic functions
make-package-name: Exported generic functions
Method, %packages: Internal generic functions
Method, %packages: Internal generic functions
Method, (setf find-package): Exported generic functions
Method, (setf find-package): Exported generic functions
Method, find-package: Exported generic functions
Method, find-package: Exported generic functions
Method, find-symbol: Exported generic functions
Method, intern-package: Exported generic functions
Method, intern-symbol: Exported generic functions
Method, make-package-name: Exported generic functions
Method, name: Exported generic functions

N
name: Exported generic functions
name: Exported generic functions

Jump to:   %   (  
D   E   F   G   I   L   M   N  

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

A.3 Variables

Jump to:   %   *  
S  
Index Entry  Section

%
%name: Exported classes
%packages: Exported classes
%packages: Exported classes

*
*namespaces*: Internal special variables

S
Slot, %name: Exported classes
Slot, %packages: Exported classes
Slot, %packages: Exported classes
Special Variable, *namespaces*: Internal special variables

Jump to:   %   *  
S  

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

A.4 Data types

Jump to:   C   N   P   S  
Index Entry  Section

C
Class, name-mixin: Exported classes
Class, namespace: Exported classes
Class, packages: Exported classes
Class, packages-identity-mixin: Exported classes
Class, packages-name-mixin: Exported classes
Class, standard-namespace: Exported classes

N
name-mixin: Exported classes
namespace: Exported classes

P
Package, symbol-namespaces: The symbol-namespaces package
packages: Exported classes
packages-identity-mixin: Exported classes
packages-name-mixin: Exported classes

S
standard-namespace: Exported classes
symbol-namespaces: The symbol-namespaces system
symbol-namespaces: The symbol-namespaces package
System, symbol-namespaces: The symbol-namespaces system

Jump to:   C   N   P   S