The new-op Reference Manual

This is the new-op Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:12:18 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 new-op

The NEW-OP System.

A (not so) new NEW operator that subsumes all the ’make-...’ functions and methods of Common Lisp.

Author

Marco Antoniotti

License

BSD

Source

new-op.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 new-op/new-op.asd

Source

new-op.asd.

Parent Component

new-op (system).

ASDF Systems

new-op.


3.1.2 new-op/new-op-pkg.lisp

Source

new-op.asd.

Parent Component

new-op (system).

Packages

it.unimib.disco.ma.cl.ext.tac.new-op.


3.1.3 new-op/new-op.lisp

Dependency

new-op-pkg.lisp (file).

Source

new-op.asd.

Parent Component

new-op (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 it.unimib.disco.ma.cl.ext.tac.new-op

Source

new-op-pkg.lisp.

Nicknames
  • common-lisp.extensions.type-and-classes.new-op
  • cl.ext.tac.new-op
  • new-op
Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *coerce-array-elements-p*

If true array initial elements are coerced to the expected type.

The default is NIL.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Special Variable: *coerce-numbers-p*

If true numbers are coerced to the expected type (in number constructors).

The default is NIL.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


5.1.2 Macros

Macro: newq (what &rest arguments)

The NEWQ macro is a convenience syntactic shortcut to the NEW function.

The macro expands into a call to NEW without evaluating the first argument.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


5.1.3 Ordinary functions

Function: register-structure-constructor (sc constructor)

Registers CONSTRUCTOR for structure class SC.

The CONSTRUCTOR will then be available to NEW whenever a SC needs to be created.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


5.1.4 Generic functions

Generic Function: new (what &rest arguments)

Generic ’construction’ function.

The NEW generic function is a single entry point for MAKE-INSTANCE, DEFSTRUCT and other constructors, e.g., for HASH-TABLEs and ARRAYs.

Methods for NEW can be defined specialized for new classes. Structure classes need to register their constuctor; see REGISTER-STRUCTURE-CONSTRUCTOR. Compound type specifiers must be specialized by defining methods for TYPE-CONS.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Methods
Method: new ((what (eql bit)) &rest arguments)
Method: new ((what (eql unsigned-byte)) &rest arguments)
Method: new ((what (eql signed-byte)) &rest arguments)
Method: new ((what cons) &rest arguments)

CONS Method.

This is the method that handles the compound type specifiers. It eventually calls TYPE-CONS, which is in charge of dealing with each compound type specifier.

In order to inform the NEW operator of a new compound type specifier it is thus sufficient to define an appropriate TYPE-CONS method.

Method: new ((what (eql it.unimib.disco.ma.cl.ext.tac.new-op::hash-set)) &rest arguments)

HASH-SET Method.

A specialised method yielding a HASH-TABLE with BOOLEAN values. It can be invoked in two forms.
<pre>
new ’HASH-SET
&optional SEQUENCE-SET
&rest HASH-TABLE-STANDARD-ARGS
&key &allow-other-keys
</pre>
or
<pre>
new ’HASH-SET
&rest HASH-TABLE-STANDARD-ARGS
&key &allow-other-keys
</pre>

I.e., it dispatches on the first of the ARGUMENTS to decide whether it also has to ’fill’ the newly created hash table; in this last case, it behaves as a ’copy’ constructor for the hash-table skeleton, and then it substitutes the values or the resulting hash-table with T. If the first of the ARGUMENTS is a hash-table, the keywords are ignored. If it is a keyword then it is assumed that the call must resolve to a simple call to MAKE-HASH-TABLE. Otherwise, <sequence-set> must be an SEQUENCE of elements of the set.

The result is an hash table.

Method: new ((what (eql #<structure-class common-lisp:hash-table>)) &rest arguments)

HASH-TABLE Method.

The HASH-TABLE method admits a non-traditional syntax. It can be invoked in two forms.
<pre>
new ’HASH-TABLE
&optional PAIRS
&rest HASH-TABLE-STANDARD-ARGS
&key &allow-other-keys
</pre>
or
<pre>
new ’HASH-TABLE
&rest HASH-TABLE-STANDARD-ARGS
&key &allow-other-keys
</pre>

I.e., it dispatches on the first of the ARGUMENTS to decide whether it also has to ’fill’ the newly created hash table; in this last case, it behaves as a ’copy’ constructor. If the first of the ARGUMENTS is a hash-table, the keywords are ignored. If it is a keyword then it is assumed that the call must resolve to a simple call to MAKE-HASH-TABLE. Otherwise, <pairs> must be an A-LIST of pairs <pre>
(key . value)
</pre>
which are then fed into the newly created hash-table.

The result is an hash table.

Method: new ((what (eql #<built-in-class common-lisp:double-float>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:single-float>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:fixnum>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:integer>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:ratio>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:rational>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:float>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:real>)) &rest arguments)
Method: new ((what (eql #<built-in-class common-lisp:complex>)) &rest arguments)

COMPLEX Method.

The COMPLEX method applies the function COMPLEX to the arguments.

Method: new ((what (eql #<built-in-class common-lisp:number>)) &rest arguments)

NUMBER Method.

The NUMBER method just checks that the argument is a number and returns it.

Method: new ((what (eql #<built-in-class common-lisp:pathname>)) &rest arguments)

PATHNAME Method.

The PATHNAME method dispatches on the first element of ARGUMENTS. If it is a KEYWORD, it assumes that MAKE-PATHNAME is to be called, applied to all the ARGUMENTS.
Otherwise it checks whether the first of ARGUMENTS ia a STRING, a STREAM or a PATHNAME, in which case is passes it to the function PATHNAME.

Method: new ((what (eql #<built-in-class common-lisp:symbol>)) &rest arguments)

SYMBOL Method.

The SYMBOL method has the following syntax.
<pre>
new ’symbol S &optional (PACKAGE *PACKAGE*) COPY-PROPERTIES </pre>
S can be a STRING or a SYMBOL. If it is a SYMBOL, S is first copied, using COPY-SYMBOL and COPY-PROPERTIES (cfr., COPY-SYMBOL in the CL Standard). If S is a STRING then MAKE-SYMBOL is initially called. If PACKAGE is NIL then a fresh, uninterned symbol is returned, otherwise the resulting symbol is IMPORTed in PACKAGE.

Method: new ((what (eql #<built-in-class common-lisp:character>)) &rest arguments)

CHARACTER Method.

Applies the function CHARACTER to the first of ARGUMENTS.

Method: new ((what (eql #<built-in-class common-lisp:list>)) &rest arguments)

LIST Method.

Applies the function VECTOR to the ARGUMENTS.

Method: new ((what (eql #<built-in-class common-lisp:string>)) &rest arguments)

STRING Method.

Applies the function STRING to the first of ARGUMENTS.

Method: new ((what (eql #<built-in-class common-lisp:vector>)) &rest arguments)

VECTOR Method.

Applies the function VECTOR to the ARGUMENTS.

Method: new ((what (eql #<built-in-class common-lisp:array>)) &rest arguments)

ARRAY Method.

Calls MAKE-ARRAY after having manipulated the ARGUMENTS.
The ’bare’ constructor for objects of ’type’ ARRAY actually behaves as having the following simple syntax:
<pre>
new ’array &optional INITIAL-CONTENTS &rest MAKE-ARRAY-keywords </pre>
I.e., the constructor figures out the dimensions of the INITIAL-CONTENTS before dispatching to MAKE-ARRAY.

Method: new :around ((what class) &rest arguments)

CLASS Around Method.

This method helps dealing with some of the vagaries of the CL type system, e.g., COMPLEX and RATIONAL types with their relationship.

Method: new ((what built-in-class) &rest arguments)

BUILT-IN-CLASS Method.

Signals an ’undefined’ error. This method is a sink for the built-in classes which do not have a specialized method built with EQL.

Method: new ((what structure-class) &rest arguments)

STRUCTURE-CLASS Method.

Applies the constructor of the STRUCTURE-CLASS to the ARGUMENTS. The constructor must have been registered with REGISTER-STRUCTURE-CONSTRUCTOR to be applicable.

Method: new ((what standard-class) &rest arguments)

STANDARD-CLASS Method.

Applies MAKE-INSTANCE to the class and ARGUMENTS. This method is, to all effects, MAKE-INSTANCE in disguise.

Method: new ((what symbol) &rest arguments)

SYMBOL Method.

Dispatches on the class named by the argument.

Generic Function: type-cons (type-name spec arguments)

The TYPE-CONS Generic Function.

TYPE-CONS is the entry point to specialize in order to handle compound type specifiers. The only assumption is that a compound type specifier is a list with a symbol as first element, as described in Section 4.2.3 ’Type Specifiers’ of the ANSI CL Specification.

Each method dispatches on the TYPE-NAME, which is a symbol. SPEC is the CDR of the full type specifier and ARGUMENTS is the list of arguments passed to NEW.

TYPE-CONS is meant to be specialized but not called directly.

Examples:

;;; Suppose you had

(deftype matrix (n m &optional (base-type ’double-float))
‘(array ,base-type (,n ,m)))

;;; You may want to define something along these lines.

(defmethod type-cons ((what (eql ’matrix)) spec arguments) (destructuring-bind (n m &optional (base-type ’double-float)) spec
(assert (and (<= 0 n (1- array-dimension-limit))
(<= 0 m (1- array-dimension-limit))))
(apply #’make-array (list n m)
:element-type base-type
arguments)))

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Methods
Method: type-cons ((what (eql class)) spec arguments)
Method: type-cons ((what (eql structure)) spec arguments)
Method: type-cons ((what (eql hash-table)) spec arguments)

The HASH-TABLE Method.

It constructs a HASH-TABLE by handling a ’type specifier’ with a
syntax that makes the following call the NEW possible:
<pre>
(new ’(hash-table &rest HT-KEYS
&key
(TEST #’eql)
(SIZE (hash-table-size *default-dummy-hash-table*))
(REHASH-SIZE (hash-table-rehash-size *default-dummy-hash-table*)) (REHASH-THRESHOLD (hash-table-rehash-threshold *default-dummy-hash-table*)) &allow-other-keys)
&rest arguments)
</pre>
The defaults for each of the keyword arguments are implementation dependent.

Method: type-cons ((what (eql mod)) spec arguments)
Method: type-cons ((what (eql unsigned-byte)) spec arguments)
Method: type-cons ((what (eql signed-byte)) spec arguments)
Method: type-cons ((what symbol) spec arguments)
Method: type-cons ((what (eql complex)) spec arguments)
Method: type-cons ((what (eql array)) spec arguments)

ARRAY Method.

It constructs an array after having manipulated SPEC and ARGUMENTS; the overall effect is similar to the NEW ARRAY method.
The TYPE-CONS method allows NEW to use the following syntax: <pre>
new ’(array &optional
(ELEMENT-TYPE T)
DIMENSION-SPEC
&rest MAKE-ARRAY-kwds-1
&key
&allow-other-keys)
&optional
INITIAL-CONTENTS
&rest MAKE-ARRAY-kwds-2
&key
&allow-other-keys
</pre>

I.e., the constructor figures out the dimensions of the <initial-contents> before dispatching to MAKE-ARRAY. Further checks are made to ensure that the shape of <initial-contents> (if supplied) is acceptable.

MAKE-ARRAY-kwds-1 and MAKE-ARRAY-kwds-2 are the normal MAKE-ARRAY parameters. The actual call to MAKE-ARRAY is eventually of the form: <pre>
(apply ’make-array
COMPUTED-DIMENSIONS
(append
(and INITIAL-CONTENTS
(list :initial-contents INITIAL-CONTENTS)) MAKE-ARRAY-kwd-1
MAKE-ARRAY-kwd-2))
</pre>
Therefore, order among the MAKE-ARRAY keywords is important.
It should be noted that
<pre>
(array &optional (ELEMENT-TYPE T) DIMENSION-SPEC)
</pre>
is a valid, yet constrained, type specifier.

Method: type-cons ((what (eql vector)) spec arguments)

5.2 Internals


5.2.1 Special variables

Special Variable: *default-dummy-hash-table*
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Special Variable: *structure-constructors*
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


5.2.2 Macros

Macro: check-optional-args-number (arglist min max &optional after)

Utility macro producing ASSERTs that check the number of arguments.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Macro: type-check (place type)

Checks that PLACE contains an object of type TYPE.

It works like CHECK-TYPE, but TYPE is evaluated. It also returns T if the check succeeds.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


5.2.3 Ordinary functions

Function: check-numeric-interval-element (n num-type-name l u)
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Function: compute-data-dimensions (data &optional rank error-if-unequal-p)

Computes the dimensions of DATA.

DATA is a sequence of nested sequences. RANK can be passed to limit the depth of the reconstruction; if NIL (the default) the dimensions are computed down to ’atoms’. ERROR-IF-UNEQUAL-P controls whether an error is signalled if the shape of DATA is ’ragged’. An error is also signalled if RANK is higher than the actual DATA rank.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Function: compute-dimensions (rank data)
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Function: copy-hash-table (ht)

Copies and HASH-TABLE.

This function is implementation dependent. The basic behavior provided here just copies an hash-table with the standard components.

Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Function: find-structure-constructor (sc &optional errorp)
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Function: make-rational (n &optional d)
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


5.2.4 Generic functions

Generic Function: interval-type-cons (num-type lower-bound upper-bound arguments)
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.

Methods
Method: interval-type-cons ((num-type (eql fixnum)) l u arguments)
Method: interval-type-cons ((num-type (eql rational)) l u arguments)
Method: interval-type-cons :before ((num-type symbol) l u arguments)
Method: interval-type-cons ((num-type symbol) l u arguments)

5.2.5 Types

Type: numeric-real-types ()
Package

it.unimib.disco.ma.cl.ext.tac.new-op.

Source

new-op.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   C   F   G   I   M   N   R   T  
Index Entry  Section

C
check-numeric-interval-element: Private ordinary functions
check-optional-args-number: Private macros
compute-data-dimensions: Private ordinary functions
compute-dimensions: Private ordinary functions
copy-hash-table: Private ordinary functions

F
find-structure-constructor: Private ordinary functions
Function, check-numeric-interval-element: Private ordinary functions
Function, compute-data-dimensions: Private ordinary functions
Function, compute-dimensions: Private ordinary functions
Function, copy-hash-table: Private ordinary functions
Function, find-structure-constructor: Private ordinary functions
Function, make-rational: Private ordinary functions
Function, register-structure-constructor: Public ordinary functions

G
Generic Function, interval-type-cons: Private generic functions
Generic Function, new: Public generic functions
Generic Function, type-cons: Public generic functions

I
interval-type-cons: Private generic functions
interval-type-cons: Private generic functions
interval-type-cons: Private generic functions
interval-type-cons: Private generic functions
interval-type-cons: Private generic functions

M
Macro, check-optional-args-number: Private macros
Macro, newq: Public macros
Macro, type-check: Private macros
make-rational: Private ordinary functions
Method, interval-type-cons: Private generic functions
Method, interval-type-cons: Private generic functions
Method, interval-type-cons: Private generic functions
Method, interval-type-cons: Private generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, new: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions
Method, type-cons: Public generic functions

N
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
new: Public generic functions
newq: Public macros

R
register-structure-constructor: Public ordinary functions

T
type-check: Private macros
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions
type-cons: Public generic functions