|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Textplot is a DuckDB extension that provides text-based data visualization functions. It's a C++ extension built using the DuckDB extension template and CI tools, creating ASCII/Unicode charts directly from SQL queries. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Build release version |
| 13 | +make release |
| 14 | + |
| 15 | +# Build debug version |
| 16 | +make debug |
| 17 | + |
| 18 | +# Run tests (requires build first) |
| 19 | +make test # runs against release build |
| 20 | +make test_debug # runs against debug build |
| 21 | + |
| 22 | +# Format code |
| 23 | +make format |
| 24 | + |
| 25 | +# Clean build artifacts |
| 26 | +make clean |
| 27 | +``` |
| 28 | + |
| 29 | +The build uses CMake under the hood. Build outputs go to `build/release/` or `build/debug/`. |
| 30 | + |
| 31 | +## Architecture |
| 32 | + |
| 33 | +### Extension Entry Point |
| 34 | +- `src/textplot_extension.cpp` - Registers all scalar functions with DuckDB via `LoadInternal()` |
| 35 | + |
| 36 | +### SQL Functions |
| 37 | +Each visualization function has a corresponding implementation file: |
| 38 | + |
| 39 | +| Function | Files | Purpose | |
| 40 | +|----------|-------|---------| |
| 41 | +| `tp_bar()` | `textplot_bar.cpp/.hpp` | Horizontal bar charts with thresholds and colors | |
| 42 | +| `tp_density()` | `textplot_density.cpp/.hpp` | Density plots/histograms from arrays | |
| 43 | +| `tp_sparkline()` | `textplot_sparkline.cpp/.hpp` | Compact trend lines with multiple modes | |
| 44 | +| `tp_qr()` | `textplot_qr.cpp/.hpp` | QR code generation | |
| 45 | + |
| 46 | +### Pattern |
| 47 | +Each function follows the DuckDB scalar function pattern: |
| 48 | +- `Textplot*Bind()` - Validates and binds arguments at plan time |
| 49 | +- `Textplot*()` - Executes the function at runtime |
| 50 | +- Functions accept named parameters (e.g., `width := 20`, `style := 'ascii'`) |
| 51 | + |
| 52 | +### Directory Structure |
| 53 | +- `src/` - C++ source files |
| 54 | +- `src/include/` - Header files |
| 55 | +- `test/sql/` - SQLLogicTest files (`.test` extension) |
| 56 | +- `duckdb/` - DuckDB submodule (git submodule) |
| 57 | +- `extension-ci-tools/` - Build system submodule |
| 58 | + |
| 59 | +## Testing |
| 60 | + |
| 61 | +Tests use DuckDB's SQLLogicTest format in `test/sql/`. See https://duckdb.org/dev/sqllogictest/intro.html for syntax. |
| 62 | + |
| 63 | +## Dependencies |
| 64 | + |
| 65 | +This extension uses vcpkg for dependency management. The `vcpkg.json` in the project root defines dependencies, and `extension_config.cmake` configures the extension build. |
0 commit comments