From e28dd609c1f22267f7c594c72cd3525f2d2b7654 Mon Sep 17 00:00:00 2001
From: "Daniel G. Taylor" <danielgtaylor@gmail.com>
Date: Mon, 4 May 2026 23:25:12 -0700
Subject: [PATCH] Add comma-disambiguated array literals

---
 README.md   |  25 +++++++
 get.go      | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 get_test.go | 118 ++++++++++++++++++++++++++++++++
 3 files changed, 325 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 7048fe6..b18acad 100644
--- a/README.md
+++ b/README.md
@@ -401,11 +401,20 @@ The query language supports:
 - Array indexing & slicing `foo.items[1:2].name`
   - Including negative indexes `foo.items[-1].name`
 - Array filtering via [mexpr](https://github.com/danielgtaylor/mexpr) `foo.items[name.lower startsWith d]`
+- Array construction `[foo.id, foo.name]`
 - Object property selection `foo.{created, names: items.name}`
 - Recursive search `foo..name`
 - Stopping processing with a pipe `|`
 - Flattening nested arrays `[]`
 
+Square brackets are context-sensitive in queries. At the beginning of a query or
+object field value, a `[` expression constructs an array only when it contains a
+top-level comma, so `[id, name]` returns a two-item array with those query
+results. Single-element and empty array construction are not supported. A `[`
+after an existing path indexes, slices, or filters that value, as in `items[0]`,
+`items[:2]`, or `items[status == active]`. An empty bracket expression, `[]`,
+keeps its existing meaning and flattens nested arrays one level.
+
 The query syntax is recursive and looks like this:
 
 <!--
@@ -489,6 +498,22 @@ $ j <data.json -q 'users[friends contains b].{id, age}'
     "id": 2
   }
 ]
+
+# Construct a shell-friendly array of selected values
+$ j <data.json -q '[users[0].id, users[0].friends[0]]'
+[
+  1,
+  "a"
+]
+
+# Array construction also works inside object selection
+$ j <data.json -q '{vars: [users[0].id, users[0].friends[0]]}'
+{
+  "vars": [
+    1,
+    "a"
+  ]
+}
 ```
 
 ## Library Usage
diff --git a/get.go b/get.go
index 3d74431..2d67962 100644
--- a/get.go
+++ b/get.go
@@ -42,14 +42,16 @@ func GetPath(path string, input any, options GetOptions) (any, bool, Error) {
 	result := input
 	var ok bool
 	var err Error
+	firstSegment := true
 	for d.pos < uint(len(d.expression)) {
-		result, ok, err = d.getPath(result)
+		result, ok, err = d.getPath(result, firstSegment)
 		if err != nil {
 			return result, ok, err
 		}
 		if d.peek() == '|' {
 			d.next()
 		}
+		firstSegment = false
 	}
 	return result, ok, nil
 }
@@ -153,6 +155,149 @@ func (d *Document) parsePathIndex() (bool, int, int, string, Error) {
 	return false, 0, 0, value, nil
 }
 
+func (d *Document) rebaseError(base uint, err Error) Error {
+	if err == nil {
+		return nil
+	}
+	return NewError(&d.expression, base+err.Offset(), err.Length(), err.Error())
+}
+
+func (d *Document) skipQuotedRaw() Error {
+	start := d.pos - d.lastWidth
+	for {
+		r := d.next()
+		if r == '\\' {
+			if d.peek() != -1 {
+				d.next()
+			}
+			continue
+		}
+		if r == -1 {
+			return NewError(&d.expression, start, d.pos-start, "Expected quote but found EOF")
+		}
+		if r == '"' {
+			return nil
+		}
+	}
+}
+
+func (d *Document) parseArrayLiteralElement() (string, rune, uint, Error) {
+	start := d.pos
+	open := 0
+
+	for {
+		r := d.next()
+		switch r {
+		case -1:
+			return "", -1, start, NewError(&d.expression, start, d.pos-start, "expected ']' after array literal")
+		case '\\':
+			if d.peek() != -1 {
+				d.next()
+			}
+		case '"':
+			if err := d.skipQuotedRaw(); err != nil {
+				return "", -1, start, err
+			}
+		case '[', '{', '(':
+			open++
+		case ']':
+			if open == 0 {
+				end := d.pos - d.lastWidth
+				return strings.TrimSpace(d.expression[start:end]), r, start, nil
+			}
+			open--
+		case '}', ')':
+			if open == 0 {
+				return "", -1, d.pos - d.lastWidth, NewError(&d.expression, d.pos-d.lastWidth, 1, "expected ']' after array literal")
+			}
+			open--
+		case ',':
+			if open == 0 {
+				end := d.pos - d.lastWidth
+				return strings.TrimSpace(d.expression[start:end]), r, start, nil
+			}
+		}
+	}
+}
+
+func (d *Document) bracketHasTopLevelComma() (bool, Error) {
+	savedPos := d.pos
+	savedLastWidth := d.lastWidth
+	defer func() {
+		d.pos = savedPos
+		d.lastWidth = savedLastWidth
+	}()
+
+	open := 0
+	for {
+		r := d.next()
+		switch r {
+		case -1:
+			return false, nil
+		case '\\':
+			if d.peek() != -1 {
+				d.next()
+			}
+		case '"':
+			if err := d.skipQuotedRaw(); err != nil {
+				return false, err
+			}
+		case '[', '{', '(':
+			open++
+		case ']':
+			if open == 0 {
+				return false, nil
+			}
+			open--
+		case '}', ')':
+			if open > 0 {
+				open--
+			}
+		case ',':
+			if open == 0 {
+				return true, nil
+			}
+		}
+	}
+}
+
+func (d *Document) getArrayLiteral(input any) ([]any, Error) {
+	if d.options.DebugLogger != nil {
+		d.options.DebugLogger("Getting array literal")
+	}
+
+	d.skipWhitespace()
+	result := []any{}
+	for {
+		d.skipWhitespace()
+		if d.peek() == ']' {
+			return nil, d.error(1, "expected array literal element")
+		}
+
+		expr, delimiter, exprStart, err := d.parseArrayLiteralElement()
+		if err != nil {
+			return nil, err
+		}
+		if expr == "" {
+			return nil, NewError(&d.expression, exprStart, 1, "expected array literal element")
+		}
+
+		value, _, err := GetPath(expr, input, GetOptions{
+			DebugLogger: d.options.DebugLogger,
+		})
+		if err != nil {
+			return nil, d.rebaseError(exprStart, err)
+		}
+		result = append(result, value)
+
+		if delimiter == ']' {
+			break
+		}
+	}
+
+	return result, nil
+}
+
 func (d *Document) getFiltered(expr string, input any) (any, Error) {
 	ast, err := mexpr.Parse(expr, nil)
 	if err != nil {
@@ -176,7 +321,7 @@ func (d *Document) getFiltered(expr string, input any) (any, Error) {
 
 				var err Error
 				d.pos = savedPos
-				out, _, err = d.getPath(item)
+				out, _, err = d.getPath(item, false)
 				if err != nil {
 					return nil, err
 				}
@@ -421,9 +566,10 @@ func (d *Document) flatten(input any) any {
 	return nil
 }
 
-func (d *Document) getPath(input any) (any, bool, Error) {
+func (d *Document) getPath(input any, allowArrayLiteral bool) (any, bool, Error) {
 	var err Error
 	found := false
+	consumed := false
 
 outer:
 	for {
@@ -440,13 +586,37 @@ outer:
 				found = true
 				continue
 			}
+			if allowArrayLiteral && !consumed {
+				isArrayLiteral, err := d.bracketHasTopLevelComma()
+				if err != nil {
+					return nil, false, err
+				}
+				if !isArrayLiteral {
+					input, err = d.getPathIndex(input)
+					if err != nil {
+						return nil, false, err
+					}
+					found = true
+					consumed = true
+					continue
+				}
+				input, err = d.getArrayLiteral(input)
+				if err != nil {
+					return nil, false, err
+				}
+				found = true
+				consumed = true
+				continue
+			}
 			input, err = d.getPathIndex(input)
 			if err != nil {
 				return nil, false, err
 			}
 			found = true
+			consumed = true
 		case '.':
 			d.next()
+			consumed = true
 			if d.peek() == '.' {
 				// Special case: recursive descent property query
 				// i.e. find this key recursively through everything
@@ -468,12 +638,12 @@ outer:
 				if len(s) == 0 {
 					// We will get `nil`, but still need to move the read head forwards to
 					// prevent an infinite loop here.
-					d.getPath(nil)
+					d.getPath(nil, false)
 				}
 
 				for i := range s {
 					d.pos = savedPos
-					result, resultFound, err = d.getPath(s[i])
+					result, resultFound, err = d.getPath(s[i], false)
 					if err != nil {
 						return nil, false, err
 					}
@@ -500,6 +670,7 @@ outer:
 				return nil, false, err
 			}
 			found = true
+			consumed = true
 			continue
 		case ',', ']', '}':
 			d.next()
@@ -508,6 +679,7 @@ outer:
 			if err != nil {
 				return nil, false, err
 			}
+			consumed = true
 		}
 	}
 
@@ -524,6 +696,7 @@ func (d *Document) getFields(input any) (any, Error) {
 	open := 1
 	var r rune
 	d.skipWhitespace()
+	pathStart := d.pos
 	for {
 		r = d.next()
 		if r == '"' {
@@ -542,13 +715,14 @@ func (d *Document) getFields(input any) (any, Error) {
 		}
 		if r == '[' {
 			d.buf.WriteRune(r)
-			d.parseUntilNoReset(1, '|')
+			d.parseUntilNoReset(1)
 			continue
 		}
 		if r == ':' && open <= 1 {
 			key = d.buf.String()
 			d.buf.Reset()
 			d.skipWhitespace()
+			pathStart = d.pos
 			continue
 		}
 		if r == '{' {
@@ -568,7 +742,7 @@ func (d *Document) getFields(input any) (any, Error) {
 				DebugLogger: d.options.DebugLogger,
 			})
 			if err != nil {
-				return nil, err
+				return nil, d.rebaseError(pathStart, err)
 			}
 			result[key] = value
 			if r == '}' {
@@ -577,6 +751,7 @@ func (d *Document) getFields(input any) (any, Error) {
 			key = ""
 			d.buf.Reset()
 			d.skipWhitespace()
+			pathStart = d.pos
 			continue
 		}
 		d.buf.WriteRune(r)
diff --git a/get_test.go b/get_test.go
index aadbea1..884bc71 100644
--- a/get_test.go
+++ b/get_test.go
@@ -223,6 +223,72 @@ var getExamples = []struct {
 		Query: `items[@ startsWith a]|[0]`,
 		Go:    "a",
 	},
+	{
+		Name:  "Root array index still works",
+		Input: `["a", "b", "c"]`,
+		Query: `[0]`,
+		Go:    "a",
+	},
+	{
+		Name:  "Root array slice still works",
+		Input: `["a", "b", "c"]`,
+		Query: `[:1]`,
+		Go:    []any{"a", "b"},
+	},
+	{
+		Name:  "Root array filter still works",
+		Input: `["a", "b", "c"]`,
+		Query: `[@ startsWith a]`,
+		Go:    []any{"a"},
+	},
+	{
+		Name:  "Array literal multiple elements",
+		Input: `{"body": {"val1": "one", "val2": "two"}}`,
+		Query: `[body.val1, body.val2]`,
+		Go:    []any{"one", "two"},
+	},
+	{
+		Name:  "Array literal in field expression",
+		Input: `{"body": {"val1": "one", "val2": "two"}}`,
+		Query: `{foo: [body.val1, body.val2]}`,
+		Go:    map[string]any{"foo": []any{"one", "two"}},
+	},
+	{
+		Name:  "Array literal in field expression with piped element",
+		Input: `{"items": ["a", "b"], "other": "z"}`,
+		Query: `{foo: [items|[0], other]}`,
+		Go:    map[string]any{"foo": []any{"a", "z"}},
+	},
+	{
+		Name:  "Array literal with nested field expression",
+		Input: `{"body": {"val1": "one", "val2": "two"}}`,
+		Query: `[{foo: body.val1}, body.val2]`,
+		Go:    []any{map[string]any{"foo": "one"}, "two"},
+	},
+	{
+		Name:  "Array literal with nested multi-field expression",
+		Input: `{"body": {"val1": "one", "val2": "two", "val3": "three"}}`,
+		Query: `[{foo: body.val1, bar: body.val2}, body.val3]`,
+		Go:    []any{map[string]any{"foo": "one", "bar": "two"}, "three"},
+	},
+	{
+		Name:  "Array literal with quoted comma in piped element",
+		Input: `{"items": [{"id": "a,b", "name": "hit"}], "other": "z"}`,
+		Query: `[items[id == "a,b"].name|[0], other]`,
+		Go:    []any{"hit", "z"},
+	},
+	{
+		Name:  "Array literal missing element preserved",
+		Input: `{"body": {"val1": "one", "val2": "two"}}`,
+		Query: `[body.val1, body.missing, body.val2]`,
+		Go:    []any{"one", nil, "two"},
+	},
+	{
+		Name:  "Root empty brackets flatten",
+		Input: `[[1, 2], 3, [[4]]]`,
+		Query: `[]`,
+		Go:    []any{1.0, 2.0, 3.0, []any{4.0}},
+	},
 	{
 		Name:  "Array filtering escape",
 		Input: `{"items": ["a", "b", "c"]}`,
@@ -334,6 +400,30 @@ var getExamples = []struct {
 		Query: `{id`,
 		Error: "field selection requires a map",
 	},
+	{
+		Name:  "Array literal unclosed",
+		Input: `{}`,
+		Query: `[`,
+		Error: "expected ']' after index or filter",
+	},
+	{
+		Name:  "Array literal unclosed after comma",
+		Input: `{}`,
+		Query: `[body.a,`,
+		Error: "expected ']' after array literal",
+	},
+	{
+		Name:  "Array literal trailing comma",
+		Input: `{}`,
+		Query: `[body.a,]`,
+		Error: "expected array literal element",
+	},
+	{
+		Name:  "Array literal nested in field unclosed",
+		Input: `{}`,
+		Query: `{foo: [body.a}`,
+		Error: "expected ']' after index or filter",
+	},
 }
 
 func TestGet(t *testing.T) {
@@ -440,6 +530,34 @@ func TestGetPathAdditionalEdgeCases(t *testing.T) {
 			want:  nil,
 			found: true,
 		},
+		{
+			name:  "Single bracket expression is not array literal",
+			input: map[string]any{"body": map[string]any{"subject": "docs"}},
+			query: `[body.subject]`,
+			want:  nil,
+			found: true,
+		},
+		{
+			name:  "Single bracket expression in field is not array literal",
+			input: map[string]any{"body": map[string]any{"subject": "docs"}},
+			query: `{foo: [body.subject]}`,
+			want:  map[string]any{"foo": nil},
+			found: true,
+		},
+		{
+			name: "Root filter function comma is not array literal",
+			input: []any{
+				map[string]any{
+					"id": 1,
+					"keep": func(a, b string) bool {
+						return a == "a" && b == "b"
+					},
+				},
+			},
+			query: `[keep("a", "b")].id`,
+			want:  []any{1},
+			found: true,
+		},
 		{
 			name:  "Filter with nested path on scalar input is empty",
 			input: map[string]any{"items": []any{"a", "b"}},