define-enumeration(7scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💜 define-enumeration(7scm)

okay so this is a page from the Scheme Programmer's Manual, and we're about to make enums make sense. stay with me bestie, it's actually so clean ✨

🌸 NAME

define-enumeration — define an enumeration type. that's it. that's the whole vibe.

📚 LIBRARY

both of these give you the goods:

(import (rnrs))                     ;R6RS
(import (rnrs enums))               ;R6RS

🎀 SYNOPSIS

(define-enumeration type-name
  (symbol ...)
  constructor-syntax)

✨ DESCRIPTION

okay so define-enumeration is the form that defines an enumeration type, and the way it's giving is generous: it hands you two macros, one for building members and one for building sets of members. two for one, we love a bundle 💅

define-enumeration is a definition, so it can show up literally anywhere any other definition can show up. no special seating required.

so the arguments:

  • type-name — an identifier that gets bound as a syntactic keyword (peep below 👀).
  • the symbol arguments — these are the symbols that make up the universe of the enumeration. the whole squad. nobody outside the universe gets in.
  • constructor-syntax — an identifier bound to a macro (also below 👀).

🦋 Type name macro

(type-name symbol) is the same energy as (quote symbol), except — and this is the important part — it verifies at macro-expansion time that the name of symbol is actually in the universe associated with type-name. if it's not? syntax violation, bestie. it does not let it slide. 😤

🧚 Constructor macro

(constructor-syntax symbol ...) checks at macro-expansion time whether every single symbol is in the universe associated with type-name. if one or more of them isn't, it's a syntax violation. periodt.

duplicates are allowed though — no cap, duplicate away 🫶.

otherwise, (constructor-syntax symbol ...) is equivalent to:

((enum-set-constructor (constructor-syntax))  '(symbol ...))

and one lil detail that matters: in the (type-name symbol) and (constructor-syntax symbol ...) forms, only the names of the symbols are significant. that's the whole check.

🍓 RETURN VALUES

nope! this form can't appear in a context where it returns a value. it's a definition, not a little value-generator. know the difference 💀

🔥 EXAMPLES

here's the iconic one:

(define-enumeration color
  (black white purple maroon)
  color-set)
(color black)                    =>  black
(color purpel)                   =>  &syntax exception

(yes purpel — that's the point, it's not in the universe, so it gets got 🙈)

(enum-set->list (color-set))     =>  ()
(enum-set->list
 (color-set maroon white))       =>  (white maroon)

see how the empty set is just () and the set comes back sorted-ish by universe order? slay.

👑 APPLICATION USAGE

enumerations are for code that would perhaps traditionally represent flags using bits in integers, or lists of symbols. you know the type. we're upgrading. 💅

🌈 RATIONALE

real talk: enumerations were added to support flags in the R6RS I/O system. that's the origin story. main character energy from day one.

💀 ERRORS

this syntax can raise exceptions with the following condition types:

  • &syntax (R6RS) — invalid arguments was passed. (their words, not mine, but you get it — bad args, syntax exception, done.)

🫶 SEE ALSO

⭐ STANDARDS

  • R6RS
  • SRFI-209

🌸 HISTORY

first appeared in R6RS. a classic.

💜 AUTHORS

this page is part of the scheme-manpages project. it includes materials from the RnRS documents. more info lives at https://github.com/schemedoc/manpages/.

and that's the whole page, bestie 🎀 this drop is from the Scheme Programmer's Manual, define-enumeration(7scm), dated 2022-03-26 — go forth and enumerate, iykyk 🌟

📦 where this page comes from