8 Enumerations (revised)

(require (planet untyped/unlib/enumeration))

Utilities for defining simple enumerations of booleans, symbols and integers. These are useful wherever you would normally use a small collection of literals to represent possible values of a variable, and test for value equality with eq?. The define-enum form binds the literals to Scheme identifiers so the compiler catches typos that might otherwise take a long time to debug.

(struct enum (name values pretty-values))

name : symbol?

values : (listof (U boolean? symbol? integer?))

pretty-values : (listof string?)

An enumeration. For each symbol in values there is a human-readable string equivalent in pretty-values.

(enum->string enum [separator]) → string?

enum : enum?

separator : string? = ", "

Returns a string representation of (enum-values enum), useful for including in debugging output. separator is used to separate the enum values in the return value.

Examples:

> (define-enum vehicle (car boat plane))

> (enum->string vehicle)

"car, boat, plane"

(enum->pretty-string enum [separator]) → string?

enum : enum?

separator : string? = ", "

Returns a string representation of (enum-pretty-values enum), useful for describing the possible values to a user. separator is used to separate the enum values in the return value.

Examples:

> (define-enum vehicle (car boat plane))

> (enum->pretty-string vehicle)

"car, boat, plane"

(enum-value? enum value) → boolean?

enum : enum?

value : any

Returns #t if value is a member of (enum-values enum).

Examples:

> (define-enum vehicle (car boat plane))

> (enum-value? vehicle 'car)

#t

> (enum-value? vehicle 'apple)

#f

(enum-prettify enum value [default]) → string?

enum : enum?

value : symbol?

default   :   (U string? (-> string?))       =   (cut raise-exn exn:fail:contract ...)

Returns the pretty equivalent of value. If value is not found in enum, default is used instead:

• if default is a procedure, it is called to determine the return value;

• if default is not a procedure, it is returned.

(define-enum enum-id (value-clause ...) keyword-arg ...)

value-clause   =   value-id     |   [value-id pretty-expr]     |   [value-id value-expr pretty-expr]           value-expr   =   (U boolean? symbol? integer?)           pretty-expr   =   string?           keyword-arg   =   #:plural id

Binds enum-id to an identifier macro that can be used:

• in argument position to refer to an enum struct;

• in procedure call position to retrieve a value from the enumeration.

Examples:

> (define-enum options       ([a 'option1 "first option"]        [b "second option"]        c))

> (options a)

option1

> (options b)

b

> (options c)

c

> (map (lambda (val)            (enum-prettify options val))          (list (options a) (options b) (options c)))

("first option" "second option" "c")

(enum-list enum value ...)

Expands to a list of values from enum.

Examples:

> (define-enum vehicles (car boat plane))

> (enum-list vehicles car boat)

(car boat)

(enum-case enum value clause ...)

clause   =   [(value ...) expr ...]     |   [else expr ...]

Like case but each value must be a value from enum. If an else expression is not provided, the values must cover the complete enumeration.

Examples:

> (define-enum vehicles (car boat plane))

> (define (flies? vehicle)       (enum-case vehicles vehicle         [(plane) #t]         [(car boat) #f]))

> (flies? 'car)

#f

> (flies? 'plane)

#t