▼scramble:   Assorted Utility Libraries
On this page:
begin/  inject-syntax
8.16.0.4
  top  contents    up   

19 Compile-time Code Injection🔗ℹ

 (require scramble/inject-syntax) package: scramble-lib

syntax

(begin/inject-syntax body ...+)

Evaluates the body forms at compile time. The bodys must end in an expression that produces a syntax object; otherwise, a syntax error is raised. The syntax object result replaces the begin/inject-syntax form. In other words, a begin/inject-syntax expression is similar to an immediate application of an anonymous macro, except that no macro scope is added to the resulting syntax.

Any side-effects performed by the bodys occur only once, when the begin/inject-syntax form is compiled. This is in contrast to begin-for-syntax, for example, whose contents are also evaluated whenever the enclosing module is visited.

If begin/inject-syntax is used in an expression context, the resulting syntax object must be an expression form; otherwise, the macro expander will raise a syntax error.

One use of begin/inject-syntax is conditional compilation: such as conditional definitions or module imports. For example, the following code either requires a module or defines a compatibility function depending on the current version:
> (require (for-syntax racket/base) scramble/inject-syntax)
> (begin-for-syntax
    (define (version-less-than? v) .... (version) ....))
> (begin/inject-syntax
    (if (version-less-than? "7.6") ; racket/symbol was added in 7.6
        #'(begin (define (symbol->immutable-string s)
                   (string->immutable-string (symbol->string s))))
        #'(begin (require (only-in racket/symbol symbol->immutable-string)))))
> (symbol->immutable-string 'hello)

"hello"

The following example checks whether an identifier is currently defined (useful, for example, when a new name is added to an existing module): defined:
> (require racket/string)
> (begin/inject-syntax
    (if (identifier-binding #'string-exclaim) ; Already defined? (No)
        #'(begin)
        #'(define (string-exclaim str)
            (regexp-replace* #rx"[.]" str "!"))))
> (string-exclaim "Thanks. Have a nice day.")

"Thanks! Have a nice day!"

The following example selects between different implementations (eg, safe vs unsafe or with contracts vs without contracts) based on a compile-time configuration variable:
> (require racket/require)
> (define-for-syntax use-safe-fx-ops? #t)
> (begin/inject-syntax
    (if use-safe-fx-ops?
        #'(require (prefix-in unsafe- racket/fixnum))
        #'(require (matching-identifiers-in #rx"^unsafe-fx" racket/unsafe/ops))))
> (unsafe-fx+ 1 2)

3

Keep in mind that it is customary in Racket to do library configuration at run time via ordinary variables, parameters, etc. Prefer run-time mechanisms when possible. Use begin/inject-syntax when compile-time concerns are involved, such as scoping and variations in module exports.

Another use is to perform compile-time computations of quotable data:
> (begin-for-syntax
    (define (slow-popcount n)
      (cond [(zero? n) 0]
            [else (+ (slow-popcount (quotient n 2))
                     (if (bitwise-bit-set? n 0) 1 0))])))
> (define (faster-popcount n)
    (define (byte-popcount b)
      (bytes-ref (begin/inject-syntax
                   #`(quote #,(apply bytes (for/list ([n 256]) (slow-popcount n)))))
                 b))
    (cond [(zero? n) 0]
          [else (+ (faster-popcount (arithmetic-shift n -8))
                   (byte-popcount (bitwise-bit-field n 0 8)))]))
> (faster-popcount #xFFFFFFFF)

32

Warning: Code can be run on a different platform from the one it was compiled on. Don’t use compile-time conditions to specialize code based on features that may change between compile time and run time. On Racket BC, these include the size of fixnums, the operating system, path conventions, and so on. On Racket CS, these features might not change, but beware of cross-compilation.

  top  contents    up