quodatum/doci
1
0
Fork 0
Code Issues Projects Activity Actions

docs: update AGENTS.md with current codebase patterns

Browse source 
- Fix test count (7 tests, not 6)
- Add guidance for running single tests
- Simplify namespace declaration example
- Enhance code examples with backticks and specifics
- Improve tracing/debugging documentation
This commit is contained in:
opencode 2026-03-15 22:27:58 +00:00
parent b8448523d0
commit d6ed25b0e5
1 changed files with 9 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
AGENTS.md
View file

@ -5,10 +5,10 @@
### Running Tests ### Running Tests
```bash ```bash
basex -t /path/to/test/file.xqm # Run all tests in a file basex -t /path/to/test/file.xqm # Run all tests in a file
basex -t /path/to/test/dir # Run all tests in directory basex -t test/simple.xqm # Run unit tests (7 tests)
basex -t test/simple.xqm # Run doci unit tests (6 tests)
basex -t test/smoke.xq # Run smoke tests (no assertions) basex -t test/smoke.xq # Run smoke tests (no assertions)
``` ```
**Running Single Tests**: BaseX runs all tests in a file. To run a single test, comment out others or use `%unit:test` selectively. Test names: `test:from-file`, `test:from-string1`, `test:from-string2`, `test:update-start`, `test:update-end`, `test:update-lines`, `test:lines`.
### Query Execution ### Query Execution
```bash ```bash
@ -38,12 +38,9 @@ basex # Start interactive BaseX shell
- Use hyphens for multi-word names (e.g., `pdfbox.xqm`) - Use hyphens for multi-word names (e.g., `pdfbox.xqm`)
- Resource files: lowercase with hyphens (e.g., `test-data.txt`) - Resource files: lowercase with hyphens (e.g., `test-data.txt`)
### Namespace Declarations
```xquery ```xquery
module namespace module-name = 'urn:project:namespace'; module namespace doci = 'urn:quodatum:text:doci';
``` ```
- Use reverse domain name notation for consistency
- Match namespace URI to file path structure
### Records & Types ### Records & Types
- Use `declare record` for structured data - Use `declare record` for structured data
@ -87,9 +84,10 @@ import module namespace mod = 'namespace' at "path/to/file.xqm";
- Prefer `let` over `for` for single items - Prefer `let` over `for` for single items
- Use `if-then-else` expressions - Use `if-then-else` expressions
- Leverage XQuery 3.1+ functions: `tokenize()`, `string-join()` - Leverage XQuery 3.1+ functions: `tokenize()`, `string-join()`
- Use `!` for mapping single items - Use `!` for mapping single items (e.g., `$lines!doci:build(.)`)
- Use `*` for mapping sequences: `expr!func()` - Use `*` for mapping sequences: `expr!func()`
- Prefer `switch() case when` over nested `if-then-else` - Prefer `switch() case when` over nested `if-then-else`
- Use `trace()` for debugging: `=>trace("$var")` or `=>trace("label")`
### Error Handling ### Error Handling
```xquery ```xquery
@ -125,7 +123,7 @@ declare function foo($param as xs:string) as xs:integer { ... }
### Record Field Access ### Record Field Access
- Use `?field` syntax for record field access (e.g., `$doci?lines`) - Use `?field` syntax for record field access (e.g., `$doci?lines`)
- Optional fields marked with `?` after field name in record declaration - Optional fields marked with `?` after field name in record declaration in declaration, but `?field` syntax for access
### Documentation ### Documentation
```xquery ```xquery
@ -211,6 +209,8 @@ docs: update module documentation
## Notes ## Notes
- BaseX 12.2 supports XQuery 3.1 syntax - BaseX 12.2 supports XQuery 3.1 syntax
- The `fn:do-until` function may not be available; use `hof:until` as alternative - Use `hof:until` instead of `fn:do-until` if available
- Java interoperability available through `Q{namespace}` syntax (e.g., `Q{java:java.io.File}new()`) - Java interoperability available through `Q{namespace}` syntax (e.g., `Q{java:java.io.File}new()`)
- For PDF processing (`pdfbox` module), external JAR dependencies required - For PDF processing (`pdfbox` module), external JAR dependencies required
- The `doci:separator()` function auto-detects line separators (`\n`, `\r\n`, `\r`)
- Use `=>trace()` liberally during debugging to inspect intermediate values