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
```bash
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 doci unit tests (6 tests)
basex -t test/simple.xqm # Run unit tests (7 tests)
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
```bash
@ -38,12 +38,9 @@ basex # Start interactive BaseX shell
- Use hyphens for multi-word names (e.g., `pdfbox.xqm`)
- Resource files: lowercase with hyphens (e.g., `test-data.txt`)
### Namespace Declarations
```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
- 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
- Use `if-then-else` expressions
- 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()`
- Prefer `switch() case when` over nested `if-then-else`
- Use `trace()` for debugging: `=>trace("$var")` or `=>trace("label")`
### Error Handling
```xquery
@ -125,7 +123,7 @@ declare function foo($param as xs:string) as xs:integer { ... }
### Record Field Access
- 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
```xquery
@ -211,6 +209,8 @@ docs: update module documentation
## Notes
- 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()`)
- 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