Changeset 37322 in project


Ignore:
Timestamp:
03/01/19 04:39:23 (3 months ago)
Author:
jacius
Message:

Updated ck-macros docs for version 0.2.0.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/ck-macros

    r37267 r37322  
    77by Oleg Kiselyov.
    88This egg provides the core {{ck}} macro,
    9 plus many useful (and some not-so-useful) predefined CK-macros.
     9many useful (and some not-so-useful) predefined CK-macros,
     10the {{ck-wrapper}} procedure, and many wrappers of R5RS procedures.
    1011
    1112If you create a useful or interesting general-purpose CK-macro,
     
    2627=== Version History
    2728
     29; 0.2.0 (2019-02-28) : Ported to CHICKEN 5. Added {{ck-wrapper}} and many R5RS wrappers. Added some new portable CK-macros. Breaking changes to {{c-apply}}. Renamed some CK-macros.
    2830; 0.1.1 (2016-02-07) : Fixed {{c-append}} and {{c-vector-append}} failing when given one argument.
    2931; 0.1.0 (2016-02-06) : Initial release. Includes version 1.1 (April 2011) of the core {{ck}} macro. Includes many CK-macros.
     
    5456allowing you to portably achieve the same effect at macro-expansion time.
    5557You can even implement "higher-ordered macros" which take a macro as an argument.
    56 See {{c-map}} and {{c-fold}} for examples of higher-ordered macros.
    57 
    58 CK-macros are not as flexibile or powerful as
    59 CHICKEN's [[/manual/Macros|explicit and implicit renaming macros]],
     58See {{c-map1}} and {{c-compose}} for examples of higher-ordered macros.
     59
     60CK-macros are not as flexibile, powerful, or efficient as
     61CHICKEN's [[/man/5/Module (chicken syntax)|explicit and implicit renaming macros]],
    6062but CK-macros are much more portable.
    61 The [[#ck|core {{ck}} macro]] and all the macros in the [[#portable-ck-macros|Portable CK-Macros]] section
    62 are implemented using only standard R5RS features,
    63 such as {{syntax-rules}} and {{let-syntax}}.
    64 This means they will work on any implementation of R5RS or later.
     63
     64* The [[#ck|core {{ck}} macro]] and everything in the
     65  [[#portable-ck-macros|Portable CK-Macros]] section
     66  are implemented using only standard R5RS features, such as {{syntax-rules}}.
     67  This means they will work on any implementation of R5RS or later.
     68
     69* The [[#ck-wrapper|{{ck-wrapper}} procedure]] and everything in the
     70  [[#non-portable-r5rs-wrappers|Non-portable R5RS Wrappers]] section
     71  are implemented using
     72  [[/man/5/Module (chicken syntax)#explicit-renaming-macros|{{er-macro-transformer}}]],
     73  which is not standard R5RS but is available in many Scheme implementations.
    6574
    6675
    6776=== How to write CK-macros
    6877
    69 Here is a basic template for CK-macros:
     78(Note: If you don't care about strict R5RS portability,
     79the easiest way to create a CK-macro is with [[#ck-wrapper|{{ck-wrapper}}]].)
     80
     81Here is a basic template for portable CK-macros:
    7082
    7183<enscript highlight="scheme">
     
    145157
    146158See [[http://okmij.org/ftp/Scheme/macros.html#ck-macros|the original article]]
    147 or [[https://gitlab.com/jcroisant/ck-macros/blob/master/ck-portable.scm|the source code]]
     159or [[https://gitlab.com/jcroisant/ck-macros/blob/master/lib/portable.scm|the source code]]
    148160for many examples of CK-macros.
    149161
     
    156168
    157169Some non-CK macros can be used in a way that expands into a user-provided expression.
    158 It is therefore possible for these non-CK macros to be used as arguments CK-macros,
     170It is therefore possible for these non-CK macros to be used as arguments to CK-macros,
    159171as long as they eventually expand into a call to the core {{ck}} macro.
    160172
    161173It is possible to write a non-CK macro which invokes a CK-macro via the core {{ck}} macro.
    162174For example, if you are writing a macro for other people to use,
    163 you can create a convenience wrapper macro, like so:
    164 
    165 <enscript highlight="scheme">
    166 ;;; Convenience wrapper around c-foo.
     175you can create a convenience macro, like so:
     176
     177<enscript highlight="scheme">
    167178(define-syntax foo
    168179  (syntax-rules ()
     
    171182</enscript>
    172183
    173 Also, it is possible for a CK-macro to expand into a call to a non-CK macro as its final result,
    174 or as part of the body of its final result.
     184Also, it is possible for a CK-macro to expand into a call to a non-CK macro
     185as its final result, or as part of the body of its final result.
    175186For example:
    176187
     
    179190;;; Expands to the expression (when (< 1 2) (print "Yay!")).
    180191</enscript>
     192
     193
     194=== Troubleshooting
     195
     196CK-macros push the Scheme macro system in unusual ways,
     197so unfortunately they are not very user-friendly.
     198
     199One common error you may see is, "no rule matches form".
     200This often indicates that you forgot to quote a value somewhere.
     201As explained in the section [[#how-to-write-ck-macros|How to write CK-macros]],
     202all values must be quoted,
     203even values which normally do not need to be quoted in Scheme code,
     204such as strings, numbers, and booleans.
     205
     206For example, the code {{(ck () (c-not #t))}} will result in an error like this:
     207
     208 Syntax error: no rule matches form
     209 
     210         (ck38782 (((c-not))) #t)
     211
     212The solution is to quote the {{#t}}, like this: {{(ck () (c-not '#t))}}
     213
     214
     215=== Known issues and limitations
     216
     217==== Slow compilation
     218
     219CK-macros are pretty slow to compile,
     220because the computation is done at compile time,
     221using ''very'' deeply recursive macro expansions.
     222
     223Non-portable wrappers created with [[#ck-wrapper|{{ck-wrapper}}]]
     224are probably somewhat faster than the portable CK-macros created with {{syntax-rules}}.
     225But this library prioritizes portability over efficiency,
     226so CK-macros are only implemented as wrappers if it is ''impossible''
     227to implement them using {{syntax-rules}}.
     228
     229You could likely improve compilation speed in your own code by
     230redefining various CK-macros using {{ck-wrapper}}.
     231
     232
     233==== Pitfalls of c-sym-eq?
     234
     235{{c-sym-eq?}} has some strange and unexpected behaviors
     236because of the way it uses {{let-syntax}}.
     237
     238* The behavior of {{c-sym-eq?}} is undefined and non-portable
     239  when comparing anything except symbols.
     240
     241* You should not use {{c-sym-eq?}} in any code that expands
     242  into a definition (of a variable, procedure, etc.),
     243  because that definition will not be visible from outside.
     244  This is because definitions that occur within the body of {{let-syntax}}
     245  are internal definitions, not global definitions.
     246
     247For example, this code will not work as expected:
     248
     249 (ck () (c-list 'define 'x (c-sym-eq? 'a 'a)))
     250
     251You might expect it to expand to {{(define x #t)}},
     252defining a global variable {{x}} with the value {{#t}}.
     253But even though {{c-sym-eq?}} seems to be used "inside" the definition,
     254the core {{ck}} macro turns things "inside out"
     255to eagerly expand macro arguments first.
     256So, the definition will actually appear inside of a {{let-syntax}},
     257and {{x}} will not be visible from outside.
     258
     259These pitfalls also affect other macros that use {{c-sym-eq?}} directly or indirectly:
     260
     261* {{c-sym-equal?}}
     262* {{c-member}} with the default comparison operator
     263* {{c-assoc}} with the default comparison operator
     264* {{c-alist-delete}} with the default comparison operator
     265
     266It is believed to be impossible to fix {{c-sym-eq?}} in a portable way,
     267so it is recommended that you avoid using it or {{c-sym-equal?}} if possible.
     268If you don't care about strict R5RS portability,
     269you should use the non-portable wrappers {{c-eq?}} and {{c-equal?}} instead.
    181270
    182271
     
    192281; s : The stack, used internally by this macro. When initially invoking this macro, {{s}} should be the empty list, e.g. {{(ck () (c-cons '+ '(1 2)))}}.
    193282; 'v : A quoted value. Can be a quoted list, symbol, or other literal value. The quote is necessary, even for literal values like strings, numbers, and booleans.
    194 ; (op ...) : A CK-macro call '''without the s argument''', such as {{(c-cons '+ '(1 2))}}. Nested calls are allowed, such as {{(c-cons '+ (c-list '1 '2))}}.
     283; (op ...) : A CK-macro call '''without the s argument''', such as {{(c-cons '+ '(1 2))}}.
     284Nested calls are allowed, such as {{(c-cons '+ (c-list '1 '2))}}.
     285
     286
     287=== ck-wrapper
     288
     289<procedure>(ck-wrapper proc)  →  macro transformer</procedure>
     290
     291Wrap a procedure in a CK-macro, returning a macro transformer
     292that can be used with {{define-syntax}} or {{let-syntax}}.
     293
     294{{ck-wrapper}} requires '''version 0.2.0 or later''' of the ck-macros egg.
     295It is considered '''non-portable''' because it depends on
     296[[/man/5/Module (chicken syntax)#explicit-renaming-macros|{{er-macro-transformer}}]],
     297which is not defined in standard R5RS.
     298However, it should work on any Scheme which defines
     299{{er-macro-transformer}} in the usual way.
     300
     301You can wrap any other expression that evaluates to a procedure,
     302such as a procedure name, a lambda form, a "let over lambda" expression, etc.
     303The expression will be evaluated once,
     304when the call to {{ck-wrapper}} is evaluated.
     305Therefore, the procedure you are wrapping must be available
     306in the syntax environment at macro expansion time.
     307(In other words, you should use
     308[[/man/5/Module (chicken syntax)#define-for-syntax|{{define-for-syntax}}]],
     309[[/man/5/Modules#import-for-syntax|{{import-for-syntax}}]], etc.)
     310
     311Examples:
     312
     313<enscript highlight="scheme">
     314;;; Import iota from SRFI 1.
     315(cond-expand
     316  (chicken-4
     317   (use-for-syntax (only srfi-1 iota)))
     318  (chicken-5
     319   (import-for-syntax (only (srfi 1) iota))))
     320
     321(define-syntax c-iota (ck-wrapper iota))
     322
     323(ck () (c-quote (c-iota '5)))
     324;; ==> '(0 1 2 3 4)
     325
     326;;; A helper procedure that returns a closure.
     327(define-for-syntax (make-adder n)
     328  (lambda (x) (+ x n)))
     329
     330;;; Temporarily define a ck-wrapper around a closure.
     331(let-syntax ((c-add2 (ck-wrapper (make-adder 2))))
     332  ;; Map c-add2 over the result of c-iota.
     333  (ck () (c-quote (c-map1 '(c-add2) (c-iota '5)))))
     334;; ==> '(2 3 4 5 6)
     335</enscript>
    195336
    196337
     
    249390
    250391<enscript highlight="scheme">
    251 (ck () (c-quote (c-apply '(c-list) 'a 'b '(c d))))
    252 ;; ==> '(a b c d)
    253 </enscript>
     392(ck () (c-quote (c-apply '(c-list) 'a '(b) '(c d))))
     393;; ==> '(a (b) c d)
     394</enscript>
     395
     396'''Prior to version 0.2.0''', the arguments in the final list required an extra level of quoting.
     397
     398
     399<syntax>(c-compose '((OP-N ...) ... (OP-1 ...)) X ...)  →  result</syntax>
     400
     401Compose one or more CK-macros and apply them to the arguments.
     402Calls the right-most {{OP}} with the arguments {{X ...}},
     403then calls the next-right-most {{OP}} with that result, and so on:
     404
     405 (OP-N ... (OP-2 ... (OP-1 ... X ...)))
     406
     407{{OP-1}} must accept all the {{X}}s as arguments,
     408and the other {{OP}}s must each accept one argument (the result of the previous operation).
     409See also {{c-rcompose}}, which is more efficient.
     410Added in '''version 0.2.0'''
     411
     412
     413<enscript highlight="scheme">
     414(ck () (c-compose '((c-car) (c-cdr)) '(1 2 3)))
     415;; ==> 2
     416
     417;;; Map over a list of lists to see which are not empty.
     418(ck () (c-quote (c-map1 '(c-compose '((c-not) (c-null?)))
     419                        '((1) () (2 3)))))
     420;; ==> '(#t #f #t)
     421</enscript>
     422
     423
     424<syntax>(c-rcompose '((OP-1 ...) ... (OP-N ...)) X ...)  →  result</syntax>
     425
     426Like {{c-compose}}, but the operations are called in the reverse order (left to right).
     427This is more efficient than {{c-compose}}.
     428Added in '''version 0.2.0'''
    254429
    255430
     
    271446Yields {{'#t}} if the argument is {{'#f}}, otherwise yields {{'#f}}.
    272447Analogous to {{not}}.
     448
     449
     450<syntax>(c-true X ...)  →  '#t</syntax>
     451
     452Always yields {{'#t}}, regardless of its arguments.
     453May be useful for some higher-order macros.
     454Added in '''version 0.2.0'''.
     455
     456<enscript highlight="scheme">
     457;;; Recursively check if two structure have the same length,
     458;;; nesting, etc, while ignoring the value of the atoms.
     459(ck () (c-compare? '(c-true) '(1 #(2) 3) '(a #(b) c)))
     460;; ==> '#t
     461</enscript>
     462
     463
     464<syntax>(c-false X ...)  →  '#f</syntax>
     465
     466Always yields {{'#f}}, regardless of its arguments.
     467May be useful for some higher-order macros.
     468Added in '''version 0.2.0'''.
    273469
    274470
     
    312508
    313509<enscript highlight="scheme">
    314 (ck () (c-quote (c-if (c-pair? '(x))
    315                       '(c-car '(x))
    316                       ''not-pair))
     510(ck () (c-quote (c-if* (c-pair? '(x))
     511                       '(c-car '(x))
     512                       ''not-pair))
    317513;; ==> 'x
    318514
    319 (ck () (c-quote (c-if (c-pair? 'x)
    320                       '(c-car 'x)
    321                       ''not-pair))
     515(ck () (c-quote (c-if* (c-pair? 'x)
     516                       '(c-car 'x)
     517                       ''not-pair))
    322518;; ==> 'not-pair
    323519</enscript>
     
    375571
    376572Opposite of {{c-pair?}}.
    377 Analogous to {{not-pair?}} from SRFI-1.
     573Analogous to {{not-pair?}} from SRFI 1.
    378574
    379575
     
    398594
    399595<syntax>(c-sym-eq? X Y)  →  '#t or '#f</syntax>
     596
     597'''ATTENTION:''' This CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]]
     598that you should be aware of.
     599If you don't require strict R5RS portability, it is recommended to use {{c-eq?}} instead.
    400600
    401601Yields {{'#t}} if {{X}} and {{Y}} are the same symbol, otherwise yields {{'#f}}.
     
    412612<syntax>(c-sym-equal? X Y)  →  '#t or '#f</syntax>
    413613
     614'''ATTENTION:''' This CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]]
     615that you should be aware of.
     616If you don't require strict R5RS portability,
     617it is recommended to use {{c-equal?}} instead.
     618
    414619Similar to {{c-sym-eq?}}, except it recursively compares
    415620pairs, lists, and vectors.
     
    420625
    421626
     627<syntax>(c-compare? '(OP ...) X Y)  →  '#t or '#f</syntax>
     628
     629Recursively compares atoms, pairs, lists, or vectors,
     630using {{OP}} as the predicate to compare atoms.
     631Similar to {{equal?}} but with a custom predicate.
     632Added in '''version 0.2.0'''.
     633
     634{{OP}} will be called with two arguments:
     635an atom of {{X}}, and the corresponding atom of {{Y}}.
     636In other words, the Nth atom of {{X}} will be compared with the Nth atom of {{Y}},
     637descending recursively into nested structures.
     638If {{X}} and {{Y}} are themselves atoms, they are compared directly with {{OP}}.
     639
     640Yields {{'#f}} if {{X}} and {{Y}} have dissimilar structures (length, nesting, type),
     641or if {{OP}} yields {{'#f}} for any corresponding atoms of {{X}} and {{Y}}.
     642Otherwise yields '#t.
     643
     644<enscript highlight="scheme">
     645(ck () (c-compare? '(c-string-ci=?) '#("a" ("b")) '#("A" ("B"))))
     646;; ==> #t
     647
     648;;; X is a vector with a list, but Y is a list with a vector.
     649;;; The structures are dissimilar.
     650(ck () (c-compare? '(c-string-ci=?) '#("a" ("b")) '("a" #("b"))))
     651;; ==> #f
     652
     653;;; Can use any predicate. Here, X and Y have same structure,
     654;;; and each atom of X is less than the correponding atom of Y.
     655(ck () (c-compare? '(c-<) '(1 #(5)) '(2 #(6))))
     656;; ==> #t
     657
     658;;; Can compare atoms directly.
     659(ck () (c-compare? '(c-<) '1 '2))
     660;; ==> #t
     661</enscript>
     662
     663
    422664==== List Processing
    423665
    424 <syntax>(c-cons X Y)  →  pair</syntax>
     666<syntax>(c-cons X Y)  →  '(X . Y)</syntax>
    425667
    426668Yields a pair with the two given arguments.
     
    428670
    429671<enscript highlight="scheme">
    430 (ck () (c-quote (c-cons '"a" '1)))
    431 ;; Expands to '("a" . 1).
     672(ck () (c-quote (c-cons 'a 'b)))
     673;; ==> '(a . b).
    432674
    433675(ck () (c-quote (c-cons '+ '(1 2))))
    434 ;; Expands to '(+ 1 2).
     676;; ==> '(+ 1 2).
    435677
    436678(ck () (c-quote (c-cons '+ (c-cons '1 (c-cons '2 '())))))
    437 ;; Also expands to '(+ 1 2).
     679;; ==> '(+ 1 2).
     680</enscript>
     681
     682
     683<syntax>(c-xcons X Y)  →  '(Y . X)</syntax>
     684
     685Like {{c-cons}}, but exchanges the order of arguments.
     686Analogous to {{xcons}} from SRFI 1.
     687
     688<enscript highlight="scheme">
     689(ck () (c-quote (c-xcons 'a 'b)))
     690;; ==> '(b . a).
    438691</enscript>
    439692
     
    494747Fails if the list is too short.
    495748
    496 Analogous to {{first}} ... {{tenth}} from SRFI-1.
     749Analogous to {{first}} ... {{tenth}} from SRFI 1.
    497750
    498751<enscript highlight="scheme">
     
    510763Fails if the list is empty or is not a proper list.
    511764
    512 Analogous to {{last}} from SRFI-1.
     765Analogous to {{last}} from SRFI 1.
    513766
    514767<enscript highlight="scheme">
     
    523776Fails if the list is empty.
    524777
    525 Analogous to {{last-pair}} from SRFI-1.
     778Analogous to {{last-pair}} from SRFI 1.
    526779
    527780<enscript highlight="scheme">
     
    541794See also {{c-udrop}}.
    542795
    543 Analogous to {{(drop L N)}} from SRFI-1.
     796Analogous to {{(drop L N)}} from SRFI 1.
    544797
    545798<enscript highlight="scheme">
     
    562815See also {{c-utake}}.
    563816
    564 Analogous to {{(take L N)}} from SRFI-1.
     817Analogous to {{(take L N)}} from SRFI 1.
    565818
    566819<enscript highlight="scheme">
     
    612865
    613866
    614 <syntax>(c-append-map '(OP ...) L)  →  list</syntax>
     867<syntax>(c-append-map1 '(OP ...) L)  →  list</syntax>
    615868
    616869Yields a list by calling the quoted operation on each item in the list,
     
    620873
    621874Analogous to {{append-map}} from SFRI-1, but only accepts one list.
     875'''Prior to version 0.2.0''', this was named {{c-append-map}}.
    622876This was named {{c-concatMap}} in the original implementation.
    623877
    624878<enscript highlight="scheme">
    625 (ck () (c-quote (c-append-map '(c-list 'a 'b) '(1 2))))
     879(ck () (c-quote (c-append-map1 '(c-list 'a 'b) '(1 2))))
    626880;; ==> '(a b 1 a b 2)
    627881</enscript>
    628882
    629883
    630 <syntax>(c-map '(OP ...) L)  →  list</syntax>
     884<syntax>(c-map1 '(OP ...) L)  →  list</syntax>
    631885
    632886Yields a list by calling the quoted operation on each item in the given list.
    633887The operation may have leading arguments.
    634888Analogous to {{map}}, but only accepts one list.
    635 
    636 <enscript highlight="scheme">
    637 (ck () (c-quote (c-map '(c-cons 'a) '(1 2))))
     889(See also {{c-map2}} ... {{c-map5}} for versions that accept more lists.)
     890'''Prior to version 0.2.0''', this was named {{c-map}}.
     891
     892<enscript highlight="scheme">
     893(ck () (c-quote (c-map1 '(c-cons 'a) '(1 2))))
    638894;; ==> '((a . 1) (a . 2))
    639895</enscript>
    640896
    641897
    642 <syntax>(c-fold '(OP ...) INIT L)  →  result</syntax>
     898<syntax>(c-map2 '(OP ...) L1 L2)  →  list</syntax>
     899<syntax>(c-map3 '(OP ...) L1 L2 L3)  →  list</syntax>
     900<syntax>(c-map4 '(OP ...) L1 L2 L3 L4)  →  list</syntax>
     901<syntax>(c-map5 '(OP ...) L1 L2 L3 L4 L5)  →  list</syntax>
     902
     903Like {{c-map1}}, but they accept exactly two, three, four, or five lists respectively.
     904{{OP}} must accept the two, three, four, or five extra arguments.
     905If the lists are different lengths, terminates when the shortest list runs out.
     906Analogous to {{map}} from SRFI 1, but they accept a specific number of lists.
     907Added in '''version 0.2.0'''.
     908
     909<enscript highlight="scheme">
     910;; The argument '(1 2) is shortest so the result only has two items.
     911(ck () (c-quote (c-map3 '(c-list) '(a b c) '(1 2) '(x y z))))
     912;; ==> '((a 1 x) (b 2 y))
     913</enscript>
     914
     915
     916<syntax>(c-fold1 '(OP ...) INIT L)  →  result</syntax>
    643917
    644918Yield a value by repeatedly calling the quoted operation
     
    652926Yields the final result.
    653927
    654 Analogous to {{fold}} from SRFI-1, but only accepts one list.
    655 
    656 <enscript highlight="scheme">
    657 (ck () (c-quote (c-fold '(c-cons) '(x) '())))
     928Analogous to {{fold}} from SRFI 1, but only accepts one list.
     929'''Prior to version 0.2.0''', this was named {{c-fold}}.
     930
     931<enscript highlight="scheme">
     932(ck () (c-quote (c-fold1 '(c-cons) '(x) '())))
    658933;; ==> '(x)
    659 (ck () (c-quote (c-fold '(c-cons) '(x) '(a b c d e f))))
     934(ck () (c-quote (c-fold1 '(c-cons) '(x) '(a b c d e f))))
    660935;; ==> '(f e d c b a x)
    661936</enscript>
     
    666941Yields a list by calling the quoted operation on each item in the given list,
    667942and discarding any item for which the test yields {{'#f}}.
    668 Analogous to {{filter}} from SRFI-1.
     943Analogous to {{filter}} from SRFI 1.
    669944
    670945<enscript highlight="scheme">
     
    679954Opposite of {{c-filter}}.
    680955Discards items that pass the test, keeps items that fail the test.
    681 Analogous to {{remove}} from SRFI-1.
     956Analogous to {{remove}} from SRFI 1.
    682957
    683958<enscript highlight="scheme">
     
    695970Yields {{'#f}} if no item passes the predicate.
    696971
    697 Analogous to {{find}} from SRFI-1.
     972Analogous to {{find}} from SRFI 1.
    698973
    699974<enscript highlight="scheme">
     
    711986Yields {{'#f}} if no item passes the predicate.
    712987
    713 Analogous to {{find-tail}} from SRFI-1.
     988Analogous to {{find-tail}} from SRFI 1.
    714989
    715990<enscript highlight="scheme">
     
    722997<syntax>(c-member X L)  →  '#t or '#f</syntax>
    723998<syntax>(c-member X L '(OP ...))  →  '#t or '#f</syntax>
     999
     1000'''ATTENTION:''' When using the default comparison operator,
     1001this CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]] that you should be aware of.
     1002If you don't require strict R5RS portability,
     1003it is recommended to use the comparison operator {{'(c-equal?)}} instead.
    7241004
    7251005Searches the list for the first occurance of {{X}},
     
    7501030
    7511031
    752 <syntax>(c-any '(OP ...) L)  →  result or '#f</syntax>
     1032<syntax>(c-any1 '(OP ...) L)  →  result or '#f</syntax>
    7531033
    7541034Calls the operation on each value in the given list
     
    7571037or if the list is empty.
    7581038
    759 Analogous to {{any}} from SRFI-1.
    760 
    761 <enscript highlight="scheme">
    762 (ck () (c-quote (c-any '(c-pair?) '())))
     1039Analogous to {{any}} from SRFI 1, but only accepts one list.
     1040'''Prior to version 0.2.0''', this was named {{c-any}}.
     1041
     1042<enscript highlight="scheme">
     1043(ck () (c-quote (c-any1 '(c-pair?) '())))
    7631044;; ==> '#f
    764 (ck () (c-quote (c-any '(c-pair?) '(a b c))))
     1045(ck () (c-quote (c-any1 '(c-pair?) '(a b c))))
    7651046;; ==> '#f
    766 (ck () (c-quote (c-any '(c-pair?) '(a (b . c)))))
     1047(ck () (c-quote (c-any1 '(c-pair?) '(a (b . c)))))
    7671048;; ==> '#t
    7681049
    769 (ck () (c-quote (c-any '(c-cons 'z) '(a b c))))
     1050(ck () (c-quote (c-any1 '(c-cons 'z) '(a b c))))
    7701051;; ==> '(1 . a)
    7711052;; Because (c-cons 'z 'a) yields a value that is not '#f.
     
    7731054
    7741055
    775 <syntax>(c-every '(OP ...) L)  →  result or '#f</syntax>
     1056<syntax>(c-every1 '(OP ...) L)  →  result or '#f</syntax>
    7761057
    7771058Calls the operation on each value in the given list
     
    7811062Yields {{'#t}} if the list is empty.
    7821063
    783 Analogous to {{every}} from SRFI-1.
    784 
    785 <enscript highlight="scheme">
    786 (ck () (c-quote (c-every '(c-pair?) '())))
     1064Analogous to {{every}} from SRFI 1, but only accepts one list.
     1065'''Prior to version 0.2.0''', this was named {{c-every}}.
     1066
     1067<enscript highlight="scheme">
     1068(ck () (c-quote (c-every1 '(c-pair?) '())))
    7871069;; ==> '#t
    788 (ck () (c-quote (c-every '(c-pair?) '(a (b . c)))))
     1070(ck () (c-quote (c-every1 '(c-pair?) '(a (b . c)))))
    7891071;; ==> '#f
    790 (ck () (c-quote (c-every '(c-pair?) '((a . b) (b . c)))))
     1072(ck () (c-quote (c-every1 '(c-pair?) '((a . b) (b . c)))))
    7911073;; ==> '#t
    7921074
    793 (ck () (c-quote (c-every '(c-cons 'z) '(a b c))))
     1075(ck () (c-quote (c-every1 '(c-cons 'z) '(a b c))))
    7941076;; ==> '(z . c)
    7951077;; Because all results were non-'#f and (c-cons 'z 'c) was the final operation.
     
    7991081<syntax>(c-assoc KEY ALIST)  →  pair or '#f</syntax>
    8001082<syntax>(c-assoc KEY ALIST '(OP ...))  →  pair or '#f</syntax>
     1083
     1084'''ATTENTION:''' When using the default comparison operator,
     1085this CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]] that you should be aware of.
     1086If you don't require strict R5RS portability,
     1087it is recommended to use the comparison operator {{'(c-equal?)}} instead.
    8011088
    8021089Searches {{ALIST}} for the first pair whose car matches {{KEY}},
     
    8081095or {{'(c-sym-equal?)}} if {{'(OP ...)}} is omitted.
    8091096
    810 Analogous to {{assoc}} from SRFI-1.
     1097Analogous to {{assoc}} from SRFI 1.
    8111098
    8121099<enscript highlight="scheme">
     
    8231110<syntax>(c-alist-delete KEY ALIST '(OP ...))  →  list</syntax>
    8241111
     1112'''ATTENTION:''' When using the default comparison operator,
     1113this CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]] that you should be aware of.
     1114If you don't require strict R5RS portability,
     1115it is recommended to use the comparison operator {{'(c-equal?)}} instead.
     1116
    8251117Removes all pairs in {{ALIST}} whose car matches {{KEY}}.
    8261118{{ALIST}} must be an association list, i.e. a list of pairs.
     
    8291121or {{'(c-sym-equal?)}} if {{'(OP ...)}} is omitted.
    8301122
    831 Analogous to {{alist-delete}} from SRFI-1.
     1123Analogous to {{alist-delete}} from SRFI 1.
    8321124Based on {{c-delete-assoc}} from the original implementation.
    8331125
     
    8511143
    8521144Yields a vector containing the same items as the given list.
    853 Analogous to {{list->vector}} from SRFI-43.
     1145Analogous to {{list->vector}} from SRFI 43.
    8541146
    8551147
     
    8571149
    8581150Yields a list containing the same items as the given vector.
    859 Analogous to {{vector->list}} from SRFI-43.
     1151Analogous to {{vector->list}} from SRFI 43.
    8601152
    8611153
     
    8631155
    8641156Yields the given vector in reverse order.
    865 Similar to {{vector-reverse-copy}} from SRFI-43,
     1157Similar to {{vector-reverse-copy}} from SRFI 43,
    8661158but does not take a start or end argument.
    8671159
     
    8801172
    8811173Appends the given vectors.
    882 Analogous to {{vector-append}} from SRFI-43,
     1174Analogous to {{vector-append}} from SRFI 43,
    8831175but only accepts two vectors.
    8841176
     
    8921184
    8931185
    894 <syntax>(c-vector-map '(OP ...) V)  →  vector</syntax>
     1186<syntax>(c-vector-map1 '(OP ...) V)  →  vector</syntax>
    8951187
    8961188Yields a vector by calling the quoted operation on each item in the given vector.
    8971189The operation may have leading arguments.
    8981190
    899 Analogous to {{vector-map}} from SRFI-43, but only accepts one vector.
    900 
     1191Analogous to {{vector-map}} from SRFI 43, but only accepts one vector.
     1192'''Prior to version 0.2.0''', this was named {{c-vector-map}}.
    9011193
    9021194
     
    10231315
    10241316Unary {{odd?}}.
    1025 Yields {{'#t}} if the given list's length is odd length
     1317Yields {{'#t}} if the given list's length is odd
    10261318(i.e. not a multiple of 2), otherwise yields {{'#f}}.
    10271319
     
    11081400Otherwise, yields a list containing items of the given list repeated {{(N-1)!}} times,
    11091401where {{N}} is the length of the given list.
    1110 This was named {{c-fact}} in the original source.
     1402This was named {{c-fact}} in the original implementation.
    11111403
    11121404<enscript highlight="scheme">
     
    11231415
    11241416Same as {{c-u-}}.
    1125 Analogous to {{drop}} from SRFI-1,
     1417Analogous to {{drop}} from SRFI 1,
    11261418but uses unary numbers,
    11271419and yields empty list if the list is too short.
     
    11401432where U is a unary number.
    11411433
    1142 Analogous to {{take}} from SRFI-1,
     1434Analogous to {{take}} from SRFI 1,
    11431435but uses unary numbers,
    11441436and yields the entire list if it is too short.
     
    11501442;; ==> '(a b)
    11511443</enscript>
     1444
     1445
     1446
     1447=== Non-portable R5RS Wrappers
     1448
     1449These are CK-macros that wrap some R5RS procedures that are useful for building macros.
     1450Not every R5RS procedure is provided here.
     1451If you need other procedures, use [[#ck-wrapper|{{ck-wrapper}}]]
     1452to create your own wrappers.
     1453
     1454These wrappers are considered non-portable because they use ck-wrapper,
     1455which is not portable to all R5RS Scheme implementations.
     1456See the ck-wrapper docs for portability information.
     1457
     1458Some R5RS procedures have portable, non-wrapper CK-macro equivalents,
     1459which are described in the [[#portable-ck-macros|Portable CK-macros]] section, above.
     1460For example, there is no wrapper for {{pair?}} listed below,
     1461because {{c-pair?}} is a portable CK-macro listed above.
     1462
     1463
     1464==== General (R5RS Wrappers)
     1465
     1466<syntax>(c-eqv? X Y)  →  '#t or '#f</syntax>
     1467
     1468CK-macro wrapper for {{eqv?}}.
     1469Added in '''version 0.2.0'''.
     1470
     1471<syntax>(c-eq? X Y)  →  '#t or '#f</syntax>
     1472
     1473CK-macro wrapper for {{eq?}}.
     1474Added in '''version 0.2.0'''.
     1475
     1476<syntax>(c-equal? X Y)  →  '#t or '#f</syntax>
     1477
     1478CK-macro wrapper for {{equal?}}.
     1479Added in '''version 0.2.0'''.
     1480
     1481
     1482==== Numbers and Math (R5RS Wrappers)
     1483
     1484<syntax>(c-number? X)  →  '#t or '#f</syntax>
     1485
     1486CK-macro wrapper for {{number?}}.
     1487Added in '''version 0.2.0'''.
     1488
     1489<syntax>(c-integer? X)  →  '#t or '#f</syntax>
     1490
     1491CK-macro wrapper for {{integer?}}.
     1492Added in '''version 0.2.0'''.
     1493
     1494<syntax>(c-= N ...)  →  '#t or '#f</syntax>
     1495
     1496CK-macro wrapper for {{=}} (equal).
     1497Added in '''version 0.2.0'''.
     1498
     1499<syntax>(c-< N ...)  →  '#t or '#f</syntax>
     1500
     1501CK-macro wrapper for {{<}} (less than).
     1502Added in '''version 0.2.0'''.
     1503
     1504<syntax>(c-> N ...)  →  '#t or '#f</syntax>
     1505
     1506CK-macro wrapper for {{>}} (greater than).
     1507Added in '''version 0.2.0'''.
     1508
     1509<syntax>(c-<= N ...)  →  '#t or '#f</syntax>
     1510
     1511CK-macro wrapper for {{<=}} (less than or equal).
     1512Added in '''version 0.2.0'''.
     1513
     1514<syntax>(c->= N ...)  →  '#t or '#f</syntax>
     1515
     1516CK-macro wrapper for {{>=}} (greater than or equal).
     1517Added in '''version 0.2.0'''.
     1518
     1519<syntax>(c-max N ...)  →  number</syntax>
     1520
     1521CK-macro wrapper for {{max}}.
     1522Added in '''version 0.2.0'''.
     1523
     1524<syntax>(c-min N ...)  →  number</syntax>
     1525
     1526CK-macro wrapper for {{min}}.
     1527Added in '''version 0.2.0'''.
     1528
     1529<syntax>(c-+ N ...)  →  number</syntax>
     1530
     1531CK-macro wrapper for {{+}} (addition).
     1532Added in '''version 0.2.0'''.
     1533
     1534<syntax>(c-* N ...)  →  number</syntax>
     1535
     1536CK-macro wrapper for {{*}} (multiplication).
     1537Added in '''version 0.2.0'''.
     1538
     1539<syntax>(c-- N ...)  →  number</syntax>
     1540
     1541CK-macro wrapper for {{-}} (subtraction).
     1542Added in '''version 0.2.0'''.
     1543
     1544<syntax>(c-/ N ...)  →  number</syntax>
     1545
     1546CK-macro wrapper for {{/}} (division).
     1547Added in '''version 0.2.0'''.
     1548
     1549<syntax>(c-remainder N1 N2)  →  number</syntax>
     1550
     1551CK-macro wrapper for {{remainder}}.
     1552Added in '''version 0.2.0'''.
     1553
     1554<syntax>(c-floor N)  →  number</syntax>
     1555
     1556CK-macro wrapper for {{floor}}.
     1557Added in '''version 0.2.0'''.
     1558
     1559<syntax>(c-round N)  →  number</syntax>
     1560
     1561CK-macro wrapper for {{round}}.
     1562Added in '''version 0.2.0'''.
     1563
     1564<syntax>(c-exact->inexact N)  →  inexact number</syntax>
     1565
     1566CK-macro wrapper for {{exact->inexact}}.
     1567Added in '''version 0.2.0'''.
     1568
     1569<syntax>(c-inexact->exact N)  →  exact number</syntax>
     1570
     1571CK-macro wrapper for {{inexact->exact}}.
     1572Added in '''version 0.2.0'''.
     1573
     1574<syntax>(c-number->string N)  →  string</syntax>
     1575<syntax>(c-number->string N RADIX)  →  string</syntax>
     1576
     1577CK-macro wrapper for {{number->string}}.
     1578Added in '''version 0.2.0'''.
     1579
     1580<syntax>(c-string->number STR)  →  number or '#f</syntax>
     1581<syntax>(c-string->number STR RADIX)  →  number or '#f</syntax>
     1582
     1583CK-macro wrapper for {{string->number}}.
     1584Added in '''version 0.2.0'''.
     1585
     1586
     1587==== Pairs and Lists (R5RS Wrappers)
     1588
     1589<syntax>(c-length L)  →  integer</syntax>
     1590
     1591CK-macro wrapper for {{length}}.
     1592Added in '''version 0.2.0'''.
     1593
     1594<syntax>(c-list-ref L I)  →  item</syntax>
     1595
     1596CK-macro wrapper for {{list-ref}}.
     1597Added in '''version 0.2.0'''.
     1598
     1599
     1600==== Symbols (R5RS Wrappers)
     1601
     1602<syntax>(c-symbol? X)  →  '#t or '#f</syntax>
     1603
     1604CK-macro wrapper for {{symbol?}}.
     1605Added in '''version 0.2.0'''.
     1606
     1607<syntax>(c-symbol->string SYM)  →  string</syntax>
     1608
     1609CK-macro wrapper for {{symbol->string}}.
     1610Added in '''version 0.2.0'''.
     1611
     1612<syntax>(c-string->symbol STR)  →  symbol</syntax>
     1613
     1614CK-macro wrapper for {{string->symbol}}.
     1615Added in '''version 0.2.0'''.
     1616
     1617
     1618==== Chars and Strings (R5RS Wrappers)
     1619
     1620<syntax>(c-char? CHAR ...)  →  '#t or '#f</syntax>
     1621
     1622CK-macro wrapper for {{char?}}.
     1623Added in '''version 0.2.0'''.
     1624
     1625<syntax>(c-char=? CHAR ...)  →  '#t or '#f</syntax>
     1626
     1627CK-macro wrapper for {{char=?}}.
     1628Added in '''version 0.2.0'''.
     1629
     1630<syntax>(c-string? X)  →  '#t or '#f</syntax>
     1631
     1632CK-macro wrapper for {{string?}}.
     1633Added in '''version 0.2.0'''.
     1634
     1635<syntax>(c-string CHAR ...)  →  string</syntax>
     1636
     1637CK-macro wrapper for {{string}}.
     1638Added in '''version 0.2.0'''.
     1639
     1640<syntax>(c-string-length STR)  →  integer</syntax>
     1641
     1642CK-macro wrapper for {{string-length}}.
     1643Added in '''version 0.2.0'''.
     1644
     1645<syntax>(c-string-ref STR I)  →  char</syntax>
     1646
     1647CK-macro wrapper for {{string-ref}}.
     1648Added in '''version 0.2.0'''.
     1649
     1650<syntax>(c-string=? STR ...)  →  '#t or '#f</syntax>
     1651
     1652CK-macro wrapper for {{string=?}}.
     1653Added in '''version 0.2.0'''.
     1654
     1655<syntax>(c-string-ci=? STR ...)  →  '#t or '#f</syntax>
     1656
     1657CK-macro wrapper for {{string-ci=?}}.
     1658Added in '''version 0.2.0'''.
     1659
     1660<syntax>(c-substring STR START)  →  string</syntax>
     1661<syntax>(c-substring STR START END)  →  string</syntax>
     1662
     1663CK-macro wrapper for {{substring}}.
     1664Added in '''version 0.2.0'''.
     1665
     1666<syntax>(c-string-append STR ...)  →  string</syntax>
     1667
     1668CK-macro wrapper for {{string-append}}.
     1669Added in '''version 0.2.0'''.
     1670
     1671
     1672==== Vectors (R5RS Wrappers)
     1673
     1674<syntax>(c-vector-length V)  →  integer</syntax>
     1675
     1676CK-macro wrapper for {{vector-length}}.
     1677Added in '''version 0.2.0'''.
     1678
     1679<syntax>(c-vector-ref V I)  →  item</syntax>
     1680
     1681CK-macro wrapper for {{vector-ref}}.
     1682Added in '''version 0.2.0'''.
Note: See TracChangeset for help on using the changeset viewer.