Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

Documentation

A Chicken specific version of the SLIB "coerce.scm" module, which implements object type conversion.

The major difference here is the ability to extend the type domain.

TYPE-TAG is a symbol.

TYPE-PRED is a procedure, (object -> boolean), testing whether the argument is a type.

Type-Of

Determine the type of an object.

Usage

(require-extension type-of)

basic-type-of

[procedure] (basic-type-of OBJECT) => symbol

Returns a TYPE-TAG for the type of OBJECT.

TYPE-TAG is one-of unspecified, boolean, port, char, fixnum, flonum, string, symbol, pair, null, blob, procedure, pointer, tagged-pointer, swig-pointer, locative, record, or vector.

The types bucket & unbound are also identified but should never be available to non-system code.

The Types BASICTYPE tags are not used, specifically: float vs. flonum, undefined vs. unspecified, eof vs. eof-object, & struct vs. record. With enough feedback this can change.

type-of

[procedure] (type-of OBJECT) => symbol

Returns a TYPE-TAG for the type of OBJECT.

The TYPE-TAG is as for basic-type-of except port differentiates input-port & output-port, keyword is differentiated from symbol, and a record is identified as the record-instance-type.

basic-same-type?

[procedure] (basic-same-type? OBJECT-A OBJECT-B) => boolean

Is OBJECT-A the same basic type as OBJECT-B?

same-type?

[procedure] (same-type? OBJECT-A OBJECT-B) => boolean

Is OBJECT-A the same type as OBJECT-B?

When record the record-instance-type must match. When port must be same "direction".

Coerce

Translate an object into another type representation.

Usage

(require-extension type-coerce)

coerce

[procedure] (coerce OBJECT TYPE-TAG [DEFAULT-PROC]) => OBJECT

Converts OBJECT to a value of TYPE-TAG.

DEFAULT-PROC is a procedure with the signature (OBJECT TYPE-TAG -> OBJECT) and is invoked when coercion fails. The default is to signal an error.

Recognized types are as for extended-type-of.

coerce-all

[procedure] (coerce-all (OBJECT...) (TYPE-TAG...) [DEFAULT-PROC]) => LIST

Returns a list of every element of the (OBJECT...) coerced to the corresponding element of the (TYPE-TAG...).

DEFAULT-PROC is as for coerce.

Extended Coerce & Type-Of

Extend the type coercion and testing machinery.

Usage

(require-extension coerce-extend)

extended-type-of

[procedure] (extended-type-of OBJECT) => symbol

Returns a TYPE-TAG for the type of OBJECT.

The TYPE-TAG is as for type-of but includes the extended types.

type-of-extended?

[procedure] (type-of-extended? TYPE-TAG) => BOOLEAN

Is the domain extended to cover the type identifier TYPE-TAG.

type-of-extend!

[procedure] (type-of-extend! TYPE-TAG TYPE-PRED)

Extends the domain of type-of with the type definition (TYPE-TAG TYPE-PRED).

type-of-composite-extension!

[procedure] (type-of-composite-extension! TYPE-TAG TYPE-PRED)

Extends the domain of an existing type-of extension.

Should the new TYPE-PRED and existing TYPE-PRED be eq? the operation is ignored.

type-of-extension-remove!

[procedure] (type-of-extension-remove! TYPE-TAG)

Delete any existing type-of extension for TYPE-TAG.

make-case-coerce

[procedure] (make-case-coerce CONVERTOR [ALIST]) => PROCEDURE

Returns a coercion procedure for use with extend-coerce

CONVERTOR is a coercion procedure with the signature (OBJECT TYPE-TAG ON-ERROR -> object). ON-ERROR is a procedure/0 that is invoked when all else fails.

ALIST here is a list of (TYPE-TAG . (OBJECT -> OBJECT).

case-coerce

[syntax] (case-coerce CASE ...) => PROCEDURE

Returns a coercion procedure for use with extend-coerce.

CASE is of the form ((TYPE-TAG ...) EXPRESSION ...), or (else EXPRESSION ...).

The variable object is bound to the object to coerce within the scope of CASE ....

The variable on-error is bound to a thunk within the scope of CASE ...} to invoke upon failure.

(define (unspecified? obj) (eq? (void) obj))

(define unspecified-coerce
  (case-coerce
    ((char)     #\nul)
    ((number)   +nan)
    ((string)   "")
    ((symbol)   '||)
    ((list)     (list))
    ((vector)   (vector))))

(coerce-extend! 'unspecified unspecified? unspecified-coerce)

(type-of (void)) ;=> unspecified

(coerce-extend! 'string
  string?
  (case-coerce ((unspecified) (if (string=? "" object) (void) (on-error)))))

(coerce "" 'unspecified) ;=> (void)

coerce-extended?

[procedure] (coerce-extended? TYPE-TAG) => BOOLEAN

Is the domain extended to cover the type identifier TYPE-TAG.

coerce-extend!

[procedure] (coerce-extend! TYPE-TAG TYPE-PRED CONVERTOR)

Extends the domain of coerce with the type definition (TYPE-TAG TYPE-PRED CONVERTOR).

TYPE-PRED is a procedure, (object -> boolean), testing whether the argument is a type.

CONVERTOR is a procedure, (object symbol on-error -> object), converting from the type to a result type.

The CONVERTOR must invoke (on-error) when conversion not possible. Usually case-coerce would be used to create the CONVERTOR, which automatically handles calling of the on-error argument.

coerce-composite-extension!

[procedure] (coerce-composite-extension! TYPE-TAG TYPE-PRED CONVERTOR)

Extends the domain of an existing coerce extension.

TYPE-TAG, TYPE-PRED, and CONVERTOR are as for extend-coerce.

The new CONVERTOR is try'ed before the existing procedure, then the existing procedure is try'ed "on-error".

Should the new TYPE-PRED and existing TYPE-PRED be eq? the TYPE-PREDs are not "composited" using or.

coerce-extension-remove!

[procedure] (coerce-extension-remove! TYPE-TAG)

Delete any existing coerce extension for the type identifier TYPE-TAG.

Usage

(require-extension coerce)

Examples

(use type-of)

(basic-same-type? (current-output-port) (current-error-port)) ;=> #t
(same-type? (current-output-port) (current-error-port)) ;=> #t
(basic-same-type? (current-output-port) (current-input-port)) ;=> #t
(same-type? (current-output-port) (current-input-port)) ;=> #f

(basic-type-of (current-output-port)) ;=> port
(type-of (current-output-port)) ;=> output-port

Notes

When extending a type using type-of-extend! no corresponding extension is made for coerce. Please use coerce-extend! should this be required.
The coercion of a composite object to a scalar often makes little sense.
The coercion of a scalar object to a composite is usually just to box the object with the specified composite.
Renames some procedures from the Chicken 3 version.

Requirements

miscmacros lookup-table check-errors

Bugs and Limitations

Cannot know before attempt if coercion possible.

Author

Kon Lovett

Version history

2.1.0
2.0.1: Fix #1420.
2.0.0: Added basic-type-of, basic-same-type?, & same-type?. Made type-of own module. Use more specific type-tags.
1.1.0: Added pointer & locative. Catch-all is object.
1.0.0: Initial Chicken 4 release.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission to copy this software, to modify it, to redistribute it, to distribute modified versions, and to use it for any purpose is granted, subject to the following restrictions and understandings.

1. Any copy made of this software must include this copyright notice in full.

2. I have made no warranty or representation that the operation of this software will be error-free, and I am under no obligation to provide any services, by way of maintenance, update, or otherwise.

3. In conjunction with products arising from the use of this material, there shall be no use of my name in any advertising, promotional, or sales literature without prior written consent in each case.