Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions ChangeLog
Original file line number Diff line number Diff line change
@@ -1,6 +1,19 @@
ChangeLog
=======

### 1.1.2 - Apr 2026

Features:
* `&field` candidate completion inside function arguments: when a function template
inserts a `&field` placeholder (e.g. `sort_by(@, &field)`), field candidates from
the base array are automatically shown so the user can Tab-cycle or type to filter
* Placeholder text is removed immediately on entering candidate mode; cursor is placed
between `&` and `)` for clean inline editing
* `Ctrl+W` now treats `&field)` as one deletion unit and stops at `&`, preserving it
(e.g. `max_by(@, &base_stat)` → `max_by(@, &`)
* Suppressed misleading green hint in `&partial` mode (hint appeared after `)`)
* Cursor stays between `&` and `)` while Tab-cycling field candidates

### 1.1.1 - Mar 28 2026

Features:
Expand Down
27 changes: 26 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -315,9 +315,27 @@ When a function candidate is confirmed, the arguments are automatically filled i
| `join` | `join('', @)` | inside `''` (separator) |
| `sort_by` | `sort_by(@, &field)` | on `field` placeholder |
| `max_by` | `max_by(@, &field)` | on `field` placeholder |
| `min_by` | `min_by(@, &field)` | on `field` placeholder |
| `map` | `map(&expr, @)` | on `expr` placeholder |

Placeholder text is shown in blue. Typing any character replaces the entire placeholder.
Placeholder text is shown in cyan. Typing any character replaces the entire placeholder.

#### `&field` Candidate Completion

For functions that take a `&field` argument (`sort_by`, `max_by`, `min_by`, `map`),
jid automatically shows the available field names from the base array as soon as the
`&field` template is inserted:

```
.stats | sort_by(@, &field) → field names shown: base_stat effort stat
.stats | sort_by(@, &b → filtered: base_stat
.stats | sort_by(@, &base_stat) → confirmed; expression evaluates normally
```

- **Tab / Shift+Tab** cycles through field candidates; cursor stays between `&` and `)`
- **Typing** filters candidates by the partial name after `&`
- **Enter** or **Tab** (when only one candidate) confirms the selection
- **Ctrl+W** deletes the field name but keeps `&` (e.g. `&base_stat)` → `&`)

### Wildcard Projection Navigation

Expand All @@ -341,3 +359,10 @@ After a wildcard expression like `.game_indices[*]`, jid shows the field names o
.[3] | to_array(@) →(Ctrl+W)→ .[3] |
.[3] | →(Ctrl+W)→ .[3]
```

Inside a function call, the `&field` argument is treated as one unit and `&` is preserved:

```
.stats | max_by(@, &base_stat) →(Ctrl+W)→ .stats | max_by(@, &
.stats | max_by(@, & →(Ctrl+W)→ .stats |
```
61 changes: 45 additions & 16 deletions cmd/jid/jid.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import (
"github.com/simeji/jid"
)

const VERSION = "1.1.1"
const VERSION = "1.1.2"

func main() {
content := os.Stdin
Expand Down Expand Up @@ -82,49 +82,78 @@ $ jid < file.json
============ With a JSON filter mode =============

TAB / CTRL-I
Show available items and choice them
Show available candidates and cycle forward.
In JMESPath pipe mode, shows field or function candidates.
Confirms immediately when only one candidate matches.

Shift-TAB
Cycle candidates backward.
Outside candidate mode: decrement the last array index.

Enter
Exit jid and print the current result.
If a candidate list is open, confirm the selected candidate instead.
Set exit_on_enter = false in config.toml to disable accidental exit.

CTRL-W
Delete from the cursor to the start of the word
Delete one segment backward (JMESPath-aware).
Removes the last field/index/function one step at a time.
Inside &field) argument: deletes the field name but keeps '&'.

CTRL-U
Delete whole query
Delete whole query.

CTRL-X
Toggle function description display (visible when function candidates are shown).

CTRL-F / Right Arrow
Move cursor a character to the right
Move cursor a character to the right.

CTRL-B / Left Arrow
Move cursor a character to the left
Move cursor a character to the left.

CTRL-A
To the first character of the 'Filter'
Move cursor to the first character of the Filter.

CTRL-E
To the end of the 'Filter'
Move cursor to the end of the Filter.

CTRL-J
Scroll json buffer 1 line downwards
Scroll json buffer 1 line downwards.

CTRL-K
Scroll json buffer 1 line upwards
Scroll json buffer 1 line upwards.

CTRL-G
Scroll json buffer to bottom
Scroll json buffer to bottom.

CTRL-T
Scroll json buffer to top
Scroll json buffer to top.

CTRL-N
Scroll json buffer 'Page Down'
Scroll json buffer Page Down.

CTRL-P
Scroll json buffer 'Page Up'
Scroll json buffer Page Up.

CTRL-L
Change view mode whole json or keys (only object)
Toggle view mode: full JSON or keys-only (objects only).

ESC
Hide a candidate box
Hide the candidate list.

Up Arrow
Navigate to the previous query in history.

Down Arrow
Navigate to the next query in history.

============ JMESPath examples =============

.users[*].name wildcard: extract name from every user
. | keys(@) pipe + function: list root keys
.users | sort_by(@, &name) sort array of objects by field
.users | length(@) pipe + function: count elements

`
}
6 changes: 3 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ header:
actions:
- label: "GitHub"
url: "https://github.com/simeji/jid"
- label: "Download v1.1.1"
url: "https://github.com/simeji/jid/releases/tag/v1.1.1"
- label: "Download v1.1.2"
url: "https://github.com/simeji/jid/releases/tag/v1.1.2"
excerpt: >
Interactively drill down JSON in your terminal.
JMESPath support, query history, key highlighting, and more.
Expand Down Expand Up @@ -138,5 +138,5 @@ scroll_up = "ctrl+k"

<div style="text-align:center; margin-top: 2em;">
<a href="https://github.com/simeji/jid" class="btn btn--primary btn--large">View on GitHub</a>
<a href="https://github.com/simeji/jid/releases/tag/v1.1.1" class="btn btn--inverse btn--large">Download v1.1.1</a>
<a href="https://github.com/simeji/jid/releases/tag/v1.1.2" class="btn btn--inverse btn--large">Download v1.1.2</a>
</div>
74 changes: 67 additions & 7 deletions engine.go
Original file line number Diff line number Diff line change
Expand Up @@ -327,6 +327,15 @@ func (e *Engine) setCandidateData() {
if isFuncCandidates || isJMESPathFieldCandidates {
// Auto-enter candidate mode so the list appears without a Tab press.
e.candidatemode = true
// When entering &field candidate mode, remove the placeholder text from the
// query string (e.g. "field" in "&field)") so the user sees just "&".
if isJMESPathFieldCandidates && strings.Contains(qs0, "&") && e.placeholderStart >= 0 && e.placeholderLen > 0 {
for i := 0; i < e.placeholderLen; i++ {
_ = e.query.Delete(e.placeholderStart)
}
e.queryCursorIdx = e.placeholderStart
e.clearPlaceholder()
}
if e.candidateidx >= l {
e.candidateidx = 0
}
Expand Down Expand Up @@ -371,7 +380,16 @@ func (e *Engine) confirmCandidate() {
qs := e.query.StringGet()
if pipeIdx := strings.LastIndex(qs, "|"); pipeIdx >= 0 {
suffix := strings.TrimLeft(qs[pipeIdx+1:], " ")
if strings.Contains(suffix, "(") {
if _, ok := ampFieldPartial(suffix); ok {
// Active &partial editing inside a function argument (e.g. "sort_by(@, &na)").
// Replace everything after the last "&" with the selected field name.
// Use ampFieldPartial to guard against matching an already-completed
// expression that happens to contain "&" (e.g. "max_by(@, &age).field").
absAmpIdx := strings.LastIndex(qs, "&")
_ = e.query.StringSet(qs[:absAmpIdx+1] + selected + ")")
e.queryCursorIdx = e.query.Length()
e.clearPlaceholder()
} else if strings.Contains(suffix, "(") {
// The pipe suffix is a complete expression (e.g. "to_array(@)[0]").
// Append .field to the full query rather than stripping back to the base.
// If query already ends with "." don't add another.
Expand Down Expand Up @@ -458,17 +476,35 @@ func (e *Engine) toggleKeymode() {
}
// removeLastJMESPathSegment removes the last navigation segment from a
// JMESPath expression suffix, working backwards:
// "to_array(@)[0].id" → "to_array(@)[0]" (remove .field)
// "to_array(@)[0]" → "to_array(@)" (remove [index])
// "to_array(@)" → "" (remove function call)
// "to_array(@)[0].id" → "to_array(@)[0]" (remove .field)
// "to_array(@)[0]" → "to_array(@)" (remove [index])
// "to_array(@)" → "" (remove function call)
// "max_by(@, &base_stat)" → "max_by(@, " (remove &field) argument)
func removeLastJMESPathSegment(expr string) string {
if expr == "" {
return ""
}
parenDepth := 0
bracketDepth := 0
inString := false
stringChar := byte(0)
for i := len(expr) - 1; i >= 0; i-- {
switch expr[i] {
c := expr[i]
// Track string literal boundaries (scan right-to-left: opening quote = exit,
// closing quote = enter). Single quotes only — JMESPath uses '' for literals.
if c == '\'' || c == '"' {
if inString && c == stringChar {
inString = false
} else if !inString {
inString = true
stringChar = c
}
continue
}
if inString {
continue
}
switch c {
case ')':
parenDepth++
case '(':
Expand All @@ -484,6 +520,13 @@ func removeLastJMESPathSegment(expr string) string {
if parenDepth == 0 && bracketDepth == 0 {
return expr[:i]
}
case '&':
// Inside a function call (not inside a string literal):
// "&field)" is one deletion unit; keep the "&".
// e.g. "max_by(@, &base_stat)" → "max_by(@, &"
if parenDepth > 0 && bracketDepth == 0 {
return expr[:i+1]
Comment on lines +523 to +528

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Ignore ampersands inside literals during Ctrl+W

The new & deletion rule triggers for any ampersand inside parentheses, including string literals, so Ctrl+W on expressions such as . | contains(@, 'a&b') truncates to . | contains(@, 'a& instead of deleting one logical segment. This introduces malformed intermediate queries for normal string searches containing &.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 402e7ef. Added string-literal tracking to removeLastJMESPathSegment: when scanning right-to-left, single/double quote characters toggle an inString flag, and the & case is skipped while inside a literal. A test covers this: removeLastJMESPathSegment("contains(@, 'a&b')") now returns "" (full expression removed as one segment) instead of truncating at the &.

Comment on lines +523 to +528

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Treat '&' inside literals as normal text in Ctrl+W logic

Backward-segment deletion now treats any & inside parentheses as an amp-field boundary, including ampersands in string literals, so Ctrl+W can truncate valid expressions into malformed ones (for example, . | contains(@, 'a&b') can be cut back to an unterminated literal). This impacts normal typing flows whenever string arguments contain &. Fresh evidence: removeLastJMESPathSegment returns at any & with parenDepth > 0, without checking whether that character is inside a quoted literal.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@codex address that feedback

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
}
}
return "" // entire expression is one segment
Expand Down Expand Up @@ -572,7 +615,7 @@ func (e *Engine) tabAction() {
return
}
e.candidateidx = (e.candidateidx + 1) % len(e.candidates)
e.queryCursorIdx = e.query.Length()
e.queryCursorIdx = e.ampFieldCursorPos(qs)
e.candidateScrollNeeded = true
return
}
Expand Down Expand Up @@ -631,12 +674,29 @@ func (e *Engine) shiftTabAction() {
} else {
e.candidateidx--
}
e.queryCursorIdx = e.query.Length()
e.queryCursorIdx = e.ampFieldCursorPos(e.query.StringGet())
e.candidateScrollNeeded = true
return
}
e.changeArrayIndex(-1)
}
// ampFieldCursorPos returns the cursor position to use while cycling candidates
// in &partial mode. When the query contains "&" inside a function call (e.g.
// "max_by(@, &)"), the cursor should sit right after "&" (between "&" and ")"),
// not at the end of the query. Otherwise returns query.Length().
func (e *Engine) ampFieldCursorPos(qs string) int {
if pipeIdx := strings.LastIndex(qs, "|"); pipeIdx >= 0 {
suffix := strings.TrimLeft(qs[pipeIdx+1:], " ")
if _, ok := ampFieldPartial(suffix); ok {
ampIdx := strings.LastIndex(qs, "&")
if ampIdx >= 0 {
return len([]rune(qs[:ampIdx+1]))
}
}
}
return e.query.Length()
}

func (e *Engine) setQuitRequested() {
e.quitRequested = true
}
Expand Down
Loading
Loading