#MoonJQ — jq in MoonBit

#Why MoonJQ?

• Streaming semantics - Process large JSON with constant memory via iterators
• jq-compatible - Familiar syntax and behavior for jq users
• Type-safe - Built with MoonBit's strong type system
• Well-tested - 415+ passing tests covering core jq functionality
• Documented - All code examples in this README are type-checked and tested

#Features

#Core Operations

• Identity & Access: . (identity), .foo (field), .[0] (index), .[-1] (negative index)
• Iteration: .[] (array iteration), .[2:4] (slicing), .. (recursive descent)
• Composition: | (pipe), , (comma/multiple outputs)
• Safety: ? (optional access), // (alternative/default)

#Operators

• Arithmetic: + (add/concat), - (subtract), * (multiply/repeat), / (divide), % (modulo)
• Comparison: ==, !=, <, <=, >, >=
• Logical: and, or, not
• Type coercion: Automatic for arithmetic operations

#Control Flow

• Conditionals: if ... then ... else ... end
• Error handling: try ... catch ...
• Variables: $var (read-only bindings)

#Built-in Functions

• Transformation: map(expr), select(expr), sort, reverse, flatten, flatten(n), unique
• Aggregation: add, min, max, length
• Inspection: type, keys, values
• Math: floor, sqrt
• Utility: empty, not

#Construction

• Arrays: [expr], [] (empty)
• Objects: {key: value}, {} (empty)

#Quick Start

#Installation

# Clone the repository
git clone https://github.com/moonbit-community/moobit-jq.git
cd moobit-jq

# Run tests to verify installation
moon test

#Basic Usage

///|
/// Helper function: Evaluate a jq query and return newline-separated results.
/// This mimics the command-line jq tool's behavior.
fn jq(query : String, input : String) -> String raise {
  let expr = @parser.parse(query)
  let json = @json.parse(input)
  @ast.eval(expr, json).collect().map(fn(v) { @debug.to_string(v) }).join("\n")
}

#Command Line

printf '%s' '{"name":"Moon"}' | moonx bobzhang/jq -r '.name'
moonx bobzhang/jq -n -c '{ok: true, values: [1, 2]}'
moonx bobzhang/jq -c '.items[]' data.json

moon run cmd/jq --target native -- -c '.foo' data.json
cat data.json | moon run cmd/jq --target native -- -r '.name'
moon run cmd/jq --target native -- -n -c '{ok: true}'
moon run cmd/jq --target native -- -f filter.jq data.json

moon build --target native --release cmd/jq
_build/native/release/build/cmd/jq/jq.exe -c '.items[]' data.json

• -c, --compact-output: print compact JSON.
• -r, --raw-output: print strings without JSON quotes.
• -f, --from-file FILE: read the filter from FILE.
• -n, --null-input: run the filter once with null input.
• -l, --logs: treat input as JSONL/NDJSON and skip non-JSON lines.

#Examples

#1. Filter and Project

**Explanation**: The `select(.age >= 18)` filters users 18 or older, then `{name: .name, email: .email}` constructs new objects with only those fields.

### 2. Optional Access with Defaults

Handle missing fields gracefully using `?` and `//`:

```mbt check
  inspect(
    jq(query, input),
    content=(
      #|String("(unknown)")
    ),
  )
}

#3. Transform and Aggregate

**Explanation**: `map(. * 2)` doubles each number, then `add` sums them all: `(1*2 + 2*2 + 3*2) = 12`.

### 4. Filter Logs by Level

Extract specific log messages based on severity:

```mbt check
///|
test "readme: extract error messages" {

///|
  inspect(
    jq(query, input),
    content=(
      #|String("disk full")
      #|String("timeout")
    ),
  )
}

#5. Array Slicing and Manipulation

///|
test "readme: array slicing" {
  let query = ".items[1:3] | reverse"
  let input =
    #|{ "items": [10, 20, 30, 40, 50] }
  inspect(
    jq(query, input),
    content=(
      #|Array([Number(30), Number(20)])
    ),
  )
}

#6. Recursive Descent

///|
test "readme: recursive descent" {
  let query = ".. | select(type == \"number\")"
  let input =
    #|{
    #|  "a": 1,
    #|  "b": { "c": 2, "d": { "e": 3 } }
    #|}
  inspect(
    jq(query, input),
    content=(
      #|Number(1)
      #|Number(2)
      #|Number(3)
    ),
  )
}

#Project Structure

moobit-jq/
├── moon.work              # Workspace listing all member modules
├── moon.mod               # bobzhang/moonjq library module
├── README.mbt.md          # This file (executable documentation)
├── TUTORIAL.md            # CLI tutorial
├── ast/                   # AST + streaming evaluator + integration tests
├── cmd/jq/                # bobzhang/jq native + Wasm executable module
├── cmd/jqlog/             # bobzhang/jqlog native executable module
├── cmd/<tool>/            # bobzhang/<tool> coreutils-style commands (wc, head,
│                          # tail, nl, uniq, cut, paste, comm, join, tr, sort,
│                          # base64, xxd, printf, true, false, cat, sleep), each a
│                          # standalone moonx module
├── parser/                # Parser (includes lexer)
├── tests/cram/            # Moon Cram CLI tests

#Development

#Running Tests

# Run all tests (415+ tests)
moon test

# Run specific package tests
moon test -p parser
moon test -p ast

# Type-check without running tests
moon check

# Type-check this README
moon check README.mbt.md

# Update test snapshots
moon test --update

#CLI Cram Tests

moon cram test tests/cram TUTORIAL.md

#Code Quality

# Format code
moon fmt

# Generate package interfaces
moon info

# Check for warnings
moon check --target all

#Implementation Highlights

• Streaming: Uses MoonBit's Iterator for lazy evaluation and constant memory
• Parser: Hand-written recursive-descent parser with precedence climbing
• Error handling: Leverages MoonBit's checked error system with raise
• Testing: 415+ tests using MoonBit's snapshot testing (inspect)

#Limitations & Roadmap

• Variable binding with as patterns
• reduce expressions
• sort_by, group_by
• Assignment operators (|=, =)
• String interpolation (\(expr))
• Many string/array utility functions

#License

#Acknowledgments

• Inspired by jq by Stephen Dolan
• Built with MoonBit

#Public API Reference

#Types

#Functions

#Query Methods

#License