TauQ Query

A programmable pre-processor for generating Tauq notation dynamically.

File Extension: .tqq Pre-processor

See TQQ in Action

Watch how each directive transforms into output

users.tqq → .tqn
0/0
Input .tqq
Output .tqn
Step Ready
💭 Select an example and press Play

Drag the slider to scrub through steps, or Play to animate. Try each example to see different TQQ directives in action.

On This Page

01

Directives Overview

All TQQ directives start with ! and are processed top-to-bottom. Non-directive lines pass through unchanged.

All Directives at a Glance

Directive Purpose Output
!set KEY value Set environment variable None (side effect)
!emit command Run command, insert stdout Command's stdout
!run interp {...} Run inline script block Script's stdout
!pipe command Transform accumulated output Transformed content
!import file.tqn Include and process file File's processed content
!json file.json Convert JSON to Tauq Tauq notation
!read file.txt Read file as string Quoted string
02

Variables & Emit

Use !set to define variables and !emit to run commands. Variables are passed as environment variables to child processes.

Basic Usage

# Set variables for child processes
!set APP_NAME "MyService"
!set VERSION "2.0.0"
!set ENV "production"

# Emit command output as Tauq
!emit sh -c 'echo "build_date \"$(date +%Y-%m-%d)\""'
!emit sh -c 'echo "hostname \"$(hostname)\""'

# Static content passes through as-is
config {
    name MyService
    version "2.0.0"
}

Key point: The output of !emit must be valid Tauq syntax. The command's stdout is inserted directly into the output stream.

⚠ Important: Output Must Be Valid Tauq

Whatever your commands output will be parsed as Tauq notation. If you emit invalid syntax, the final parse will fail. Always ensure commands output properly formatted key-value pairs, arrays, or objects.

03

Inline Scripts (!run)

For complex logic, embed a script block. The script's stdout becomes part of the output.

Python Script

!run python3 {
import json
import random

# Generate random user data
users = [
    {"id": i, "score": random.randint(1, 100)}
    for i in range(5)
]
print(json.dumps(users))
}

Outputs JSON array, which Tauq can parse directly

Shell Script

!run sh {
echo "host \"$(hostname)\""
echo "user \"$(whoami)\""
echo "date \"$(date +%Y-%m-%d)\""
}

Outputs Tauq key-value pairs

Supported Interpreters

Any interpreter available on your system works with !run:

python3 node ruby sh bash perl lua
04

Data Pipelines (!pipe)

The !pipe directive is the most powerful feature. It takes all accumulated output and transforms it through a command.

Example: Sorting Data

Input (.tqq file)
# Player scores as key-value pairs
Alice 50
Bob 20
Carol 95
Dave 75

# Sort by score (2nd column), descending
!pipe sort -k 2 -nr
Output (after !pipe)
Carol 95
Dave 75
Alice 50
Bob 20

⚠ !pipe Transforms All Previous Output

When TQQ encounters !pipe, it:

  1. Takes all accumulated output so far (everything above the !pipe)
  2. Sends it as stdin to the command
  3. Replaces the accumulated output with the command's stdout

This means !pipe should be placed at the end of your data. Content after !pipe won't be piped.

Example: Filtering Data

# Filter and transform user data
!def User id name role
!use User

101 "Alice" "Dev"
102 "Bob" "Ops"
103 "Carol" "Design"

# Keep only Dev and Ops roles
!pipe grep -E "Dev|Ops"

Result: Only rows matching "Dev" or "Ops" are kept. The schema definitions are preserved in the output.

05

File Operations

Import files, convert JSON, and read raw content into your data stream.

!import - Include Tauq Files

Recursively process and insert another file: 

!import ./common/schemas.tqn
!import ./config/defaults.tqn

# Your local content here
app_name "MyService"

!json - Convert JSON to Tauq

Read a JSON file and convert it to Tauq notation on the fly: 

# users.json contains: [{"id": 1, "name": "Alice"}, ...]
!json ./data/users.json

# Becomes:
# [{ id 1 name Alice } { id 2 name Bob }]

!read - Embed Raw Text

Read a file and emit it as a quoted string (useful for templates): 

template !read ./templates/email.html

# Becomes:
# template "<html>...entire file contents...</html>"
06

Real-World Examples

Dynamic Build Configuration

Generate config with build metadata: 

# main.tqq - Production config
!set ENV "production"

# Import shared definitions
!import ./schemas.tqn
!import ./defaults.tqn

# Import JSON and convert to Tauq
!json ./data/users.json

# Emit computed values
!emit sh -c 'echo "generated_at \"$(date -Iseconds)\""'

Environment-Aware Config

Generate different configs based on environment: 

# Environment-aware configuration
!set ENV "production"

!run python3 {
import os
env = os.environ.get('ENV', 'development')

if env == 'production':
    print('database { host "db.prod.example.com" pool_size 20 }')
else:
    print('database { host "localhost" pool_size 5 }')
}

File System Inventory

Generate structured data from directory listing: 

# Generate file listing as Tauq records
!def File name size modified

!use File
!emit ls -la *.rs | tail -n +2 | awk '{print "\"" $9 "\" " $5 " \"" $6 " " $7 " " $8 "\""}'

Best Practices

✓ Do

  • Validate command output is valid Tauq
  • Use !set for repeated values
  • Keep !pipe at the end of sections
  • Test .tqq files with tauq build
  • Use !import for shared schemas

✗ Don't

  • Emit unquoted strings with spaces
  • Put content after !pipe (it won't be piped)
  • Rely on commands that aren't portable
  • Forget to escape quotes in emit/run output
  • Output invalid Tauq syntax from commands

CLI Usage

Process .tqq files with the Tauq CLI: 

# Process TQQ and output Tauq notation
tauq build input.tqq -o output.tqn

# Process TQQ and convert directly to JSON
tauq build input.tqq --json -o output.json

# Validate TQQ without writing output
tauq validate input.tqq

Ready to Build Data Pipelines?

TQQ transforms static data files into dynamic, programmable content. Combine it with Tauq's token efficiency for powerful data workflows.

Try in Playground Tauq Syntax Guide CLI Reference