ffi: new feature: enums.

* ffi.c (enum_s): New symbol variable.
(struct txr_ffi_type): New member, sym_num, num_sym.
(ffi_enum_type_mark): New static function.
(ffi_type_enum_ops): New static structure.
(ffi_enum_put, ffi_enum_get, ffi_enum_rput, ffi_enum_rget):
New static functions.
(make_ffi_type_enum): New static function.
(ffi_type_compile): Extend with enum syntax.
(ffi_init): Initialize enum_s with new interned symbol.

* ffi.c (enum_s): Declared.

* txr.1: Documented.

1 files changed, 60 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index e0a3ed1f..8a5d815e 100644
--- a/txr.1
+++ b/txr.1
@@ -53941,6 +53941,66 @@ zero bytes into
 
 .PP
 The following following parametrized types are available:
+.meIP (enum < name >> {( sym << value ) | << sym }*)
+The type
+.code enum
+specifies an enumerated type, which establishes a correspondence between
+a set of Lisp symbols and foreign integer values of type
+.codn int .
+
+The
+.meta name
+argument must either be
+.code nil
+or a symbol for which the
+.code bindable
+function returns true. It gives the tag name of the enumerated
+type. The remaining arguments specify the enumeration constants.
+
+In the enumeration constant syntax, each occurrence of
+.meta sym
+They must be either a keyword symbol, or a symbols for which the
+.code bindable
+function returns true. The symbols may not repeat.
+
+If a
+.meta sym
+is given, it is associated with an integer value which is one greater
+than the integer value associated with the previous symbol.
+If there is no previous symbol, then the value is zero.
+
+If
+.meti >> ( sym << value )
+is given, then
+.code sym
+is given the specified value. The
+.meta value
+argument may be either an integer token, or a symbol. If it is an integer
+token, then the value must be in range of the FFI
+.code int
+type.  If a symbol is given, it must be be one of the symbols already defined
+in the same enumerated type. The new symbol is given the same value as that
+symbol.
+
+The FFI
+.code enum
+type converts two kinds of Lisp values to the foreign type
+.codn int :
+symbols which are in the set defined by the type, and integer values
+which are in the range which that foreign type can represent.
+Out-of-range integer values, symbols not defined in the enumeration, and
+objects not of symbol or integer type all trigger an exception.
+
+In the reverse direction, the
+.code enum
+type extracts from the foreign representation values of FFI type
+.codn int ,
+and converts them, if possible, to symbols. If an integer value occurs
+which is not assigned to any enumeration symbol, then the conversion produces
+that integer value itself rather than a symbol. If an integer value occurs
+which is assigned to multiple enumeration symbols, it is not specified which
+of those symbols is produced.
+
 .meIP (struct < name >> {( slot << type )}*)
 The FFI
 .code struct