scope

Lightweight library for tracking scope and identifier usage in untyped Nim macros. Builds live scope stack during AST traversal, recording definitions, usages, and shadowing with rich metadata.

Features

• Complete scope tracking - Procedures, blocks, loops, conditionals, exception handling
• Variable shadowing detection - Multi-level shadowing analysis with scope depths
• Cross-scope access patterns - Track variables used from outer scopes
• Rich metadata - Line numbers, scope depths, usage classifications
• Custom traversal callbacks - Hook into AST walking process
• Persistent storage - No data loss during scope transitions
• Zero dependencies - Pure Nim, works with any macro

Quick Start

import scope

macro analyzeScope(body: untyped): untyped =
  let scope = newScope()
  scope.walk(body)
  
  # Check for variable shadowing
  for name, info in scope:
    if scope.isShadowed(name):
      echo name, " is shadowed"
  
  result = body

analyzeScope:
  var x = 1
  if true:
    var x = 2  # Detected as shadow

API Reference

Core Types

type
  UsageKind = enum
    ukDef     # Variable definition
    ukUse     # Variable usage
    ukShadow  # Shadow definition

  UsageInfo = object
    node*: NimNode
    kind*: UsageKind
    scopeDepth*: int
    line*, col*: int

  IdentInfo = object
    name*: string
    all*: seq[UsageInfo]  # All usages
    def*: UsageInfo       # Definition info

Main API

# Create tracker
proc newScope*(): ScopeTracker

# Walk AST
proc walk*(st: ScopeTracker, root: NimNode)
proc walk*(st: ScopeTracker, root: NimNode, cb: WalkCallback)

# Query identifiers
proc info*(st: ScopeTracker, name: string): IdentInfo
proc info*(st: ScopeTracker, ident: NimNode): IdentInfo
proc allTracked*(st: ScopeTracker): seq[IdentInfo]

# Scope queries
proc currentScopeSymbols*(st: ScopeTracker): seq[string]
proc currentScopeLevel*(st: ScopeTracker): int
proc inCurrentScope*(st: ScopeTracker, name: string): bool
proc scopeOf*(st: ScopeTracker, name: string): int

# Analysis helpers
proc isDefined*(st: ScopeTracker, name: string): bool
proc isShadowed*(st: ScopeTracker, name: string): bool
proc usagesOf*(st: ScopeTracker, name: string): seq[UsageInfo]
proc shadowedIdents*(st: ScopeTracker): seq[IdentInfo]

# Iterators
iterator items*(st: ScopeTracker): IdentInfo
iterator pairs*(st: ScopeTracker): (string, IdentInfo)
iterator itemsInScope*(st: ScopeTracker, level: int): IdentInfo

Usage Patterns

Variable Shadowing Detection

macro checkShadowing(body: untyped): untyped =
  let scope = newScope()
  scope.walk(body)
  
  for shadowedVar in scope.shadowedIdents():
    echo "Warning: ", shadowedVar.name, " is shadowed"
  
  result = body

Cross-Scope Analysis

macro findCrossScope(body: untyped): untyped =
  let scope = newScope()
  scope.walk(body)
  
  for name, info in scope:
    let usageDepths = info.all.mapIt(it.scopeDepth)
    if usageDepths.len > 1:
      echo name, " accessed across scopes: ", usageDepths

Macro Hygiene

macro hygieneCheck(newVarName: static[string], body: untyped): untyped =
  let scope = newScope()
  scope.walk(body)
  
  if scope.isDefined(newVarName):
    error("Variable name conflict: " & newVarName)
  
  # Safe to generate code with newVarName

Custom Callbacks

proc scopeCallback(n: NimNode, st: ScopeTracker) =
  if n.kind == nnkProcDef:
    echo "Entering procedure at depth ", st.currentScopeLevel()

scope.walk(body, scopeCallback)

Supported Constructs

Procedures: proc, func, method, converter, iterator, template, macro
Control Flow: if/elif/else, case/of, for, while, block
Exception Handling: try/except/finally
Variable Declarations: var, let, const
Parameters: All procedure parameter types

Use Cases

• Hygiene-aware macro generation - Avoid variable name conflicts
• Static analysis tools - Detect unused variables, scope violations
• Code transformation - Safely rename/refactor variables
• Template engines - Generate code with proper scoping
• DSL implementation - Build domain-specific languages
• Debugging macros - Understand variable lifetime and visibility

Examples

See examples/example.nim for comprehensive demonstrations including:

• Multi-level variable shadowing
• Cross-scope variable access tracking
• Procedure parameter analysis
• Nested scope depth visualization
• Macro hygiene checking

Requirements

• Nim 1.6+ (uses modern macro APIs)
• No external dependencies

License

MIT