sparql

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

SPARQL.ex is an implementation of the SPARQL standards for Elixir that executes queries against RDF.ex data structures. It provides a complete query engine with support for SPARQL 1.0 and partial SPARQL 1.1 features.

## Development Commands

```bash
# Setup and build
mix deps.get                      # Install dependencies
mix compile                       # Compile project (includes leex/yecc for parser)

# Testing
mix test                          # Run full test suite
mix test path/to/test.exs        # Run specific test file
mix test path/to/test.exs:42     # Run test at specific line
mix test --cover                  # Run tests with coverage
mix coveralls.html                # Generate HTML coverage report

# Code quality
mix dialyzer                      # Run static analysis
mix credo                         # Check code style and quality

# Documentation
mix docs                          # Generate documentation
```

## Architecture and Structure

The codebase follows a pipeline architecture for query processing:
1. **Parsing**: SPARQL string → AST (via leex/yecc in `src/`)
2. **Translation**: AST → Algebra expressions (`lib/sparql/algebra/`)
3. **Execution**: Algebra evaluation against RDF data (`lib/sparql/processor.ex`)
4. **Results**: Format results (JSON/XML/CSV/TSV in `lib/sparql/query/result/`)

### Key Modules

- `SPARQL.Query` - Query structure and creation
- `SPARQL.Processor` - Main execution engine
- `SPARQL.Algebra.Expression` - Core protocol for expression evaluation
- `SPARQL.Language.Decoder` - SPARQL string parsing
- `SPARQL.Functions.Builtins` - Standard SPARQL functions
- `SPARQL.ExtensionFunction` - Custom function registration system

### Protocol-Based Design

The system uses the `SPARQL.Algebra.Expression` protocol for evaluating different query expressions. Each algebra operation (BGP, Filter, Optional, etc.) implements this protocol.

## Testing Approach

- Test files mirror the structure in `lib/` under `test/sparql/`
- Use `SPARQL.Test.Case` as the base test case (provides common imports/aliases)
- W3C compliance tests are in `test/acceptance/w3c-test-suites/`
- Prefer `==` assertions with expected result on the right side
- Use pattern matching only when exact comparison is impractical

## Extension Functions

Custom SPARQL functions can be registered via the `SPARQL.ExtensionFunction` system:

```elixir
defmodule MyFunction do
  use SPARQL.ExtensionFunction,
    name: "http://example.org/myFunction",
    arguments: 2
  
  def evaluate([arg1, arg2], _context), do: # implementation
end
```

## Important Implementation Notes

- The lexer (`src/sparql_lexer.xrl`) and parser (`src/sparql_parser.yrl`) are generated via leex/yecc
- Query execution is currently single-threaded (parallelization is on the roadmap)
- Named graph support (FROM/GRAPH) is not yet implemented
- Solution modifiers (ORDER BY, LIMIT, OFFSET) are not yet supported
- The codebase requires Elixir 1.14+ and OTP 24+

## Current Feature Gaps

Not yet implemented in the query engine:
- Named graphs (FROM/GRAPH clauses)
- ORDER BY, LIMIT, OFFSET
- Aggregates (GROUP BY, HAVING)
- ASK and DESCRIBE query forms
- Subqueries and property paths
- SPARQL Update operations
- NOT EXISTS negation
- VALUES inline data

## Code Conventions

- Keep TODO comments unless resolved
- Documentation should be minimal, focusing on "why" rather than "what"
- Use hyphens for lists in documentation
- Include doctests in "## Examples" sections when setup is straightforward
- Test assertions: prefer `==` with expected on right side
- Use pattern matching in tests only when exact comparison is impractical