### Debug Compiler Passes

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Tools for tracing runtime execution, echoing macro expansions, and tracing individual transformers.

```scheme
;; Trace entire pass execution
(trace-define-pass remove-one-armed-if : Lsrc (e) -> L1 ()
  (Expr : Expr (e) -> Expr ()
    [(if ,[e0] ,[e1]) `(if ,e0 ,e1 (void))]))

;; When run:
;; |(remove-one-armed-if (if x y))
;; |(if x y (void))

;; Echo macro expansion for debugging
(echo-define-pass remove-one-armed-if : Lsrc (e) -> L1 ()
  (Expr : Expr (e) -> Expr ()
    [(if ,[e0] ,[e1]) `(if ,e0 ,e1 (void))]))
;; Prints expanded code at compile time

;; Trace individual transformer
(define-pass my-pass : L1 (e) -> L2 ()
  (trace Expr : Expr (e) -> Expr ()  ; 'trace' keyword
    [(if ,[e0] ,[e1] ,[e2]) `(if ,e0 ,e1 ,e2)]))
```

--------------------------------

### Construct language terms with with-output-language

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Enables construction of language terms using quasiquote syntax outside of pass definitions by rebinding quasiquote and in-context.

```scheme
;; Construct language terms in helper functions
(with-output-language (L10 Expr)
  (define make-boxes
    (lambda (t*)
      (map (lambda (t) `(primcall box ,t)) t*)))

  (define build-let
    (lambda (x* e* body)
      (if (null? x*)
          body
          `(let ([,x* ,e*] ...) ,body)))))

;; Use in-context to switch nonterminals
(with-output-language L10
  (define make-lambda-expr
    (lambda (x* body)
      (in-context LambdaExpr `(lambda (,x* ...) ,body)))))
```

--------------------------------

### trace-define-pass and echo-define-pass - Debugging Passes

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Tools for debugging Nanopass passes. `trace-define-pass` traces input/output at runtime, and `echo-define-pass` shows macro expansion at compile time. Individual transformers can be traced with the `trace` keyword.

```APIDOC
## trace-define-pass and echo-define-pass - Debugging Passes

### Description
Tools for debugging Nanopass passes. `trace-define-pass` traces input/output at runtime, and `echo-define-pass` shows macro expansion at compile time. Individual transformers can be traced with the `trace` keyword.

### Method
Form

### Endpoint
N/A

### Parameters
None

### Request Example
```scheme
;; Trace entire pass execution
(trace-define-pass remove-one-armed-if : Lsrc (e) -> L1 ()
  (Expr : Expr (e) -> Expr ()
    [(if ,[e0] ,[e1]) `(if ,e0 ,e1 (void))]))

;; Echo macro expansion for debugging
(echo-define-pass remove-one-armed-if : Lsrc (e) -> L1 ()
  (Expr : Expr (e) -> Expr ()
    [(if ,[e0] ,[e1]) `(if ,e0 ,e1 (void))]))

;; Trace individual transformer
(define-pass my-pass : L1 (e) -> L2 ()
  (trace Expr : Expr (e) -> Expr ()  ; 'trace' keyword
    [(if ,[e0] ,[e1] ,[e2]) `(if ,e0 ,e1 ,e2)]))
```

### Response
#### Success Response (Runtime/Compile-time Output)
- `trace-define-pass` outputs runtime input/output.
- `echo-define-pass` prints expanded code at compile time.

### Response Example
```scheme
;; When run with trace-define-pass:
;; |(remove-one-armed-if (if x y))
;; |(if x y (void))

;; echo-define-pass prints expanded code at compile time
```
```

--------------------------------

### diff-languages - Show Differences Between Languages

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Computes and displays the extension form needed to transform one language into another, useful for understanding language evolution.

```APIDOC
## diff-languages - Show Differences Between Languages

### Description
Computes and displays the extension form needed to transform one language into another, useful for understanding language evolution.

### Method
Form

### Endpoint
N/A

### Parameters
None

### Request Example
```scheme
;; Show what changed from Lsrc to L1
(diff-languages Lsrc L1)
```

### Response
#### Success Response (S-expression)
- Returns the S-expression representing the differences and extensions.

### Response Example
```scheme
;; =>
'(define-language L1
   (extends Lsrc)
   (entry Expr)
   (terminals
     (- (primitive (pr)))
     (+ (void+primitive (pr))))
   (Expr (e body)
     (- (if e0 e1))))
```
```

--------------------------------

### with-output-language

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Enables construction of language terms using quasiquote syntax outside of a pass definition.

```APIDOC
## with-output-language

### Description
The `with-output-language` form enables construction of language terms using quasiquote syntax outside of a pass definition. It rebinds `quasiquote` and `in-context` for the specified language.

### Parameters
- **language-spec** (list) - Required - The language and optional nonterminal context.
- **body** (expressions) - Required - The code block where language terms are constructed.
```

--------------------------------

### Create S-expression parsers with define-parser

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Converts S-expressions into record-based language representations. Grammars must be unambiguous to be parsed correctly.

```scheme
;; Create parser for language Lsrc
(define-parser parse-Lsrc Lsrc)

;; Usage: parse S-expression into language form
(parse-Lsrc '(lambda (x) (+ x 1)))
;; => Returns record-based representation

;; Ambiguous grammars cannot be parsed - must restructure:
;; BAD: Multiple set! forms with same structure
(define-language Lunparsable
  (Statement (stmt)
    (set! x0 int64)
    (set! x0 x1)
    (set! x0 (binop x1 int32))
    (set! x0 (binop x1 x2))))

;; GOOD: Restructured to be unambiguous
(define-language Lparsable
  (Statement (stmt) (set! x rhs))
  (Rhs (rhs) x int64 (binop x arg))
  (Argument (arg) x int32))

(define-parser parse-Lparsable Lparsable)
```

--------------------------------

### prune-language and define-pruned-language - Remove Dead Productions

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Analyze a language from its entry point and remove unreachable nonterminals and terminals, producing a minimal language definition.

```APIDOC
## prune-language and define-pruned-language - Remove Dead Productions

### Description
Analyze a language from its entry point and remove unreachable nonterminals and terminals, producing a minimal language definition.

### Method
Form

### Endpoint
N/A

### Parameters
None

### Request Example
```scheme
;; Show pruned language as S-expression
(prune-language L15)

;; Define a new pruned language
(define-pruned-language L15 L15-minimal)
```

### Response
#### Success Response (Language Definition)
- `prune-language` returns the pruned language as an S-expression.
- `define-pruned-language` creates a new language with dead code removed.

### Response Example
```scheme
;; => Returns language with only reachable productions
;; Creates L15-minimal with dead code removed
```
```

--------------------------------

### Define Optional Fields

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Uses the maybe form to allow production fields to contain a value or #f, with ? suffix for pattern matching.

```scheme
(define-language Lopt
  (terminals
    (label (l))
    (constant (c)))
  (Expr (e body)
    (quote c)
    ;; Call with optional label and optional expression
    (call (maybe l) (maybe e) e* ...)))

;; In patterns, use ? suffix for maybe fields
(define-pass process-calls : Lopt (e) -> Lopt ()
  (Expr : Expr (e) -> Expr ()
    [(call ,l? ,e? ,[e*] ...)  ; l? and e? may be #f
     (if l?
         `(call ,l? ,e? ,e* ...)
         `(call #f #f ,e* ...))]))
```

--------------------------------

### Compute Language Differences

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Displays the extension form required to transform one language into another.

```scheme
;; Show what changed from Lsrc to L1
(diff-languages Lsrc L1)
;; =>
'(define-language L1
   (extends Lsrc)
   (entry Expr)
   (terminals
     (- (primitive (pr)))
     (+ (void+primitive (pr))))
   (Expr (e body)
     (- (if e0 e1))))
```

--------------------------------

### Define language transformation passes with define-pass

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Defines transformations between languages using pattern matching, catamorphisms, and optional guard clauses.

```scheme
;; Simple pass: remove one-armed if by adding explicit void
(define-pass remove-one-armed-if : Lsrc (e) -> L1 ()
  (Expr : Expr (e) -> Expr ()
    [(if ,[e0] ,[e1]) `(if ,e0 ,e1 (void))]))
    ;; [,e0] = catamorphism (auto-recurse), `(if ...) = output template
    ;; All other Expr productions autogenerated!

;; Pass with extra arguments and return values
(define-pass uncover-free : L10 (e) -> L11 ()
  (Expr : Expr (e) -> Expr (free*)  ; Returns transformed expr AND free vars
    [(quote ,c) (values `(quote ,c) '())]
    [,x (values x (list x))]        ; Variable is free
    [(let ([,x* ,[e* free**]] ...) ,[e free*])
     (values `(let ([,x* ,e*] ...) ,e)
       (apply union (difference free* x*) free**))]
    [(if ,[e0 free0*] ,[e1 free1*] ,[e2 free2*])
     (values `(if ,e0 ,e1 ,e2) (union free0* free1* free2*))])
  (let-values ([(e free*) (Expr e)])
    (unless (null? free*) (error who "unbound variables" free*))
    e))

;; Pass with definitions clause and extra transformer arguments
(define-pass expose-closure-prims : L12 (e) -> L13 ()
  (Expr : Expr (e [cp #f] [free* '()]) -> Expr ()  ; cp, free* with defaults
    (definitions
      (define handle-closure-ref
        (lambda (x cp free*)
          (let loop ([free* free*] [i 0])
            (cond
              [(null? free*) x]
              [(eq? x (car free*)) `(primcall closure-ref ,cp (quote ,i))]
              [else (loop (cdr free*) (+ i 1))])))))
    [,x (handle-closure-ref x cp free*)]
    [(,[e] ,[e*] ...) `((primcall closure-code ,e) ,e* ...)]))
```

--------------------------------

### define-parser

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Creates a parser that converts S-expressions into the record-based language representation.

```APIDOC
## define-parser

### Description
Creates a parser that converts S-expressions into the record-based language representation. The grammar must be unambiguous.

### Parameters
- **parser-name** (symbol) - Required - The name of the resulting parser function.
- **language** (language) - Required - The language definition to parse against.
```

--------------------------------

### Match language terms with nanopass-case

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Provides pattern matching on language terms outside of full pass definitions, suitable for predicates and inspections.

```scheme
;; Define a predicate using nanopass-case
(define lambda?
  (lambda (e)
    (nanopass-case (L8 Expr) e
      [(lambda (,x* ...) ,abody) #t]
      [else #f])))

;; Complex matching with guards
(define simple?
  (lambda (e bound* assigned*)
    (nanopass-case (L8 Expr) e
      [(quote ,c) #t]
      [,x (not (or (memq x bound*) (memq x assigned*)))]
      [(primcall ,pr ,e* ...)
       (and (effect-free-prim? pr) (for-all simple? e*))]
      [(if ,e0 ,e1 ,e2)
       (and (simple? e0) (simple? e1) (simple? e2))]
      [else #f])))
```

--------------------------------

### maybe - Optional Fields in Productions

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Allows a production field to contain either a value of the specified type or `#f` (representing bottom/unspecified).

```APIDOC
## maybe - Optional Fields in Productions

### Description
Allows a production field to contain either a value of the specified type or `#f` (representing bottom/unspecified).

### Method
Form

### Endpoint
N/A

### Parameters
None

### Request Example
```scheme
(define-language Lopt
  (terminals
    (label (l))
    (constant (c)))
  (Expr (e body)
    (quote c)
    ;; Call with optional label and optional expression
    (call (maybe l) (maybe e) e* ...)))

;; In patterns, use ? suffix for maybe fields
(define-pass process-calls : Lopt (e) -> Lopt ()
  (Expr : Expr (e) -> Expr ()
    [(call ,l? ,e? ,[e*] ...)  ; l? and e? may be #f
     (if l?
         `(call ,l? ,e? ,e* ...)
         `(call #f #f ,e* ...))]))
```

### Response
#### Success Response (Language Definition/Pass)
- Defines a language with optional fields.
- A pass can process these optional fields using the `?` suffix in patterns.

### Response Example
```scheme
;; The 'call' production in Lopt can have optional 'l' and 'e' fields.
;; The 'process-calls' pass demonstrates how to handle these optional fields.
```
```

--------------------------------

### extends - Define Language Extensions

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Creates a new language by adding or removing elements from a base language, facilitating incremental grammar definition.

```APIDOC
## extends - Define Language Extensions

### Description
The `extends` clause creates a new language by adding or removing terminals and productions from a base language, avoiding verbose rewriting of entire grammars. Use `(+)` to add and `(-)` to remove elements.

### Method
(define-language ... (extends <base-language>))

### Endpoint
N/A (Scheme macro)

### Parameters
#### Scheme Syntax
```scheme
(define-language <new-language-name>
  (extends <base-language-name>)
  (terminals
    (+ <new-terminal> ...)
    (- <removed-terminal> ...))
  (<nonterminal-name>
    (+ <added-production> ...)
    (- <removed-production> ...)))
```

### Request Example
```scheme
;; L1 extends Lsrc: removes one-armed if, changes primitive terminal
(define-language L1
  (extends Lsrc)
  (terminals
    (- (primitive (pr)))           ; Remove old primitive terminal
    (+ (void+primitive (pr))))     ; Add new terminal with void
  (Expr (e body)
    (- (if e0 e1))))               ; Remove one-armed if production

;; L15 adds a new nonterminal by adding all its productions
(define-language L15
  (extends L14)
  (Expr (e body)
    (- x (quote c) (label l))      ; Remove productions
    (+ se                          ; Add: SimpleExpr as Expr
       (primcall pr se* ...)
       (se se* ...)))
  (SimpleExpr (se)                 ; New nonterminal
    (+ x (label l) (quote c))))    ; Define its productions
```

### Response
N/A (Macro expansion)
```

--------------------------------

### define-pass

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Defines a transformation pass between an input and output language, supporting pattern matching, catamorphisms, and guard clauses.

```APIDOC
## define-pass

### Description
Defines a transformation from an input language to an output language. It supports pattern matching on input forms, catamorphisms for automatic recursion, guard clauses, and autogeneration of boilerplate clauses for unchanged productions.

### Parameters
- **name** (symbol) - Required - The name of the pass.
- **input-language** (language) - Required - The source language definition.
- **output-language** (language) - Required - The target language definition.
- **body** (expressions) - Required - The transformation logic including nonterminal definitions and clauses.
```

--------------------------------

### nanopass-case

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Provides pattern matching on language terms outside of a full pass definition.

```APIDOC
## nanopass-case

### Description
The `nanopass-case` form provides pattern matching on language terms outside of a full pass definition, useful for predicates and simple inspections.

### Parameters
- **language-spec** (list) - Required - The language and nonterminal to match against.
- **expression** (any) - Required - The language term to inspect.
- **clauses** (list) - Required - Pattern matching clauses.
```

--------------------------------

### language->s-expression - Display Full Language Definition

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Returns the complete S-expression representation of a language, expanding any extensions. Useful for debugging extended languages.

```APIDOC
## language->s-expression - Display Full Language Definition

### Description
Returns the complete S-expression representation of a language, expanding any extensions. Useful for debugging extended languages.

### Method
Form

### Endpoint
N/A

### Parameters
None

### Request Example
```scheme
;; Display the full L1 language (extends Lsrc)
(language->s-expression L1)
```

### Response
#### Success Response (S-expression)
- Returns the S-expression representation of the language.

### Response Example
```scheme
;; =>
'(define-language L1
   (entry Expr)
   (terminals
     (void+primitive (pr))
     (symbol (x))
     (constant (c))
     (datum (d)))
   (Expr (e body)
     pr x c
     (quote d)
     (if e0 e1)  ; Note: no one-armed if
     (or e* ...)
     (and e* ...)
     (not e)
     (begin e* ... e)
     (lambda (x* ...) body* ... body)
     (let ([x* e*] ...) body* ... body)
     (letrec ([x* e*] ...) body* ... body)
     (set! x e)
     (e e* ...)))
```
```

--------------------------------

### Define an intermediate language grammar

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Specifies terminals, nonterminals, and productions for a language. Requires defining predicates for custom terminals like primitive? and constant?.

```scheme
;; Define a source language for a Scheme subset
(define-language Lsrc
  (terminals
    (symbol (x))           ; Variables, uses symbol? predicate
    (primitive (pr))       ; Primitives like +, -, cons
    (constant (c))         ; Booleans, null, integers
    (datum (d)))           ; Quoted data
  (entry Expr)             ; Starting nonterminal
  (Expr (e body)           ; Nonterminal with meta-variables e, body
    pr                     ; Stand-alone primitive
    x                      ; Stand-alone variable
    c                      ; Stand-alone constant
    (quote d)              ; Quoted datum
    (if e0 e1)             ; One-armed if
    (if e0 e1 e2)          ; Two-armed if
    (or e* ...)            ; Or with zero or more exprs
    (and e* ...)           ; And with zero or more exprs
    (not e)                ; Negation
    (begin e* ... e)       ; Sequence
    (lambda (x* ...) body* ... body)  ; Lambda
    (let ([x* e*] ...) body* ... body)
    (letrec ([x* e*] ...) body* ... body)
    (set! x e)             ; Assignment
    (e e* ...)))           ; Application (implicit production)

;; Terminal predicates must be defined
(define primitive?
  (lambda (x)
    (memq x '(+ - * / cons car cdr null? pair? eq?))))

(define constant?
  (lambda (x)
    (or (boolean? x) (null? x) (and (integer? x) (exact? x)))))
```

--------------------------------

### Display Language S-expression

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Returns the full S-expression representation of a language, including expanded extensions.

```scheme
;; Display the full L1 language (extends Lsrc)
(language->s-expression L1)
;; =>
'(define-language L1
   (entry Expr)
   (terminals
     (void+primitive (pr))
     (symbol (x))
     (constant (c))
     (datum (d)))
   (Expr (e body)
     pr x c
     (quote d)
     (if e0 e1 e2)  ; Note: no one-armed if
     (or e* ...)
     (and e* ...)
     (not e)
     (begin e* ... e)
     (lambda (x* ...) body* ... body)
     (let ([x* e*] ...) body* ... body)
     (letrec ([x* e*] ...) body* ... body)
     (set! x e)
     (e e* ...)))
```

--------------------------------

### Extend an existing language grammar

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Uses the extends clause to modify a base language by adding or removing terminals and productions. Use (+) to add and (-) to remove elements.

```scheme
;; L1 extends Lsrc: removes one-armed if, changes primitive terminal
(define-language L1
  (extends Lsrc)
  (terminals
    (- (primitive (pr)))           ; Remove old primitive terminal
    (+ (void+primitive (pr))))     ; Add new terminal with void
  (Expr (e body)
    (- (if e0 e1))))               ; Remove one-armed if production

;; L15 adds a new nonterminal by adding all its productions
(define-language L15
  (extends L14)
  (Expr (e body)
    (- x (quote c) (label l))      ; Remove productions
    (+ se                          ; Add: SimpleExpr as Expr
       (primcall pr se* ...)
       (se se* ...)))
  (SimpleExpr (se)                 ; New nonterminal
    (+ x (label l) (quote c))))    ; Define its productions
```

--------------------------------

### define-language - Define Intermediate Language Grammar

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Specifies an intermediate language grammar including terminals, nonterminals, productions, and an entry point. It generates record definitions, an unparser, and a meta-parser.

```APIDOC
## define-language - Define Intermediate Language Grammar

### Description
The `define-language` form specifies an intermediate language grammar consisting of terminals (with predicates), nonterminals, productions, and an entry point. It creates record definitions for language terms, an unparser to convert records back to S-expressions, and a meta-parser for use in pass definitions.

### Method
(define-language)

### Endpoint
N/A (Scheme macro)

### Parameters
#### Scheme Syntax
```scheme
(define-language <language-name>
  (terminals
    (<terminal-name> <predicate-variable>)
    ...)
  (entry <nonterminal-name>)
  (<nonterminal-name> (<meta-variable>*)
    <production-rule>
    ...))
```

### Request Example
```scheme
;; Define a source language for a Scheme subset
(define-language Lsrc
  (terminals
    (symbol (x))           ; Variables, uses symbol? predicate
    (primitive (pr))       ; Primitives like +, -, cons
    (constant (c))         ; Booleans, null, integers
    (datum (d)))           ; Quoted data
  (entry Expr)             ; Starting nonterminal
  (Expr (e body)           ; Nonterminal with meta-variables e, body
    pr                     ; Stand-alone primitive
    x                      ; Stand-alone variable
    c                      ; Stand-alone constant
    (quote d)              ; Quoted datum
    (if e0 e1)             ; One-armed if
    (if e0 e1 e2)          ; Two-armed if
    (or e* ...)            ; Or with zero or more exprs
    (and e* ...)           ; And with zero or more exprs
    (not e)                ; Negation
    (begin e* ... e)       ; Sequence
    (lambda (x* ...) body* ... body)  ; Lambda
    (let ([x* e*] ...) body* ... body)
    (letrec ([x* e*] ...) body* ... body)
    (set! x e)             ; Assignment
    (e e* ...)))

;; Terminal predicates must be defined
(define primitive?
  (lambda (x)
    (memq x '(+ - * / cons car cdr null? pair? eq?))))

(define constant?
  (lambda (x)
    (or (boolean? x) (null? x) (and (integer? x) (exact? x)))))
```

### Response
N/A (Macro expansion)
```

--------------------------------

### Prune Unreachable Productions

Source: https://context7.com/nanopass/nanopass-framework-scheme/llms.txt

Removes unreachable nonterminals and terminals from a language definition.

```scheme
;; Show pruned language as S-expression
(prune-language L15)
;; => Returns language with only reachable productions

;; Define a new pruned language
(define-pruned-language L15 L15-minimal)
;; Creates L15-minimal with dead code removed
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.