diff options
Diffstat (limited to 'doc/ref/general/util.texi')
-rw-r--r-- | doc/ref/general/util.texi | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/doc/ref/general/util.texi b/doc/ref/general/util.texi new file mode 100644 index 00000000..bae19987 --- /dev/null +++ b/doc/ref/general/util.texi @@ -0,0 +1,359 @@ +@node Miscellaneous utilities +@section Miscellaneous utilities + +Provided by the module @code{(hnh util)}. + +@defmac define-syntax [stx] +Extends the default syntax from the default +@lisp +(define-syntax @r{<name>} (λ (stx) body ...)) +@end lisp +To also allow +@lisp +(define-syntax (@r{<name>} stx) body ...) +@end lisp +@end defmac + + +@defmac when pred body ... +@defmacx unless pred body ... +Extends @var{when} and @var{unless} to return @code{'()} on the +false-case (instead of being undefined). +@end defmac + + +@defmac aif condition consequent alternate +@defmacx awhen condition consequent ... +Equivalent to the standard @var{if} and @var{when}@footnote{Actually +our extra specialized @var{when}}, but binds the return of +@var{condition} in the variable @var{it}. +@end defmac + + +@defmac for key in collection body ... +@defmacx for (key ...) in collection body ... +Syntactic sugar over @code{map}. +@example +(for x in collection + body ...) +@end example +expands into +@example +(map (lambda (x) body ...) collection) +@end example + +If keys are a list, an match-lambda is used instead. +@xref{Pattern Matching,,,guile} + +@defun break args ... +Abandon the entire loop. Returing what was given to @code{break}. +@end defun + +@defun continue [arg] +Abandon the current iteration of the loop. If an argument is given, +it's used as the result in the resulting list, otherwise @code{#f} is +used. +@end defun + +@end defmac + + +@defmac print-and-return expr +Prints @var{expr}, and then returns it. +Only evaluates @var{expr} once. +@end defmac + + +@defun swap f +@math{swap (λ (x y) body ...) ⇔ λ (y x) body ...} +@end defun + +@defmac set! key value ... +@defmacx set! key = proc ... +@defmacx set! key = (op args ...) ... +Extends @var{set!} to allow multiple forms in one, also introduces the +cases: +@lisp +(set! x = f) ⇔ (set! x (f x)) +(set! x = (+ 1) ⇔ (set! x (+ x 1)) +@end lisp +@end defmac + +@defmac set/r! key value ... +See @var{set!}, but also returns the final value. +@end defmac + +@defmac label name proc +Equivalent to +@lisp +(letrec ((name proc)) + proc) +@end lisp +@end defmac + + +@defun sort* items comperator [get=identity] +@defunx sort*! items comperator [get=identity] +A sort more similar to Python's. Applies @var{get} to each item before +calling @var{comperator} on them. + +@var{sort*!} may modify the input list. +@end defun + + +@defun find-extreme items [<=<] [access=identity] +Returns 2 values, the most extreme value, as compared by @var{<} after +calling @var{access} on each element, along with the remaining values +in an undefined order. + +Should be faster than @var{car+cdr} ∘ @var{sort*}. +@end defun + +@defun find-min list [access=identity] +@defunx find-max list [access=identity] +See @var{find-extreme} +@end defun + +@defun filter-sorted proc list +@c TODO document me +@end defun + +@defun != args ... +@lisp +(define != (negate =)) +@end lisp +@end defun + +@defun take-to lst n +Equivalent to @var{take}, but return everything (instead of crash) if +n > (length lst). +@end defun + +@defun string-take-to str n +Same as @var{take-to}, but for strings +@end defun + + +@defun string-first +@defunx string-last +Returns the first and last character of a string respectivly +@end defun + + +@defun as-symb s +Returns @code{(string->symbol s)} if @var{s} is a string, @var{s} otherwise. +@end defun + +@defun enumerate lst +Returns a list of lists, where the @var{car} is the index in the list, +and the @var{cadr} is the corresponding element of the original list +@end defun + + +@defun unval proc [n=0] +Takes a procedure returning multiple values, and returns a function +which takes the same arguments as the original procedure, but only +returns one of the procedures. Which procedure can be sent as an +additional parameter. +@end defun + + +@defun flatten lst +Takes an arbitrarily nested list, and flattens it to a depth 1 list +@end defun + + +@defmac let-lazy forms body ... +Syntactically equivalent to a regular @var{let}, but wraps each variable +in @var{forms} in @var{delay}, while it finds each instance of that +variable in body and wraps in in @var{force}. +@end defmac + + +@defun map/dotted proc dotted-list +Like @var{map}, but also works for improper lists. +@end defun + + +@defun assq-merge a b +@c TODO +@end defun + +@defun kvlist->assq +Given a flat list where each odd element (counting from 1) is a +keyword, and each even element is any value, return these as a list of +pairs of symbols and values. + +@lisp +(kvlist->assq '(#:a 1 #:b "Hello")) +⇒ ((a . 1) + (b . "Hello")) +@end lisp +@end defun + +@defun assq-limit alist [number=1] +@c TODO document +@end defun + +@defun group-by proc lst +Calls @var{proc} on each element in @var{lst}, and return a +association list which @code{(proc e)} as its keys, and all elements +which mapped to that value. + +The values returned by @var{proc} are compared as per @code{equal?}. +@end defun + +@defun split-by lst element +Split a list into sub-lists on @var{element} +@lisp +(split-by '(0 1 2 3 4 2 5 6) 2) +⇒ ((0 1) (3 4) (5 6)) +@end lisp +@end defun + + +@defun span-upto count predicate list +Simar to span from srfi-1, but never takes more than +@var{count} items. Can however still take less. +@example +(span-upto 2 char-numeric? (string->list "123456")) +⇒ (#\1 #\2) +⇒ (#\3 #\4 #\5 #\6) +(span-upto 2 char-numeric? (string->list "H123456")) +⇒ () +⇒ (#\H #\1 #\2 #\3 #\4 #\5 #\6) +@end example +@end defun + + +@defun cross-product args ... +Returns the cross product between all given lists. Each pair will be a +list, whose indices matches the order of the inputs +@end defun + +@defun string-flatten tree +@c TODO document me +@end defun + +@defun intersperse item list +Inserts @var{item} between each element in @var{list}. +@end defun + + +@defun insert-ordered item collection [<=<] +Inserts @var{item} into @var{collection}, such that collection +remainins sorted if it was sorted beforehand. +@end defun + + +@defmac -> item forms ... +@defmacx ->> item forms ... +Applies each form onto item, from left to right. +A form can either by a symbol, which is the applied directly, or a +list, in which case @var{->} inserts item as the second argument +(after the operand), and @var{->>} inserts it last. +@end defmac + + +@defmac set (accessor object) value +@defmacx set (accessor object) = (operation args ...) +See @xref{SRFI-9 Records,,,guile} +@end defmac + +@defmac set-> object (accessor value) rest ... +@defmacx set-> object (accessor = (operator args)) rest ... +Wrapper around @var{set}, but applies transformations from left to +right, similar to @var{->}. +@end defmac + + +@defmac and=>> value procedures ... +Chained application of @code{and=>}, so applies each procedure from +left to right, stopping when one return @code{#f}. +@end defmac + +@defun downcase-symbol +Converts a symbol to lower case. +@end defun + + +@defun group list chunk-size +Splits @var{list} into sub-lists of size @var{chunk-size}. +Requires that @math{chunk-size|(length list)} +@end defun + + +@defun iterate proc until base +Repeatedly applies @var{proc} to @var{base}, until @var{until} is +satisfied. +@end defun + +@defun valued-map proc lists ... +Applies a procedure which returns multiple values to each element of a +list, and returns all values returned from all procedure calls. +@example +(define (± x) (values x (- x))) +(valued-map ± '(1 2)) +⇒ 1 +⇒ -1 +⇒ 2 +⇒ -2 +@end example +@end defun + + +@defun assoc-ref-all alist key +@defunx assq-ref-all alist key +@defunx assv-ref-all alist key +Equivalent to assoc-ref (and family), but works on association lists with +non-unique keys, returning all mathing records (instead of just the first). +@lisp +(assoc-ref-all '((a . 1) (b . 2) (a . 3)) 'a) +⇒ (1 3) +@end lisp +@end defun + + +@defun vector-last v +Returns the last element of @var{v}. +@end defun + +@defun ->string any +Converts @var{any} to a string, as per @var{display}. +@end defun + + +@defmac let-env bindings body ... +Similar to @var{let}, but sets environment variables for the code in +body. Restores the old values once we leave. + +A variable can also be removed from the environment, by setting its +value to @code{#f}. +@end defmac + +@defmac catch* thunk (symbol proc) ... +Macro allowing multiple exception types to be caught. Each (symbol +proc) pair expands to a regular @code{catch}, with the leftmost being +innermost. + +@var{Symbol} can also be on the form @code{(pre-unwind @var{symbol})}, +then @code{with-throw-handler} is used instead of @code{catch}. +@end defmac + +@defun uniq lst +@defunx univ lst +@defunx unique lst +@defunx uniqx comp lst +Squash repeated equivalent elements in a list into single instances, +similar to the POSIX command uniq(1). The three variants uses +@code{eq?}, @code{eqv?}, and @code{equal?} respectively. + +@code{uniqx} also takes @var{comp}, which is sholud be a binary +procedure returning if the elements are equal. +@end defun + +@defmac begin1 forms ... +Port of Common Lisp's @code{begin1} form. Like @code{begin} runs each +form in its body in order, but returns the first result instead of the +last. +@end defmac |