defcenum

defcenum

Syntax

Macro: defcenum name-and-options &body enum-list

enum-list ::= [docstring] { keyword | (keyword value) }*
name-and-options ::= name | (name &optional (base-type :int) &key allow-undeclared-values)

Arguments and Values

name

The name of the new enum type.

docstring

A documentation string, ignored.

base-type

A symbol denoting a foreign type.

allow-undeclared-values

Whether to pass through integer values that were not explicitly declared in the enum when translating from foreign memory.

keyword

A keyword symbol.

value

An index value for a keyword.

Description

The defcenum macro is used to define foreign types that map keyword symbols to integer values, similar to the C enum type.

If value is omitted its value will either be 0, if it’s the first entry, or it it will continue the progression from the last specified value.

Keywords will be automatically converted to values and vice-versa when being passed as arguments to or returned from foreign functions, respectively. The same applies to any other situations where an object of an enum type is expected.

If a value should be translated to lisp that is not declared in the enum, an error will be signalled. You can elide this error and instead make it pass the original enum value by specifying allow-undeclared-values. This can be useful for very large enumerations of which we only care about a subset of values, or for enumerations that should allow for client or vendor extensions that we cannot know about.

Types defined with defcenum canonicalize to base-type which is :int by default.

Examples

  (defcenum boolean
    :no
    :yes)
   
  CFFI> (foreign-enum-value 'boolean :no)
  ⇒ 0

  (defcenum numbers
    (:one 1)
    :two
    (:four 4))
   
  CFFI> (foreign-enum-keyword 'numbers 2)
  ⇒ :TWO

See Also

foreign-enum-value
foreign-enum-keyword