miscmacros

  1. miscmacros
    1. Description
    2. Author
    3. Repository
    4. Requirements
    5. Documentation
    6. Changelog
    7. License

Description

Various useful little macros.

Note: since version 2.95, this extension does not support doto anymore. It is provided instead by Moritz Heidkamp's clojurian egg, among other other interesting Clojure macros.

Author

felix winkelmann

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/miscmacros

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Requirements

None

Documentation

[syntax] (let/cc K BODY ...)

Executes BODY ... with K bound to the current-continuation.

[syntax] (until TEST BODY ...)

Executes BODY ... repeatedly while the expression TEST returns #f.

[syntax] (repeat TIMES BODY ...)

Executes BODY ... TIMES times.

[syntax] (repeat* TIMES BODY ...)

Executes BODY ... TIMES times, with the variable it bound to the count-down value.

[syntax] (dotimes (VAR TIMES [FINAL]) BODY ...)

Executes BODY ... TIMES times, with the variable VAR bound to the count-up value.

Returns the result of the FINAL expression or (void) when no FINAL expression.

[syntax] (while TEST BODY ...)

Executes BODY ... repeatedly until the expression TEST returns #f.

[syntax] (while* TEST BODY ...)

Executes BODY ... repeatedly, with the result of TEST bound to the variable it, until the expression TEST returns #f.

[syntax] (select EXP ((KEY ...) EXP1 ...) ... [(else EXPn ...)])

This is similar to case, but the keys are evaluated.

[syntax] (if* X Y [Z])

The anaphoric if: if the expression X evaluates to a true value, the expression Y will be executed with the result of X bound to the variable it. If X is false, then Z (if supplied) will be evaluated:

 (if* (> 3 1) it)                      ==> #t
 (if* (memq 'a '(b a c)) (cdr it) 99)  ==> (c)
 (if* #f it 1)                         ==> 1
 (if* #f #f)                           ==> #<unspecified>
[syntax] (push! X LOC)

equivalent to

 (set! LOC (cons X LOC))

Note that LOC may be any settable location.

[syntax] (pop! LOC)

Returns the first element from the list stored in the location LOC and sets LOC to the cdr of the previous value.

[syntax] (inc! LOC [AMOUNT])

Equivalent to (set! LOC (+ LOC AMOUNT)). AMOUNT defaults to 1. Returns the new value.

[syntax] (dec! LOC [AMOUNT])

Equivalent to (set! LOC (- LOC AMOUNT)). AMOUNT defaults to 1. Returns the new value.

[syntax] (ignore-errors BODY ...)

Evaluates the expressions in BODY .... If any exceptions should be raised during execution of the body, then the exceptions will be caught, and ignore-errors returns #f.

[syntax] (begin0 BODY ...)

Evaluates BODY ... just like begin, but instead of returning the last value(s), begin0 returns the result (or the results) of the first expression in BODY ....

[syntax] (define-enum ->INT ->SYM ID ...)

Defines an enumeration. The variables ID, ... are bound to the exact integers 0, 1, ... with define-constant. ID may also take the form (ID N), in which case the counter will be set to the exact integer N for that variable, and continue upward normally from there. A procedure named ->INT will be defined that takes a symbols and returns the respective integer. A procedure ->SYM will also be defined that takes an integer and returns the respective symbol (from the set of IDs). If a symbol doesn't map to an integer (or vice versa), #f is returned.

[syntax] (define-optionals ((VAR1 DEFAULT1) ...) ARGUMENTS)

Defines the globals VAR1 ... with the values taken from the list ARGUMENTS, or with DEFAULT1 ..., if the list is shorter.

[syntax] (define-parameter VAR [VALUE [GUARD]])

Equivalent to

 (define VAR (make-parameter VALUE [GUARD]))

VALUE defaults to (void).

[syntax] (ignore-values EXP)

Evaluates EXP ignoring any return values. Returns an unspecified value.

[syntax] (modify-location LOC PROC)

Expands into a call to PROC with two arguments: a zero-argument procedure for retrieving the value from the settable location LOC and a one argument procedure for setting the value of LOC. Care is taken to evaluate any subforms in LOC only once.

modify-location is intended to create modification macros for generalized locations (as in SRFI-17.

 (define-syntax-rule (increment! loc)
   (modify-location
     loc
     (lambda (ref upd) (upd (add1 (ref)))) ) )
 
 (define x (vector 123))
 (increment! (vector-ref x (print 0)))   ; sets x to #(124) and prints "0" only once
[syntax] (modify! LOC PROC)

Modifies the contents of location LOC by applying the procedure PROC to it's contents and setting LOCs to the result. LOC may be any settable location.

 (define-macro (increment! loc)
   `(modify! ,loc add1) )
[syntax] (exchange! LOC1 LOC2)

Exchanges the contents of the given locations. LOC1 and LOC2 may be any settable locations.

[syntax] (define-syntax-rule (NAME ARGUMENT ...) TEMPLATE)

Shorthand for

 (define-syntax NAME
   (syntax-rules ()
     ((_ ARGUMENT ...) TEMPLATE)))
[syntax] (ecase EXP ((LITERAL ...) BODY ...) ...)

Similar to case, but signals an error if no clause matches.

[syntax] (ensure PREDICATE EXP [ARGUMENTS ...])

Evaluates the expression EXP and applies the one-argument procedure PREDICATE to the result. If the predicate returns #f an error is signaled, otherwise the result of EXP is returned. If compiled in unsafe mode (either by specifying the -unsafe compiler option or by declaring (unsafe)), then this expression expands to an unspecified value. If specified, the optional ARGUMENTS are used as arguments to the invocation of the error-signalling code, as in (error ARGUMENTS ...). If no ARGUMENTS are given, a generic error message is displayed with the offending value and PREDICATE expression.

[syntax] (eval-when (SITUATION ...) EXP ...)

Controls evaluation/compilation of subforms. SITUATION should be one of the symbols eval, compile or load. When encountered in the evaluator, and the situation specifier eval is not given, then this form is not evaluated and an unspecified value is returned. When encountered while compiling code, and the situation specifier compile is given, then this form is evaluated at compile-time. When encountered while compiling code, and the situation specifier load is not given, then this form is ignored and an expression resulting into an unspecified value is compiled instead.

The following table should make this clearer:

In compiled code In interpreted code
eval ignore evaluate
compile evaluate at compile time ignore
load compile as normal ignore

Changelog

License

 Copyright (c) 2006-2018, The CHICKEN Team
 Copyright (c) 2004-2005, Felix L. Winkelmann
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
 conditions are met:
 
   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
     disclaimer.
   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
     disclaimer in the documentation and/or other materials provided with the distribution.
   Neither the name of the author nor the names of its contributors may be used to endorse or promote
     products derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.