1 Stable

7.7

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.

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)
100
> (add-to-base 5)
100
> (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, 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)
1588682419661.526
> (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)
1588682419692.163

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.

top ← prev up next →

1.1	Iteration Forms
1.2	Guarded Evaluation: when-like Forms
1.3	Small Utilities
1.4	Regular Expressions
1.5	Definitions
1.6	Serialization
1.7	Sequence Constructors
1.8	require-provide: Abbreviations for Re-Exporting