### Build using system libraries

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/configuration.md

Example of setting an environment variable to use system-installed libjq and libonig libraries during installation.

```bash
# Build using system libraries
JQPY_USE_SYSTEM_LIBS=1 pip install jq
```

--------------------------------

### all() Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Examples demonstrating the usage of the all() method to retrieve all output elements in a list.

```python
import jq

program = jq.compile(".[]+1")
assert program.input_value([1, 2, 3]).all() == [2, 3, 4]

program2 = jq.compile(".+5")
assert program2.input_values([1, 2, 3]).all() == [6, 7, 8]

program3 = jq.compile("empty")
assert program3.input_value(None).all() == []  # No output
```

--------------------------------

### Install with System Libraries

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Command to install jq.py using system libjq instead of the bundled version.

```bash
# Install with system libjq instead of bundled
JQPY_USE_SYSTEM_LIBS=1 pip install jq
```

--------------------------------

### first() Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Examples demonstrating the usage of the first() method to retrieve the first output element.

```python
import jq

program = jq.compile(".")
assert program.input_value("hello").first() == "hello"

program2 = jq.compile("[.[]+1]")
assert program2.input_value([1, 2, 3]).first() == [2, 3, 4]

program3 = jq.compile(".[]+1")
assert program3.input_value([1, 2, 3]).first() == 2  # First of multiple outputs
```

--------------------------------

### Install jq.py using pip

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Standard installation using pip.

```sh
pip install jq
```

--------------------------------

### Program Class - input() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

An example demonstrating the usage of the input() method.

```python
import jq

program = jq.compile(".x")
result = program.input({"x": 42, "y": 10}).first()
assert result == 42

result_text = program.input(text='{"x": 42}').first()
assert result_text == 42
```

--------------------------------

### text() Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Examples demonstrating the usage of the text() method to retrieve all output serialized as JSON text.

```python
import jq

program = jq.compile(".")
assert program.input_value("42").text() == '"42"'

program2 = jq.compile(".[]")
assert program2.input_value([1, 2, 3]).text() == "1\n2\n3"

program3 = jq.compile('.')
assert program3.input_text('{"a": 1}').text() == '{"a": 1}'
```

--------------------------------

### Output Methods: Comparing Output Methods Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Provides examples for each output method (`first`, `all`, `text`, `__iter__`) to illustrate their behavior and return types.

```python
import jq

program = jq.compile(".[]")
data = [1, 2, 3]

# first() - stop early
print(program.input_value(data).first())  # 1
```

--------------------------------

### __iter__() Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Examples demonstrating the usage of the __iter__() method for lazy evaluation of output.

```python
import jq

program = jq.compile(".[]+1")
iterator = iter(program.input_value([1, 2, 3]))
assert next(iterator) == 2
assert next(iterator) == 3
assert next(iterator) == 4
assert next(iterator, None) is None  # No more values

# Using in a for loop
program2 = jq.compile(".[]")
result = []
for value in program2.input_value([10, 20, 30]):
    result.append(value)
assert result == [10, 20, 30]
```

--------------------------------

### Program Class - input_values() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

An example demonstrating the usage of the input_values() method.

```python
import jq

program = jq.compile(".+5")
result = program.input_values([1, 2, 3]).all()
assert result == [6, 7, 8]

program2 = jq.compile(".")
result2 = program2.input_values([1, 2, 3]).all()
assert result2 == [1, 2, 3]
```

--------------------------------

### Error Handling Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates how to catch ValueErrors raised by jq.py.

```python
try:
    jq.compile("invalid!").first()
except ValueError as e:
    print(f"Error: {e}")
```

--------------------------------

### Data Flow Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/ARCHITECTURE.md

A complete data flow example demonstrating the compilation of a jq program, inputting a value, and retrieving the first result.

```python
result = jq.compile(".x").input_value({"x": 42}).first()
```

--------------------------------

### Compile with arguments

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/configuration.md

Example of compiling a jq program with predefined variables.

```python
import jq

program = jq.compile("$a + $b + .", args={"a": 100, "b": 20})
result = program.input_value(3).first()
assert result == 123
```

--------------------------------

### Install dependencies on Red Hat/Fedora/CentOS

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Installs necessary development tools and libraries for building jq.py on Red Hat-based systems.

```sh
yum groupinstall "Development Tools"
yum install autoconf automake libtool python python-devel
```

--------------------------------

### Automatic resource cleanup example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/configuration.md

Illustrates automatic memory management and resource cleanup in jq.py.

```python
import jq

# Resources are automatically cleaned up
def process_data(data):
    program = jq.compile(".[] | select(. > 5)")
    return program.input_value(data).all()

result = process_data([1, 6, 3, 8, 2, 10])
# Program and all internal resources cleaned up here
```

--------------------------------

### Install dependencies on Debian/Ubuntu

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Installs necessary development tools and libraries for building jq.py on Debian-based systems.

```sh
apt-get install autoconf automake build-essential libtool python-dev
```

--------------------------------

### Basic Usage Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Demonstrates basic operations like collecting all results, serializing to text, and lazy iteration.

```python
print(program.input_value(data).all())  # [1, 2, 3]

print(program.input_value(data).text())  # "1\n2\n3"

for v in program.input_value(data):
    print(v)  # Prints: 1 \n 2 \n 3
```

--------------------------------

### all() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/convenience-functions.md

Demonstrates the usage of the `all()` function to process a list, a single value, and JSON text.

```python
import jq

assert jq.all(".[] + 1", [1, 2, 3]) == [2, 3, 4]
assert jq.all(".", value=42) == [42]
assert jq.all(".", text="1\n2\n3") == [1, 2, 3]
```

--------------------------------

### iter() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/convenience-functions.md

Shows how to use the `iter()` function to get an iterator for processing results from a jq program, including converting the iterator to a list and iterating manually.

```python
import jq

iterator = jq.iter(".[] + 1", [1, 2, 3])
assert list(iterator) == [2, 3, 4]

result = []
for value in jq.iter(".", text="10\n20\n30"):
    result.append(value)
assert result == [10, 20, 30]
```

--------------------------------

### Extract Fields

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Examples of extracting specific fields from objects.

```python
names = jq.all(".[] | .name", [
    {"name": "Alice", "age": 35},
    {"name": "Bob", "age": 28},
])
# → ["Alice", "Bob"]
```

--------------------------------

### Program Class - input_value() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

Examples demonstrating the usage of the input_value() method with various Python types.

```python
import jq

program = jq.compile(".")
assert program.input_value(None).first() == None
assert program.input_value(42).first() == 42
assert program.input_value(0.42).first() == 0.42
assert program.input_value(True).first() == True
assert program.input_value("hello").first() == "hello"
assert program.input_value([1, 2, 3]).first() == [1, 2, 3]
assert program.input_value({"a": 1}).first() == {"a": 1}
```

--------------------------------

### Catching Errors Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Provides an example of how to catch jq execution errors, which are all ValueError exceptions.

```python
import jq

try:
    result = jq.first(".x", {"x": 42})
except ValueError as e:
    print(f"jq error: {e}")
```

--------------------------------

### Convenience Function: all()

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

A single-call function to compile, input, and get all results.

```python
results = jq.all(".x", {"x": 42})           # → [42]
results = jq.all(".x", [{"x": 1}, {"x": 2}])  # → [1, 2]
```

--------------------------------

### Transform Data

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Example of transforming data structure.

```python
result = jq.first('{name: .name, years: (.age - 1960)}', {
    "name": "Alice",
    "age": 1990,
})
# → {"name": "Alice", "years": 30}
```

--------------------------------

### Nested Access

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Example of accessing nested data structures.

```python
value = jq.first(".users[0].email", {
    "users": [
        {"email": "alice@example.com"},
        {"email": "bob@example.com"},
    ]
})
# → "alice@example.com"
```

--------------------------------

### Process Array Elements

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Examples of processing elements within an array.

```python
results = jq.all(".[]", [1, 2, 3, 4, 5])   # → [1, 2, 3, 4, 5]
results = jq.all(".[] | . * 2", [1, 2, 3]) # → [2, 4, 6]
```

--------------------------------

### Install dependencies on Mac OS X

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Installs necessary development tools for building jq.py on Mac OS X using Homebrew.

```sh
brew install autoconf automake libtool
```

--------------------------------

### Slurp Mode Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/configuration.md

Demonstrates the difference between processing JSON inputs with and without slurp mode enabled.

```python
import jq

program = jq.compile(".")

# Without slurp: separate results
result1 = program.input_text("1\n2\n3").all()
assert result1 == [1, 2, 3]  # Three separate values

# With slurp: single array result
result2 = program.input_text("1\n2\n3", slurp=True).all()
assert result2 == [[1, 2, 3]]  # One array containing all values
```

--------------------------------

### Convenience Function: first()

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

A single-call function to compile, input, and get the first result.

```python
value = jq.first(".x", {"x": 42})           # → 42
```

--------------------------------

### Filter Objects

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Examples of filtering objects based on a condition.

```python
results = jq.all(".[] | select(.age > 30)", [
    {"name": "Alice", "age": 35},
    {"name": "Bob", "age": 28},
])
# → [{"name": "Alice", "age": 35}]
```

--------------------------------

### Basic compilation

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

An example of basic compilation of a jq program.

```python
import jq

program = jq.compile(".")
```

--------------------------------

### Value Lifecycle Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/ARCHITECTURE.md

Illustrates the memory management pattern for jv values, showing how values are copied when needed and freed after consumption, including error paths.

```cython
jv value = jv_parser_next(self._parser)
if jv_is_valid(value):
    return value
elif jv_invalid_has_msg(jv_copy(value)):
    error_message = jv_invalid_get_msg(value)
    message = _jq_error_to_py_string(error_message)
    jv_free(error_message)  # Free error message
    raise ValueError(u"parse error: " + message)
else:
    jv_free(value)  # Free invalid value
    raise StopIteration()
```

--------------------------------

### Basic usage example

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Compiles a jq program, supplies input, and retrieves the first output element.

```python
import jq

assert jq.compile(".+5").input_value(42).first() == 47
```

--------------------------------

### Get All Results

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Retrieves all results from the jq program execution as a list.

```python
values = program.input_value(data).all()   # Returns list
```

--------------------------------

### Execution Model: Thread Safety Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

An example showing how to use jq.py with concurrent execution using `ThreadPoolExecutor`, highlighting thread safety.

```python
import jq
from concurrent.futures import ThreadPoolExecutor

program = jq.compile(".[]+1")

def process(data):
    return list(program.input_value(data))

with ThreadPoolExecutor() as executor:
    results = list(executor.map(process, [[1,2], [3,4], [5,6]]))
```

--------------------------------

### Error Handling Usage Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Example demonstrating how errors are raised during iteration.

```python
import jq

program = jq.compile(".x")
try:
    for value in program.input_value(42):  # Can't index a number with string
        print(value)
except ValueError as e:
    print(f"Execution error: {e}")
```

--------------------------------

### Define Variables in Programs

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Example of defining and using variables within a jq program.

```python
program = jq.compile("$a + $b", args={"a": 10, "b": 20})
```

--------------------------------

### first() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/convenience-functions.md

Illustrates the `first()` function for retrieving the initial result from a jq program applied to a list, JSON text, and a single value.

```python
import jq

assert jq.first(".[] + 1", [1, 2, 3]) == 2
assert jq.first(".[] + 1", text="[1, 2, 3]") == 2
assert jq.first(".", value=42) == 42
```

--------------------------------

### Get First Result

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Retrieves the first result from the jq program execution.

```python
value = program.input_value(data).first()  # Returns single value or raises
```

--------------------------------

### Execution Model: Lazy Evaluation Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

An example illustrating lazy evaluation with the `first()` method, showing that processing can stop as soon as the first result is found.

```python
import jq

# With lazy evaluation, only processes until first match
program = jq.compile(".[] | select(. > 5)")
result = program.input_value([1, 2, 3, 6, 7, 8, 9]).first()
# Returns 6, without necessarily processing 7, 8, 9
```

--------------------------------

### Common Task: Transform an array

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

Example of transforming each element in an array.

```python
jq.all(".[] | . * 2", [1, 2, 3])
# → [2, 4, 6]
```

--------------------------------

### Getting all output elements as a list

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates using .all() to retrieve all output elements of a jq program in a list.

```python
assert jq.compile(".[]+1").input_value([1, 2, 3]).all() == [2, 3, 4]
```

--------------------------------

### Error Handling Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/INDEX.md

Demonstrates how to catch ValueError exceptions for compilation and type errors.

```python
try:
    jq.compile("invalid!")  # Syntax error
except ValueError as e:
    print(e)

try:
    jq.compile(".x").input_value(42).first()  # Type error
except ValueError as e:
    print(e)
```

--------------------------------

### Getting the first output element

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates using .first() to retrieve the first output of a jq program.

```python
import jq

assert jq.compile(".").input_value("hello").first() == "hello"
assert jq.compile("[.[]+1]").input_value([1, 2, 3]).first() == [2, 3, 4]
assert jq.compile(".[]+1").input_value([1, 2, 3]).first() == 2
```

--------------------------------

### Thread safety example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/configuration.md

Demonstrates concurrent execution of the same jq program from multiple threads using ThreadPoolExecutor.

```python
import jq
import threading

program = jq.compile(".[]+1")

def worker(data):
    return list(program.input_value(data))

# Safe to use from multiple threads
with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(worker, [[1,2,3], [4,5,6], [7,8,9], [10,11,12]]))
```

--------------------------------

### Get String Representation of Program

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Shows the string representation of a compiled jq program object.

```python
program = jq.compile(".x")
repr(program)  # "jq.compile('.x')"
```

--------------------------------

### Convenience Function: text()

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

A single-call function to compile, input, and get results as text.

```python
text = jq.text(".x", {"x": 42})             # → '"42"'
```

--------------------------------

### String Encoding Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/types.md

Confirms that all strings processed by jq.py are handled as UTF-8, allowing for correct processing of unicode characters.

```python
import jq

program = jq.compile(". + '‽'")
result = program.input_value("Dragon").first()
assert result == "Dragon‽"
```

--------------------------------

### Input Handling: Slurping Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Demonstrates the effect of the `slurp=True` option, which collects multiple JSON inputs into a single array.

```python
import jq

program = jq.compile(".")

# Without slurp: three separate values
result = program.input_text("1\n2\n3").all()
assert result == [1, 2, 3]

# With slurp: one array
result = program.input_text("1\n2\n3", slurp=True).all()
assert result == [[1, 2, 3]]
```

--------------------------------

### Array Iteration with Copying

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/ARCHITECTURE.md

Example demonstrating the need for jv_copy() during array iteration due to jq's ownership model.

```cython
for idx in range(0, jv_array_length(jv_copy(value))):
    property_value = jv_array_get(jv_copy(value), idx)
```

--------------------------------

### Both Input Arguments Provided Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates catching a ValueError when the input() method is called with both value and text arguments.

```python
import jq

program = jq.compile(".")
try:
    program.input(value=42, text="42")  # Both provided
except ValueError as e:
    print(e)  # Either the value or text argument should be set
```

--------------------------------

### With Variables

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/INDEX.md

Example of using variables within a jq program compiled by jq.py.

```python
program = jq.compile("$prefix + .name", args={"prefix": "Hello, "})
result = program.input_value({"name": "World"}).first()  # "Hello, World"
```

--------------------------------

### text() Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/convenience-functions.md

Demonstrates the `text()` function for obtaining jq program output as a newline-separated JSON string.

```python
import jq

assert jq.text(".[] + 1", [1, 2, 3]) == "2\n3\n4"
assert jq.text(".", [1, 2, 3]) == "[1, 2, 3]"
assert jq.text(".[]", text="[1, 2, 3]") == "1\n2\n3"
```

--------------------------------

### Performance Tip: Choose Right Output Method

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Guidance on selecting the appropriate output method (`first`, `iter`, `all`) based on the expected number of results and memory constraints.

```python
# Use first() if you only need one result
value = program.input_value(data).first()

# Use iter() for large result sets (memory efficient)
for value in program.input_value(data):
    process(value)

# Use all() only if you need all results in memory
values = program.input_value(data).all()
```

--------------------------------

### Usage Pattern: One-off operation

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/convenience-functions.md

Example of using a convenience function for a simple, single jq operation.

```python
import jq

result = jq.first(".title", {"title": "Hello", "body": "World"})
```

--------------------------------

### Input Handling: Method Variants Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Compares different input handling methods (`input_value`, `input_text`) for processing data from Python objects and JSON strings.

```python
import jq
import json

program = jq.compile(".title")

# From Python object
data_obj = {"title": "Article", "body": "..."}
result1 = program.input_value(data_obj).first()

# From JSON text
json_text = '{"title": "Article", "body": "..."}'
result2 = program.input_text(json_text).first()

# Both produce the same result
assert result1 == result2 == "Article"
```

--------------------------------

### Invalid Program Syntax Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates catching a ValueError when a jq program string contains invalid syntax.

```python
import jq

try:
    jq.compile("!")  # Invalid character
except ValueError as e:
    print(e)  # jq: error: syntax error, unexpected INVALID_CHARACTER...
```

--------------------------------

### Get Original Program String

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Retrieves the original jq program string from a compiled program object.

```python
program = jq.compile(".x")
print(program.program_string)  # ".x"
```

--------------------------------

### Missing Input Argument Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates catching a ValueError when the input() method is called without providing either a value or text argument.

```python
import jq

program = jq.compile(".")
try:
    program.input()  # Neither value nor text provided
except ValueError as e:
    print(e)  # Either the value or text argument should be set
```

--------------------------------

### Lazy Evaluation Usage Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Example demonstrating memory-efficient processing of large result sets using iteration.

```python
import jq

program = jq.compile('.[]')
for item in program.input_value(range(1000000)):
    process(item)  # Each item is yielded on demand
```

--------------------------------

### Execution Model: State Pooling Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Demonstrates state pooling where a compiled jq program's execution state is reused internally for subsequent calls.

```python
import jq

program = jq.compile(".")

# Both calls reuse the same compiled state internally
program.input_value([1, 2, 3]).first()
program.input_value([4, 5, 6]).first()
```

--------------------------------

### Getting all output elements as an iterator

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates using .iter() to retrieve all output elements of a jq program as an iterator.

```python
iterator = iter(jq.compile(".[]+1").input_value([1, 2, 3]))
assert next(iterator, None) == 2
assert next(iterator, None) == 3
assert next(iterator, None) == 4
assert next(iterator, None) == None
```

--------------------------------

### Choosing the Right Output Method

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Explains when to use `first()`, `iter()`, and `all()` based on memory and result requirements.

```python
import jq

program = jq.compile(".[]")

# Use first() if you only need one value
first_val = program.input_value(data).first()

# Use iter() for memory efficiency with large results
for val in program.input_value(data):
    process(val)

# Use all() only if you need all values in memory
all_vals = program.input_value(data).all()
```

--------------------------------

### Basic Program Usage

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates compiling a jq program and executing it with a JSON input value.

```python
program = jq.compile("$prefix + .name", args={"prefix": "Hello "})
result = program.input_value({"name": "World"}).first()
# → "Hello World"
```

--------------------------------

### Using the older input() method

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates the older .input() method with positional and keyword arguments.

```python
import jq

assert jq.compile(".").input("hello").first() == "hello"
assert jq.compile(".").input(text='"hello"').first() == "hello"
```

--------------------------------

### Importing jq

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

All public functions are at module level.

```python
import jq
```

--------------------------------

### Performance Tip: Reuse Compiled Programs

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Compares inefficient recompilation with efficient reuse of compiled jq programs.

```python
# Bad: recompiles every time
for item in items:
    jq.first(".x", item)

# Good: compile once
program = jq.compile(".x")
for item in items:
    program.input_value(item).first()
```

--------------------------------

### Basic Workflow: Chaining Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Shows how the compile, input, and output steps can be chained together for concise operations.

```python
import jq

results = jq.compile(".[] | select(. > 5)").input_value([1, 6, 3, 8, 2]).all()
assert results == [6, 8]
```

--------------------------------

### Convenience Functions with value= or text=

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates using 'value=' or 'text=' parameters with convenience functions.

```python
jq.first(".x", value={"x": 42})
jq.first(".x", text='{"x": 42}')
```

--------------------------------

### Infinity Handling

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates how infinity values are capped at the maximum double value.

```python
result = jq.first(". * 2", 1.7976931348623157e+308)
# → 1.7976931348623157e+308 (max double, infinity caps at this value)
```

--------------------------------

### Basic Workflow: Three-Step Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Illustrates the typical three-step process of compiling a jq program, providing input data, and retrieving results.

```python
import jq

# Step 1: Compile
program = jq.compile(".[] | select(. > 5)")

# Step 2: Input
program_with_input = program.input_value([1, 6, 3, 8, 2])

# Step 3: Output
results = program_with_input.all()
assert results == [6, 8]
```

--------------------------------

### Input from JSON Text

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Provides JSON text as input.

```python
program.input_text('{"x": 42}')       # String containing JSON
program.input_text("1\n2\n3")         # Multiple JSON values (newline-separated)
program.input_text("1\n2\n3", slurp=True)  # Read all into array
```

--------------------------------

### Reuse Compiled Program

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates efficient reuse of a compiled jq program.

```python
# Inefficient: recompiles each time
for record in records:
    jq.first(".name", record)

# Efficient: compile once
program = jq.compile(".name")
for record in records:
    program.input_value(record).first()
```

--------------------------------

### Get Results as JSON Text

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Retrieves all results formatted as newline-separated JSON text.

```python
text = program.input_value(data).text()    # Returns string (newline-separated)
```

--------------------------------

### Common Task: Filter objects

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

Example of filtering objects from an array based on a condition.

```python
jq.all(".[] | select(.age > 25)", [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 20},
])
# → [{"name": "Alice", "age": 30}]
```

--------------------------------

### Multi-line output with text()

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates how .text() handles multiple output elements, each on a new line.

```python
assert jq.compile(".[]").input_value([1, 2, 3]).text() == "1\n2\n3"
```

--------------------------------

### Common Task: Extract a field

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

Example of extracting a specific field from a JSON object.

```python
jq.first(".name", {"name": "Alice", "age": 30})
# → "Alice"
```

--------------------------------

### Compilation with Variables

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Compiles a jq program with arguments.

```python
program = jq.compile(".x + $offset", args={"offset": 10})
```

--------------------------------

### Interleaved Execution Usage Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/output-methods.md

Example showing concurrent use of multiple iterators from the same program.

```python
import jq

program = jq.compile(".[]+1")
first = iter(program.input_value([1, 2, 3]))
second = iter(program.input_value([10, 20, 30]))

assert next(first) == 2
assert next(second) == 11
assert next(first) == 3
assert next(second) == 12
```

--------------------------------

### Basic Workflow: Convenience Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Demonstrates the use of module-level convenience functions for single jq operations.

```python
import jq

results = jq.all(".[] | select(. > 5)", [1, 6, 3, 8, 2])
assert results == [6, 8]
```

--------------------------------

### Input Parse Error Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates catching a ValueError when invalid JSON is provided as text input.

```python
import jq

program = jq.compile(".")
try:
    program.input_text("!!").first()
except ValueError as e:
    print(e)  # parse error: Invalid numeric literal at EOF at line 1, column 2
```

--------------------------------

### Chaining Operations

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/INDEX.md

Shows how to chain compilation, input, and output methods for concise code.

```python
result = jq.compile(".[] | select(. > 5)").input_value([1, 6, 3, 8]).all()
```

--------------------------------

### Complex program with multiple operations

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

An example of compiling a complex jq program with multiple operations.

```python
import jq

program = jq.compile('[.[] | select(. > 5)]')
result = program.input_value([1, 6, 3, 8, 2, 10]).first()
assert result == [6, 8, 10]
```

--------------------------------

### error() Function Output Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates catching ValueErrors when the jq program calls the error() function with a value.

```python
import jq

program = jq.compile("error")
try:
    program.input_value({"x": 1}).first()
except ValueError as e:
    print(e)  # {"x": 1}

program2 = jq.compile('if . < 0 then error("negative number") else . end')
try:
    program2.input_value(-5).first()
except ValueError as e:
    print(e)  # negative number
```

--------------------------------

### Multiple Inputs

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates how multiple input values are processed as separate jq executions.

```python
# Each value becomes separate jq execution
results = jq.all(".x", [
    {"x": 1},
    {"x": 2},
    {"x": 3},
])
# → [1, 2, 3]
```

--------------------------------

### Using predefined variables with compile()

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates how to use the 'args' argument in jq.compile() to pass predefined variables into the jq program.

```python
program = jq.compile("$a + $b + .", args={"a": 100, "b": 20})
assert program.input_value(3).first() == 123
```

--------------------------------

### Input from Multiple Objects

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Provides multiple Python objects as separate inputs.

```python
program.input_values([obj1, obj2, obj3])  # Each becomes separate input
```

--------------------------------

### Basic Usage Pattern

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/INDEX.md

Illustrates the fundamental workflow of compiling a jq program, providing input, and retrieving results.

```python
import jq

# 1. Compile
program = jq.compile(".[] | select(. > 5)")

# 2. Input
with_input = program.input_value([1, 6, 3, 8])

# 3. Output
result = with_input.all()  # [6, 8]
```

--------------------------------

### Common Task: Handle errors

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

Example of handling potential errors during jq program execution using a try-except block.

```python
try:
    result = jq.first(".x", 42)
except ValueError as e:
    print(f"Error: {e}")
```

--------------------------------

### Input Methods: Multiple Objects

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

Supplies multiple Python objects as input.

```python
# Multiple objects
program.input_values([{"x": 1}, {"x": 2}])
```

--------------------------------

### Distinguishing Error Types

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Example code demonstrating how to distinguish between different types of errors raised by jq.py by inspecting the error message string.

```python
import jq

program = jq.compile(".x")
try:
    program.input_value(42).first()
except ValueError as e:
    error_str = str(e)
    if error_str.startswith("parse error"):
        print("JSON parsing failed")
    elif "Cannot index" in error_str:
        print("Type error in program")
    elif "jq:" in error_str:
        print("Compilation error")
    else:
        print("Other execution error")
```

--------------------------------

### Basic Compilation

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Compiles a jq program string into a Program object.

```python
program = jq.compile(".x")  # Returns Program
```

--------------------------------

### macOS Deployment Target

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/configuration.md

Setting the MACOSX_DEPLOYMENT_TARGET environment variable based on sysconfig for macOS compatibility.

```python
macosx_deployment_target = sysconfig.get_config_var("MACOSX_DEPLOYMENT_TARGET")
if macosx_deployment_target:
    os.environ['MACOSX_DEPLOYMENT_TARGET'] = str(macosx_deployment_target)
```

--------------------------------

### NaN Handling

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Shows how NaN values are handled, converting to None.

```python
result = jq.first("nan", None)
print(result)  # None (NaN converts to None)
```

--------------------------------

### Error State Isolation Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates that errors do not persist across separate program executions, showing a failed execution followed by a successful one.

```python
import jq

program = jq.compile(".x")

# First execution fails
try:
    program.input_value(42).first()
except ValueError:
    pass

# Second execution succeeds with proper input type
result = program.input_value({"x": 99}).first()
assert result == 99
```

--------------------------------

### Input from Python Object

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Provides a Python object as input to the compiled jq program.

```python
program.input_value({"x": 42})        # Dict, list, str, int, float, bool, None
program.input_value([1, 2, 3])        # Any JSON-compatible type
```

--------------------------------

### Program Execution Error Examples

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Demonstrates catching ValueErrors for common program execution issues like indexing a number with a string or iterating over a non-array.

```python
import jq

# Cannot index number with string
program = jq.compile(".x")
try:
    program.input_value(42).first()
except ValueError as e:
    print(e)  # Cannot index number with string "x"

# Cannot iterate over non-array
program2 = jq.compile(".[]")
try:
    program2.input_value(42).first()
except ValueError as e:
    print(e)  # Cannot iterate over number
```

--------------------------------

### String representation of a compiled jq program

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

Demonstrates how to get a string representation of a compiled jq program, useful for debugging or logging.

```python
import jq

program = jq.compile(".")
assert repr(program) == "jq.compile('.')"
```

--------------------------------

### Manual Resource Control with Iterators

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Demonstrates manual control over resource lifecycle using iterators for long-running programs.

```python
import jq

program = jq.compile(".[]")
for item in program.input_value(large_dataset):
    # Memory is released incrementally as iteration progresses
    process_item(item)
```

--------------------------------

### Validating Input

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/errors.md

Example function to safely query jq, validating input types before passing to jq to ensure better error messages and handle JSON-serializability issues.

```python
import jq
import json

def safe_jq_query(program_str, data):
    try:
        # Ensure data is valid JSON-compatible
        json.dumps(data)
        return jq.first(program_str, data)
    except TypeError as e:
        print(f"Data is not JSON-serializable: {e}")
        return None
    except ValueError as e:
        print(f"jq error: {e}")
        return None
```

--------------------------------

### Convenience Functions: First

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

A convenience function to compile, execute, and return the first result.

```python
jq.first(".x", {"x": 42})            # → 42
```

--------------------------------

### Module Imports

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/module-overview.md

Demonstrates how to import the jq module and use its basic compilation and convenience functions.

```python
import jq

# Compile a program
program = jq.compile(".[]")

# Use convenience functions
results = jq.all(".[] + 1", [1, 2, 3])

# Iterate results
for item in jq.iter(".[]", [10, 20, 30]):
    print(item)
```

--------------------------------

### Complex Data Example

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/types.md

Demonstrates how jq.py handles complex nested data structures, including strings, numbers, booleans, lists, and dictionaries, mapping them directly to Python's native types.

```python
import jq

program = jq.compile(".")
complex_data = {
    "name": "Alice",
    "age": 30,
    "active": True,
    "scores": [95, 87, 92],
    "metadata": {
        "created": "2024-01-01",
        "tags": ["admin", "developer"]
    }
}
result = program.input_value(complex_data).first()
assert result == complex_data
```

--------------------------------

### Convenience Functions

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/INDEX.md

Module-level shortcuts for common jq operations.

```python
jq.all(program, value=..., text=...)       # → list
jq.first(program, value=..., text=...)     # → Any
jq.text(program, value=..., text=...)      # → str
jq.iter(program, value=..., text=...)      # → Iterator
```

--------------------------------

### Inputting a single JSON value

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Demonstrates using .input_value() with various JSON types.

```python
import jq

assert jq.compile(".").input_value(None).first() == None
assert jq.compile(".").input_value(42).first() == 42
assert jq.compile(".").input_value(0.42).first() == 0.42
assert jq.compile(".").input_value(True).first() == True
assert jq.compile(".").input_value("hello").first() == "hello"
```

--------------------------------

### Convenience functions for jq operations

Source: https://github.com/mwilliamson/jq.py/blob/master/README.rst

Shows the usage of convenience functions like jq.first(), jq.text(), jq.all(), and jq.iter() for common jq operations.

```python
assert jq.first(".[] + 1", [1, 2, 3]) == 2
assert jq.first(".[] + 1", text="[1, 2, 3]") == 2
assert jq.text(".[] + 1", [1, 2, 3]) == "2\n3\n4"
assert jq.all(".[] + 1", [1, 2, 3]) == [2, 3, 4]
assert list(jq.iter(".[] + 1", [1, 2, 3])) == [2, 3, 4]
```

--------------------------------

### Complex Values with Arguments

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/QUICK-REFERENCE.md

Shows how to use arguments in a jq program to combine input values with default values.

```python
program = jq.compile(".items + $defaults", args={
    "defaults": ["default1", "default2"]
})
result = program.input_value({
    "items": ["item1"]
}).first()
# → ["item1", "default1", "default2"]
```

--------------------------------

### File Structure

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/README.md

The file structure of the jq.py documentation.

```bash
output/
├── README.md                          # This file
├── INDEX.md                           # Complete navigation index
├── QUICK-REFERENCE.md                 # Fast lookup for common tasks
├── ARCHITECTURE.md                    # Implementation details
├── types.md                           # Type conversions and definitions
├── errors.md                          # Error handling reference
├── configuration.md                   # Configuration and setup
└── api-reference/
    ├── module-overview.md             # Overall API structure
    ├── compile.md                     # compile() function and Program class
    ├── output-methods.md              # Output retrieval methods
    └── convenience-functions.md       # Module-level convenience functions

```

--------------------------------

### jq.compile parameters and usage

Source: https://github.com/mwilliamson/jq.py/blob/master/_autodocs/api-reference/compile.md

Demonstrates how to compile a jq program and use it with different input types and the 'slurp' option.

```python
import jq

program = jq.compile(".")
assert program.input_text("null").first() == None
assert program.input_text("42").first() == 42
assert program.input_text('"hello"').first() == "hello"
assert program.input_text("1\n2\n3").all() == [1, 2, 3]

# With slurp=True
result = program.input_text("1\n2\n3", slurp=True).first()
assert result == [1, 2, 3]
```