SRFI-51: Handling rest list

The procedure and macros proposed in this SRFI make a strong combination with RECEIVE (SRFI 8) and LET-VALUES (SRFI 11).

Abstract

This SRFI introduces the REST-VALUES procedure which has three modes of operation:

1. it processes a rest list after checking its elements with default values or predicate procedures,

2. it processes a rest list with default values without checking its elements,

3. it processes a default list whose elements are lists or pairs, after checking their elements that are default values or predicate procedures with the elements of a rest list,

and eight macros which additionally check the rest arguments that are returned by REST-VALUES.

Rationale

When defining a procedure with a variable number of arguments, REST-VALUES with or without the checking macros reduces the clutter of various conditionals and error conditions.

Specification

REST-VALUES

[procedure] (REST-VALUES [<caller>] <rest-list> [<args-number-limit> <default> ...])
[parameter] <caller>

<caller> is any scheme expression.

[parameter] <args-number-limit>

<args-number-limit> should be an integer, +, -, or a boolean.

1. When the <args-number-limit> is + or a positive integer, each <default> should be a list that contains default value(s), or a pair whose car is a default value and cdr is a predicate procedure.
2. When the <args-number-limit> is - or a negative integer, each <default> is any scheme expression.
3. When the <args-number-limit> is a boolean, each <default> is the same as 1.
1. (first mode of operation)

REST-VALUES checks whether each element of the <rest-list> is a member of the corresponding <default> list, or satisfies the predicate procedure of the corresponding <default> pair, and then returns the checked element(s). If the element doesn't pass, REST-VALUES signals an error. When there are no more elements in the <rest-list>, then REST-VALUES additionally returns the car values of the remaining <default>s. On the other hand, when the number of elements of the <rest-list> are more than the number of the <default>s, the supernumerary elements are additionally returned if the <args-number-limit> is +, or its value is not less than the number of elements of the <rest-list>.

2. (second mode of operation)

This is the same as the first except that REST-VALUES does not check each element of the <rest-list>, and it uses - instead of +, and an absolute value instead of a simple value as the value of <args-number-limit>.

3. (third mode of operation)

REST-VALUES checks whether any element of the <default> list is a member of the <rest-list>, or any element of the <rest-list> satisfies the predicate procedure of the <default> pair, and then returns the checked element. If the <default> doesn't pass, REST-VALUES returns the car value of the <default>. When any elements of the <rest-list> are remained after the above processing, REST-VALUES either signals an error if the <args-number-limit> is #t, or returns the remaining elements of the <rest-list> if the <args-number-limit> is #f.

ARG and END procedures

[procedure] (ARG-AND [<caller>] <variable> <expr> ...)
[procedure] (ARG-ANDS [COMMON <caller>] ([<caller>] <variable> <expr> ...) ...)
[procedure] (ERR-AND <caller> <expression> ...)
[procedure] (ERR-ANDS (<caller> <expression> ...) ...)
[procedure] (ARG-OR [<caller>] <variable> <expr> ...)
[procedure] (ARG-ORS [COMMON <caller>] ([<caller>] <variable> <expr> ...) ...)
[procedure] (ERR-OR <caller> <expression> ...)
[procedure] (ERR-ORS (<caller> <expression> ...) ...)

Each <variable> should be an argument of a procedure.
The <caller>, <expr>, and <expression> are any scheme expressions, but the <expr> should contain the corresponding <variable>.

ARG-AND, ARG-ANDS, ERR-AND, and ERR-ANDS are the same as AND except that these signal an error in case AND returns a false value.

ARG-OR, ARG-ORS, ERR-OR, and ERR-ORS are the same as OR except that these signal an error in case OR returns a true value.

Examples

caller    => <procedure caller>
rest-list => (x 1)
(rest-values rest-list)	                 => x 1
(rest-values rest-list 2)	         => x 1
(rest-values caller rest-list)           => x 1
(rest-values caller rest-list -3)        => x 1
(rest-values rest-list -2 'y 3 1)
 => error too many defaults (y 3 1) default-list (<= (length default-list) 2)
(rest-values 'caller rest-list 1 '(x y z))
 => error too many arguments (x 1) rest-list (<= (length rest-list) 1) caller
(rest-values caller rest-list 2 (list 'x 'y 'z) (cons "str" string?))
 => error incorrect argument 1 arg (<procedure string?> arg) <procedure caller>
(rest-values rest-list 2 '(y z) `(100 . ,number?))
 => error unmatched argument x arg (member arg (y z))
(rest-values "caller: bad argument" rest-list 2 '(y z) `(100 . ,number?))
 => error caller: bad argument x arg (member arg (y z))
(rest-values 'caller rest-list (list 'x 'y) (cons 1 number?))
 => error bad optional argument (x y) option
    (or (boolean? option) (integer? option) (memq option (list + -))) caller
(rest-values rest-list - 'y 100 "str")
 => x 1 "str"
(rest-values rest-list + `(x y z) `(100 . ,number?) `("str" . ,string?))
 => x 1 "str"
(rest-values rest-list #t `(x y z) `(100 . ,number?) `("str" . ,string?))
 => x 1 "str"
(rest-values rest-list #t `(100 . ,number?) `("str" . ,string?) `(x y z))
 => 1 "str" x
(rest-values rest-list #t `(100 . ,number?) `("str" . ,string?) `(y z))
 => error bad argument (x) rest-list (null? rest-list)
(rest-values rest-list #f `(100 . ,number?) `("str" . ,string?) `(y z))
 => 1 "str" y x

caller => <procedure caller>
str    => "string"
num    => 2
(arg-and num (number? num) (< num 2))
       => error incorrect argument 2 num (< num 2)
(arg-and caller num (number? num) (< num 2))
       => error incorrect argument 2 num (< num 2) <procedure caller>
(arg-and 'caller num (number? num) (< num 2))
       => error incorrect argument 2 num (< num 2) caller
(arg-and "caller: bad argument" num (number? num) (< num 2))
       => error caller: bad argument 2 num (< num 2)
(arg-ands (str (string? str) (< (string-length str) 7))
	  ("caller: bad argument" num (number? num) (< num 2)))
       => error caller: bad argument 2 num (< num 2)
(arg-ands ("caller: bad argument" str (string? str) (< (string-length str) 7))
	  (num (number? num) (< num 2)))
       => error incorrect argument 2 num (< num 2)
(arg-ands common 'caller
	  (str (string? str) (< (string-length str) 7))
	  (num (number? num) (< num 2)))
       => error incorrect argument 2 num (< num 2) caller
(arg-ands common "caller: bad argument"
	  (str (string? str) (< (string-length str) 7))
	  ("caller: incorrect argument" num (number? num) (< num 2)))
       => error caller: incorrect argument 2 num (< num 2)
(err-and 'caller
	 (string? str) (< (string-length str) 7) (number? num) (< num 2))
       => error false expression (< num 2) caller
(err-ands (caller (string? str) (< (string-length str) 7))
	  ("num failed test in caller" (number? num) (< num 2)))
       => error num failed test in caller (< num 2)

(define (read-line . p-d)
  ;; p-d should be (<input-port> <symbol>).
  (receive (p d) (rest-values p-d 2
			      (cons (current-input-port) input-port?)
			      (list 'trim 'concat 'split...))
    ...))
(define (read-line . p-d)
  (receive (p d) (rest-values p-d -2 (current-input-port) 'trim)
    (arg-ands (p (input-port? p))
	      (d (memq d '(trim concat split...))))
    ...))
(define (read-line . p-d)
  ;; p-d can be (<input-port> <symbol>) or (<symbol> <input-port>).
  (receive (p d) (rest-values p-d #t
			      (cons (current-input-port) input-port?)
			      (list 'trim 'concat 'split...))
    ...))

(define (delete x ls . predicate)
  (let ((pred (rest-values 'delete predicate 1 (list equal? eqv? eq?))))
    ...))
(define (delete x ls . predicate)
  (let ((pred (rest-values 'delete predicate -1 equal?)))
    (err-and 'delete (list? ls) (memq pred (list equal? eqv? eq?)))
    ...))

(define (substring str . start-end)
  (let ((str-len (arg-and substring str (string? str) (string-length str))))
    (receive (start end) (rest-values substring start-end -2 0 str-len)
      (arg-ands common substring
		(start (integer? start) (<= 0 start str-len))
		(end (integer? end) (<= start end str-len)))
      ...)))

(define (procedure-with-sequential-binding-arguments . a-b-c)
  (receive (a b c) (rest-values a-b-c -3 10 #f #f)
    (let* ((b (or b (+ a 10)))
	   (c (or c (+ a b))))
      ...)))

Author

Joo ChurlSoo
Ported to Chicken Scheme 5 by Sergey Goldgaber

Repository

https://github.com/diamond-lizard/srfi-51

Version history

0.2 - Fixed missing exports

0.1 - Ported to Chicken Scheme 5

Copyright

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Scheme Request For Implementation process or editors, except as needed for the purpose of developing SRFIs in which case the procedures for copyrights defined in the SRFI process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the authors or their successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.