From cd8cf4f8fd827e428c53f2e6d7fcce5cd9727e7f Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Wed, 1 Jun 2016 07:05:35 -0700
Subject: Methods for turning objects into sequences.

Struct objects can now define methods car, cdr and nullify.
With these, they can participate in operations on sequences.

* eval.h (car_s, cdr_s): Declared.

* lib.c (nullify_s): New symbol variable.
(car, cdr): Implement for struct objects via, respectively,
their car and cdr methods.
(tolist): Handle objects by mapping through identity.
(nullify): Implement for objects optionally: if an object
is a struct with a nullify method, use it, otherwise go
through default case of just returning the object.
(empty): Implement for objects that have nullify method.
(obj_init): Initialize nullify_s.

* struct.c (maybe_slot): New function.

* struct.h (maybe_slot): Declared.

* txr.1: Documented car, cdr and nullify method
convention.
---
 txr.1 | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

(limited to 'txr.1')

diff --git a/txr.1 b/txr.1
index e79ec1d7..6ba20ac0 100644
--- a/txr.1
+++ b/txr.1
@@ -10300,6 +10300,13 @@ are made to work with strings and vectors:
   (car #(1 2 3)) -> 1
 .cble
 
+Moreover, structure types which define the methods
+.codn car ,
+.code cdr
+and
+.code nullify
+can also be treated in the same way.
+
 The
 .code ldiff
 function is also extended in a special way. When the right parameter
@@ -19288,6 +19295,48 @@ is defined for a structure type, then it is used for pretty-printing instances
 of that type. The method takes one argument (in addition to the object), which
 specifies the output stream.
 
+.NP* Sequence Operations on Structures
+
+Structures may be treated as sequences if they define methods named
+by the symbols
+.codn car ,
+.codn cdr ,
+and
+.codn nullify .
+
+If a structure supports these methods, then these methods are used
+by the functions
+.codn car ,
+.codn cdr ,
+.codn nullify ,
+.code empty
+and various other sequence manipulating functions derived from them, when those
+functions are applied to that object.
+
+An object which implements these three methods can be considered to denote
+an abstract sequence. The object's
+.code car
+method should return the first value in that abstract sequence, or else
+.code nil
+if that sequence is empty.
+
+The object's
+.code cdr
+method should return an object denoting the remainder of the sequence,
+or else
+.code nil
+if the sequence is empty or contains only one value.  This returned object can
+be of any type: it may be of the same structure type as that object, a
+different structure type, a list, or whatever else.  If a non-sequence object
+is returned.
+
+The
+.code nullify
+method should return
+.code nil
+if the object is considered to denote an empty sequence. Otherwise it
+should return that object itself.
+
 .coNP Macro @ defstruct
 .synb
 .mets (defstruct >> { name | >> ( name << arg *)} < super
-- 
cgit v1.2.3