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
environment-variables-set*
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
8.12

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)

Changed in version 0.3.2 of package adjutor: Fixed wrapping of body-or-break forms.

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).

A flat contract corresponding to listen-port-number? from racket/tcp, which recognizes valid TCP/IP port numbers for tcp-listen and related operations: that is, (integer-in 0 65535). Currently, ip-port-num/c is an alias for listen-port-number?.

Added in version 0.2.1 of package adjutor.
Changed in version 0.3.2: Became an alias for listen-port-number?.

procedure

(environment-variables-set* env    
  key    
  value ...    
  ...)  environment-variables?
  env : environment-variables?
  key : bytes-environment-variable-name?
  value : (or/c bytes-no-nuls? #f)
Returns a fresh environment variable set like env, but extended with mappings from each given key to the new value.

As with hash-set*, latter mappings for a given key overwrite earlier mappings.

Changed in version 0.3 of package adjutor: Moved from unstable.

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)

27

> (add-to-base 5)

27

> (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.

Changed in version 0.3.2 of package adjutor: Fixed implementation to accept documented syntax.

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, adjutor/unstable 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)

1707247458014.1401

> (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)

1707247458028.3718

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.