The incognito-keywords Reference Manual

Table of Contents

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

The incognito-keywords Reference Manual

This is the incognito-keywords Reference Manual, version 1.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:04:35 2018 GMT+0.


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

1 Introduction

Project's home: http://www.hexstreamsoft.com/projects/incognito-keywords/


incognito-keywords introduces a new kind of keyword that looks just
like any non-keyword symbol and allows safe usage of convenient but
clashy symbol names by multiple libraries without conflicts through
sharing. Some names that might benefit are (alist blist plist macro
operator index &doc &decl &rest+ &destructure &ignored &ignorable).


Some hypothetical examples
--------------------------

incognito keywords, or "ikeywords" for short, are useful targets for
various kinds of dispatching.

(define (macro my-macro) ...) ; MACRO being an ikeyword

;; blends much better with:
(define (variable my-variable) ...) ; VARIABLE is exported from CL.

;; than would:
(define (:macro my-macro))

;; And the following:
(define (macro my-macro) ...) ; MACRO a normal symbol
;; would very likely result in symbol conflicts.

(map 'alist ...) ; ALIST being an ikeyword

;; INDEX, &IGNORED and PLIST being ikeywords
(do-for ((i (index :from 1)) 
         (((&ignored key) value) (plist my-plist)))
  ...)

(ikeywords:defpackage #:do-for.ikeywords
  (:export #:index
           #:&ignored
           #:plist
           ...))

(defpackage #:do-for-user-package
  (:use #:cl #:do-for-ikeywords)
  (:import-from #:do-for #:do-for))

(locate 'macro "my-macro")

In the examples above, DEFINE, MAP, DO-FOR and LOCATE could come from
different libraries by different authors. If they all use ikeywords as
appropriate, then their users can use all these libraries from one
package without symbol conflicts!


API
---

Usage of incognito-keywords is very easy!

First of all, in the way of packages there's the INCOGNITO-KEYWORDS
package, which is also nicknamed IKEYWORDS. It exports the functions
(PACKAGE ENSURE IKEYWORDP) and the macro DEFPACKAGE. These symbols
should be explicitly qualified. For example, ikeywords:defpackage
instead of (:use #:ikeywords) or (:import-from #:ikeywords
#:defpackage).

ikeywords live in the IKEYWORD package (also nicknamed "I") and are
typically created implicitly with ikeywords:defpackage, but it's also
possible to create some dynamically with ikeywords:ensure.


macro ikeywords:DEFPACKAGE name &rest options => new-or-redefined-package

  A very simplified version of cl:defpackage dedicated to creation of
  "ikeyword packages". The syntax is just like cl:defpackage, except
  that only the :export, :nicknames, :documentation and :size options
  are supported. The package will implicitly use the IKEYWORD package.
  All the symbol names in :export clauses will be passed to ENSURE.
  The :nicknames, :documentation and :size options are passed straight
  through to cl:defpackage.

  It's possible to obtain a list of all ikeyword packages with:
  (package-used-by-list (ikeywords:package))


function ikeywords:ENSURE name => new-or-existing-ikeyword

  If NAME already names an ikeyword (a symbol in the IKEYWORD
  package), then return that ikeyword.

  Else, create the ikeyword (interning a symbol with that name in the
  IKEYWORD package), immediately export it (from the IKEYWORD
  package), then return the new ikeyword.

  Attempting to create an ikeyword with the name of one of the 978
  symbols in the COMMON-LISP package is an error, as this would almost
  inevitably result in symbol conflicts, which would defeat the whole
  point of ikeywords!


function ikeywords:PACKAGE => ikeyword-package

  This convenience function simply returns the IKEYWORD package.
  Basically equivalent to (find-package '#:ikeyword).


function ikeywords:IKEYWORDP object => generalized-boolean

  This convenience function simply returns true if the OBJECT is a
  symbol and its home package (as returned by SYMBOL-PACKAGE) is the
  IKEYWORD package, else it returns false.


Restrictions to avoid definition conflicts
------------------------------------------

incognito-keywords' reason to exist is to allow libraries to make use
of some very desirable symbol names, while avoiding the excessive
symbol conflicts this would normally incur. HOWEVER, INCORRECT USAGE
OF THIS LIBRARY COULD ACTUALLY INCREASE (DEFINITION) CONFLICTS. So
please carefully read and understand the following:

Libraries should not create global definitions for Common Lisp
functions, macros, SETF expanders, etc. on ikeywords, as any two
libraries that do this can't be safely loaded in the same image.

However, if a library creates a new kind of definition in another
"namespace", then this library can safely create such definitions on
these symbols. However, if that library exports a way to create such
definitions, then users of that library can't safely create such
definitions on ikeywords.

For this reason, libraries in this situation should provide any
appropriate definitions on ikeywords using their new exported
definition mechanisms, and prohibit their users, through mechanism
and/or policy, from providing any new definitions on those ikeywords.


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 incognito-keywords

Author

Jean-Philippe Paradis <hexstream@gmail.com>

License

Public Domain

Description

incognito-keywords introduces a new kind of keyword that looks just like any non-keyword symbol and allows safe usage of convenient but clashy symbol names by multiple libraries without conflicts through sharing. Some names that might benefit are (alist blist plist macro operator index &doc &decl &rest+ &destructure &ignored &ignorable).

Version

1.1

Dependencies
Source

incognito-keywords.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 incognito-keywords.asd

Location

incognito-keywords.asd

Systems

incognito-keywords (system)


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

3.1.2 incognito-keywords/package.lisp

Parent

incognito-keywords (system)

Location

package.lisp

Packages

incognito-keywords


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

3.1.3 incognito-keywords/main.lisp

Dependency

package.lisp (file)

Parent

incognito-keywords (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 incognito-keywords

Source

package.lisp (file)

Nickname

ikeywords

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: defpackage NAME &rest OPTIONS
Package

incognito-keywords

Source

main.lisp (file)


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

5.1.2 Functions

Function: ensure NAME
Package

incognito-keywords

Source

main.lisp (file)

Function: ikeywordp OBJECT
Package

incognito-keywords

Source

main.lisp (file)

Function: package ()
Package

incognito-keywords

Source

main.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *%cl-package*
Package

incognito-keywords

Source

main.lisp (file)

Special Variable: *%package*
Package

incognito-keywords

Source

main.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   I   L  
Index Entry  Section

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

I
incognito-keywords.asd: The incognito-keywords<dot>asd file
incognito-keywords/main.lisp: The incognito-keywords/main<dot>lisp file
incognito-keywords/package.lisp: The incognito-keywords/package<dot>lisp file

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

Jump to:   F   I   L  

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

A.2 Functions

Jump to:   D   E   F   I   M   P  
Index Entry  Section

D
defpackage: Exported macros

E
ensure: Exported functions

F
Function, ensure: Exported functions
Function, ikeywordp: Exported functions
Function, package: Exported functions

I
ikeywordp: Exported functions

M
Macro, defpackage: Exported macros

P
package: Exported functions

Jump to:   D   E   F   I   M   P  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*%cl-package*: Internal special variables
*%package*: Internal special variables

S
Special Variable, *%cl-package*: Internal special variables
Special Variable, *%package*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   I   P   S  
Index Entry  Section

I
incognito-keywords: The incognito-keywords system
incognito-keywords: The incognito-keywords package

P
Package, incognito-keywords: The incognito-keywords package

S
System, incognito-keywords: The incognito-keywords system

Jump to:   I   P   S