On this page:
1.1 Iteration Forms
for/  fold/  define
for*/  fold/  define
for/  lists/  define
for*/  lists/  define
1.2 Guarded Evaluation:   when-like Forms
string-when
string-unless
list-when
list-unless
1.3 Small Utilities
values->list
list->values
any->boolean
infix:
ip-port-num/  c
1.4 Regular Expressions
rx
px
1.5 Definitions
define*
def
define-alias
define-aliases
1.6 Serialization
serialize-to-string
deserialize-from-string
1.7 Sequence Constructors
in-value*
in-value*/  generator
in-value*-record?
in-value*/  expression
1.8 require-provide:   Abbreviations for Re-Exporting
require-provide
provide-only
7.1

1 Stable

This section documents the stable portion of adjutor.

1.1 Iteration Forms

syntax

(for/fold/define ([accum-id init-expr] ...)
                 (for-clause ...)
  body-or-break ... body)

syntax

(for*/fold/define ([accum-id init-expr] ...)
                  (for-clause ...)
  body-or-break ... body)
Like for/fold and for*/fold, respectively, but rather than returning (potentially multiple) values, binds each accum-id to the final result of the iterations.

For example, for/fold/define is equivalent to
(define-values (accum-id ...)
  (for/fold ([accum-id init-expr] ...)
            (for-clause ...)
    body-or-break ... body))

Note that the #:result clause of for/fold and for*/fold (added in Racket 6.11.0.1) is not currently supported.

Examples:
> (for/fold/define ([keys '()]
                    [vals '()])
                   ([pr '([a . 1]
                          [b . 2]
                          [c . 3])])
    (match pr
      [(cons k v)
       (values (cons k keys)
               (cons v vals))]))
> keys

'(c b a)

> vals

'(3 2 1)

syntax

(for/lists/define (id ...)
                  (for-clause ...)
  body-or-break ... body)

syntax

(for*/lists/define (id ...)
                   (for-clause ...)
  body-or-break ... body)
Similar to for/lists and for*/lists, respectively, but binds each id to the corresponding final result of the iterations similarly to for/fold/define and for*/fold/define.

Examples:
> (for/lists/define (keys vals)
                    ([pr '([a . 1]
                           [b . 2]
                           [c . 3])])
    (match pr
      [(cons k v)
       (values k v)]))
> keys

'(a b c)

> vals

'(1 2 3)

1.2 Guarded Evaluation: when-like Forms

syntax

(string-when test body ...+)

syntax

(string-unless test body ...+)

Like when and unless, respectively, but with "" (rather than #<void>) as the default value when test prevents the evaluation of the body forms.

Examples:
> (string-when (= 1 1)
    "This is returned")

"This is returned"

> (string-unless (= 1 1)
    "Default is returned")

""

> (string-when #f
    (+ 42 "This would be an error"))

""

syntax

(list-when test body ...+)

syntax

(list-unless test body ...+)

Like string-when and string-unless, respectively, but with null as the default value.

Examples:
> (list-when (= 1 1)
    `(1 1 2 3 5 8))

'(1 1 2 3 5 8)

> (list-unless (= 1 1)
    "Default is returned")

'()

> (list-when #f
    (+ 42 "This would be an error"))

'()

1.3 Small Utilities

syntax

(values->list body ...+)

procedure

(list->values lst)  any

  lst : list?
Helpers to make forms that expect and/or produce multiple return values interoperable with those that produce and consume lists.

Examples:
> (values->list (values 1 2 3 4))

'(1 2 3 4)

> (define-values (val1 val2)
    (list->values `(first-item second-item)))
> val1

'first-item

> val2

'second-item

procedure

(any->boolean x)  boolean?

  x : any/c
Returns #t for any input but #f.

syntax

(infix: left op right)

Provides infix notation for binary operators, expanding to (op left right).

Infix notation is often useful, especially for noncommutative binary operators like <. Racket supports reader-based infix notation by default, so you can write (< 1 2). However, a disadvantage of this notation for those used to reading Racket syntax is that the beginning of the s-expression doesn’t make it obvious that infix notation is being used. This is particularly a problem when the expression immediately following the ( is more complex than 1, as it might be confused with a function or macro application.

This macro provides an alternative infix notation specialized for the common case of binary operators, allowing the above expression to be written as (infix: 1 < 2).

value

ip-port-num/c : flat-contract? = (integer-in 0 65535)

A contract recognizing legal IP port numbers.

Added in version 0.2.1 of package adjutor.

1.4 Regular Expressions

procedure

(rx [#:handler handler] arg ...)  regexp?

  handler : (or/c #f (-> any/c any)) = #f
  arg : string?
(rx [#:handler handler] arg ...+)  byte-regexp?
  handler : (or/c #f (-> any/c any)) = #f
  arg : bytes?

procedure

(px [#:handler handler] arg ...)  pregexp?

  handler : (or/c #f (-> any/c any)) = #f
  arg : string?
(px [#:handler handler] arg ...+)  byte-pregexp?
  handler : (or/c #f (-> any/c any)) = #f
  arg : bytes?
Functions that concatenate their arguments into a regular expression value. A handler, if given, used as with regexp etc.

As a special case, in an application visible at compile-time when every arg is a literal string or byte string, the regular expression value is generated at compile time rather than runtime. In this case, any handler expression is not even evaluated: instead, a compile-time error is raised if the arguments are invalid.

These functions are particularly designed for use with the @ Syntax.

1.5 Definitions

syntax

(define* define-lhs maybe-with-clause body ...+)

 
maybe-with-clause = 
  | #:with [definition-or-expr ...]
The function form of define helps with readability, but it doesn’t work well for functions that want to maintain private state via a "let-over-lambda". Also, when binding a plain identifier with define, it is a syntax error to have "multiple expressions after identifier". These limitations are solved with define*.

When the #:with clause is ommited, define* works just like define, except that multiple body forms are allways allowed. (As usual, these can be arbitrary definitions and expressions, but they must end with an expression.)

If a #:with clause is given, it may contain arbitrary definitions and expressions (and may conclude with a definition). These are lifted outside the function, if applicable, and any identifiers defined in the #:with clause are only in scope within the define* form. If define-lhs specifies a curried function, the #:with clause is evaluated outside of the outermost function.

Examples:
> (define* (add-to-base n)
    #:with [(define base
              (random 100))]
    (+ n base))
> (add-to-base 5)

39

> (add-to-base 5)

39

> (define* watermellons
    (displayln "Defining watermellons!")
    "watermellons")

Defining watermellons!

> watermellons

"watermellons"

syntax

(def def-clause ...)

 
def-clause = [id rhs]
  | [function-header body ...+]
Concisely define multiple identifiers with a let-like syntax that also supports the best features of define.

Examples:
> (def
    [(add2 n) (+ 2 n)]
    [fruits '(apples peaches pears)])
> (add2 5)

7

> fruits

'(apples peaches pears)

syntax

(define-alias new-id orig-id)

Short for (define-syntax new-id (make-rename-transformer #'orig-id))

syntax

(define-aliases [new-id orig-id] ...+)

Short for multiple define-alias forms.

1.6 Serialization

procedure

(serialize-to-string v)  (and/c string? immutable?)

  v : serializable?

procedure

(deserialize-from-string str)  any/c

  str : string?
Like serialize and deserialize, respectively, but using a string for the serialized value.

Added in version 0.2.5 of package adjutor.

1.7 Sequence Constructors

In addition to the stable sequence constructors documented in this section, the experimental portion of adjutor provides in-match.

procedure

(in-value* expr ...)  (and/c sequence? in-value*-record?)

  expr : any/c
Produces a sequence which is similar to those produced by in-value in that it has only a single element; however, whereas in-value produces single-valued sequences, the sequence produced by in-value* has as many values as there are expr expressions.

In other words, if in-value is "useful for let-like bindings in forms such as for*/list", in-value* is useful for let-values-like bindings.

An in-value* application can provide better performance when it appears directly in a for clause.

Examples:
> (for/list ([(a b c) (in-value* 1 2 3)])
    (vector a b c))

'(#(1 2 3))

> (define seq
    (in-value*))
> seq

#<in-value*-record>

> (for/first ([() seq])
    '|This works|)

'|This works|

procedure

(in-value*/generator generator)

  (and/c sequence? in-value*-record?)
  generator : (or/c (-> any) in-value*-record?)

procedure

(in-value*-record? v)  any/c

  v : any/c
The function in-value*/generator creates a single-element, potentially-multi-valued sequence like in-value*, where the values are determined by generator. If generator is a thunk, the values are the results of calling generator. Otherwise, generator must be a sequence constructed using in-value*, in-value*/expression, or in-value*/generator, in which case generator is returned directly (but potentially with a performance advantage when used directly in a for clause). Sequences that may be used for generator are recognized by the predicate in-value*-record?.

An in-value*/generator application can provide better performance when it appears directly in a for clause.

Examples:
> (define (gen)
    (values "apples" "peaches" "pears"))
> (for/list ([(a b c) (in-value*/generator gen)])
    (string-append a " & " b " & " c))

'("apples & peaches & pears")

> (define seq
    (in-value* "apples" "peaches" "pears"))
> (for/list ([(a b c) (in-value*/generator seq)])
    (string-append a " & " b " & " c))

'("apples & peaches & pears")

syntax

(in-value*/expression body-expr)

Creates a sequence that is conceptually equivalent to (in-value*/generator (λ () body-expr)). Note that this means that body-expr is evaluated each time the resulting sequence is initiated.

An in-value*/expression application can provide better performance when it appears directly in a for clause. Using in-value*/expression may also have advantages over in-value*/generator in such cases.

Examples:
> (define seq
    (in-value*/expression
     (current-inexact-milliseconds)))
> (for/first ([msec seq])
    msec)

1543411658543.677

> (for*/list ([task `([1 1 2]
                      [4 5]
                      [5 5 3]
                      [15 35 8])]
              [(a b c) (in-value*/expression
                        (match task
                          [(list a b c)
                           (values a b c)]
                          [(list a b)
                           (values a b 0)]))])
    (- (+ a b) c))

'(0 9 7 42)

> (for/first ([msec seq])
    msec)

1543411658589.669

1.8 require-provide: Abbreviations for Re-Exporting

syntax

(require-provide require-provide-spec ...)

 
require-provide-spec = module-path
  | adjust-require
  | adjust-provide
  | derived-require-provide-spec
     
adjust-require = (only-in require-provide-spec id-maybe-renamed ...)
  | (except-in require-provide-spec excluded-id ...)
  | (prefix-in prefix require-provide-spec)
  | 
(rename-in require-provide-spec
           [orig-id in-id] ...)
  | (only-meta-in phase-level require-provide-spec)
  | (provide-only module-path ...)
     
adjust-provide = (except-out require-provide-spec excluded-id ...)
  | 
(rename-out require-provide-spec
            [orig-id out-id] ...)
  | (prefix-out prefix require-provide-spec)
     
adjust-both = (for-syntax require-provide-spec ...)
  | (for-template require-provide-spec ...)
  | (for-label require-provide-spec ...)
  | (for-meta phase-level require-provide-spec ...)
     
id-maybe-renamed = orig-id
  | [orig-id renamed]
In the simplest case, when require-provide-spec is a plain module-path (as specified by require and provide) for
(require module-path ...)
(provide (all-from-out module-path ...))

Other kinds of require-provide-spec adjust what is required, provided, or both. Note that a few have a subtly different grammar than when used with require or provide. All are recognized by binding, rather than symbolically.

For details on derived-require-provide-spec (i.e. programmer-implemented extensions to require-provide), see Extending require-provide below, but note that the extension mechanism is unstable and subject to change.

Examples:
> (module example racket/base
    (require adjutor)
    (require-provide (provide-only adjutor)
                     (prefix-in : racket/stream)
                     (prefix-out : racket/string))
    (:stream 1 2 3)
    (string-join '("Works without a prefix here,"
                   "but exported with a prefix.")
                 " "))
> (require 'example)

#<stream>

"Works without a prefix here, but exported with a prefix."

> (string-when #t
    (:string-join '("Here," "it has a prefix")
                  " "))

"Here, it has a prefix"

> (:stream "Still has a prefix")

#<stream>

syntax

(provide-only module-path ...)

The provide-only form cooperates with require-provide to export all bindings from each module-path, which should have been used in a require form elsewhere.

This might be desireable when a module is re-exporting bindings from a number of other modules via require-provide, but also wants to export bindings from some module which it had to import via require, perhaps because that module gave it the require-provide binding itself. Thus, for example,
(require adjutor)
(require-provide (provide-only adjutor))
could be used as an alternative to
(require adjutor)
(provide (all-from-out adjutor))

Use of provide-only outside of a require-provide form is a syntax error.