;;
;; util-proc.scm
;;
;; Auxiliary procedure functions.
;;
;; ISC License
;;
;; Copyright 2023 Brmlab, z.s.
;; Dominik Pantůček <dominik.pantucek@trustica.cz>
;;
;; Permission to use, copy, modify, and/or distribute this software
;; for any purpose with or without fee is hereby granted, provided
;; that the above copyright notice and this permission notice appear
;; in all copies.
;; 
;; THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
;; WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
;; WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
;; AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
;; CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
;; OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
;; NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
;; CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
;;

(declare (unit util-proc))

(import duck)

(module*
 util-proc
 #:doc ("This module provides a few simple procedures for querying properties
of other procedures.")
 (
  improper-list-info

  procedure-arity=?
  procedure-arity>=?
  procedure-arity>?

  procedure-num-args
  procedure-arg-names
  )

 (import scheme
	 (chicken base))
 
 (define/doc (improper-list-info lst)
   ("Returns two values: the proper part of the list length and #t if
there is an improper list end")
   (let loop ((lst lst)
	      (len 0))
     (if (symbol? lst)
	 (values len #t)
	 (if (null? lst)
	     (values len #f)
	     (loop (cdr lst)
		   (add1 len))))))

 ;; Returns two values: the number of mandatory arguments and
 ;; information whether the procedure accepts optional arguments
 (define (procedure-arity-info proc)
   (let-values (((len rest?) (improper-list-info (procedure-information proc))))
     (values (sub1 len) rest?)))

 (define/doc ((procedure-arity=? n) proc)
   ("* ```n``` - integer representing the number of arguments
* ```proc``` - procedure to query

Returns true if the procedure ```proc``` accepts exactly ```n```
arguments.")
   (let-values (((args rest?) (procedure-arity-info proc)))
     (and (not rest?)
	  (= args n))))

 (define/doc ((procedure-arity>=? n) proc)
   ("* ```n``` - integer representing the number of arguments
* ```proc``` - procedure to query

Returns true if the procedure ```proc``` accepts at least ```n```
arguments.")
   (let-values (((args rest?) (procedure-arity-info proc)))
     (or rest?
	 (>= args n))))

 (define/doc ((procedure-arity>? n) proc)
   ("* ```n``` - integer representing the number of arguments
* ```proc``` - procedure to query

Returns true if the procedure ```proc``` accepts more than ```n```
arguments.")
   (let-values (((args rest?) (procedure-arity-info proc)))
     (or rest?
	 (> args n))))

 (define/doc (procedure-num-args proc)
   ("* ```proc``` - procedure to check

Returns the number of mandatory arguments.")
   (let-values (((args rest?) (procedure-arity-info proc)))
     args))

 (define/doc (procedure-arg-names proc)
   ("* ```proc``` - procedure to check

Returns the (possibly improper) list of arguments the procedure
```proc``` accepts. If it accepts arbitrary number of arguments, it is
signalled by simple symbol instead of pair at the last position. If it
accepts an exact number of arguments, it returns a proper list.")
   (cdr (procedure-information proc)))

 )