Destructuring

Unpack structs and arrays into variables with defaults, nesting, and rest captures.

Since BoxLang 1.12.x

Destructuring lets you unpack values from structs and arrays into variables in a single expression.

It works in declarations like var and in assignments.

📋 Table of Contents

• Struct destructuring

• Array destructuring

• Declarations vs assignments

• Defaults

• Nested patterns

• Rest bindings

• Scoped targets

• Common errors

🧩 Struct destructuring

Struct destructuring binds keys by name.

user = { name: "Luis", role: "admin" }
var { name, role } = user

println( name )
println( role )

You can also rename keys while destructuring.

config = { host: "localhost", port: 5432 }
var { host, port: dbPort } = config

println( host )
println( dbPort )

While renaming a struct key, you can also place it into a different scope. (You may not use the var, final, or static keywords in these cases.)

config = { host: "localhost", port: 5432 }
({ host: variables.host, port: request.dbPort } = config)

println( variables.host )
println( request.dbPort )

📚 Array destructuring

Array destructuring binds values by position.

coords = [ 10, 20 ]
var [ x, y ] = coords

println( x )
println( y )

This also works with assignments.

values = [ "BoxLang", "1.0" ]
[ productName, version ] = values

📝 Declarations vs assignments

Declarations work directly with var, final, or static.

var { name, role } = user
var [ first, second ] = values

Non-declaration struct assignments must be wrapped in parentheses.

({ name, role } = user)
({ token: authToken } = response)

Array assignments do not need the extra parentheses.

[ first, second ] = values

Use parentheses for struct assignments unless you are declaring with var, final, or static.

🎯 Defaults

Defaults let you provide a fallback when a value is not available.

Struct defaults

Struct defaults apply when a key is missing.

options = { size: "lg" }
var { size = "md", theme = "light", debug = false } = options

println( size ) // "lg"
println( theme ) // "light"
println( debug ) // false

Array defaults

Array defaults apply when a slot is missing or null.

values = [ 10, 20 ]
var [ first = 10, second = 0, third = 30 ] = values

println( first ) // 10
println( second ) // 20
println( third ) // 30

🪆 Nested patterns

You can destructure nested structs and arrays.

Nested structs

user = {
    name: "Luis",
    address: {
        city: "Houston"
    }
}

var { name, address: { city, zip = "77001" } } = user
println( name ) // Luis
println( city ) // Houston
println( zip ) // 77001

Nested arrays

points = [ [ 10, 20 ], [ 30, 40 ] ]
var [ [ x1, y1 ], [ x2, y2 ] ] = points

println( x1 ) // 10
println( y1 ) // 20
println( x2 ) // 30
println( y2 ) // 40

You can combine nesting with defaults.

options = {}
var { coords: chartCoords = { x: 0, y: 0 } } = options

println( chartCoords ) // { x: 0, y: 0 }

🧺 Rest bindings

Rest bindings capture the remaining values.

Struct rest

data = { id: 1, name: "BoxLang", stable: true }
var { id, ...rest } = data

println( rest.keyList() ) // name, stable

Array rest

numbers = [ 1, 2, 3, 4, 5 ]
var [ first, ...rest ] = numbers

println( first )
println( rest )

Array destructuring also supports middle rest.

numbers = [ 1, 2, 3, 4, 5, 6 ]
var [ first, ...middle, last ] = numbers

println( first )
println( middle )
println( last )

Short arrays still bind predictably.

numbers = [ 1 ]
var [ first, ...middle, last ] = numbers

// first  = 1
// middle = []
// last   = null

A destructuring pattern can only contain one rest binding.

🎯 Scoped targets

You can explicitly destructure into scopes by renaming the binding target.

result = { token: "abc123", userId: 42 }
({ token: request.authToken, userId: variables.currentUserId } = result)

This is useful when you want the source key and target variable to differ.

payload = { id: 100 }
({ id: arguments.recordId } = payload)

Scoped targets are not allowed in var, final, or static destructuring declarations.

⚠️ Common errors

Invalid shorthand keys

Some keys cannot use shorthand.

Use explicit renaming for quoted keys, spaced keys, or numeric keys.

source = {
    "display name": "BoxLang",
    123: "numeric"
}

var {
    "display name": displayName,
    123: numericKey
} = source

Wrong source type

Struct destructuring expects a struct-like value. Array destructuring expects an array-like value.

If a nested value does not match the pattern, BoxLang throws an error.

Multiple rest bindings

A destructuring pattern can only contain one rest binding.

Safer target syntax

Scoped targets must start with an explicit scope. Use variables.foo, request.bar, or another real scope.

✅ Summary

Destructuring gives you:

• concise assignments

• built-in renaming

• defaults

• nested extraction

• rest capture

• scoped targets when needed