Re: Improving support for user-defined annotations

+1 !

Le 17/12/2020 à 09:26, Reece Dunn a écrit :
> With XQuery 3.0 annotations were extended to support any EQName, and 
> allow optional values. These have been used by vendors to implement 
> REST capabilities (via the EXQuery RESTXQ specification) and unit test 
> capabilities (such as in BaseX's test module).
>
> However, support for user-defined annotations is lacking. This means 
> that external projects implementing the RESTXQ module (such as the rqx 
> library for MarkLogic) need to rely on vendor extensions and vendor 
> APIs to implement that functionality to take advantage of annotations. 
> A similar case applies to unit test libraries like XRay which use 
> annotations to define which functions are unit tests.
>
> The general approach for this (some of which have been raised as 
> xpath-ng proposals) can be broken down into 3 parts:
>
> 1. Annotation Item Types -- similar to a FunctionTest, making 
> annotations a concrete part of the XQuery type system.
>
> 2. Annotation Declarations -- similar to function declarations, that 
> define the form an annotation can take; that is, the annotation name 
> along with the supported parameter names and types.
>
> 3. Functions and Operators support -- allowing annotations to be 
> queried, along with the annotation argument values, and possibly other 
> operations.
>
> I'm wondering if it makes sense for annotation declarations to be 
> function declarations. This would avoid the need for having a separate 
> parallel system to functions (including in-scope definitions).
>
> For example, you could create a simple test framework as follows:
>
>     declare %annotation function test:case() {};
>     declare %annotation function test:values($values as item() ...) {};
>
>     declare function test:run-tests() {
>         for $f in in-scope-functions()
>         let $a as annotation()? :=
>             annotation-for-function($f, test:case#0)
>         let $with-values as annotation(xs:string ...)* :=
>             annotation-for-function($f, test:values#*) (: any arity :)
>         where exists($a)
>         return if (exists($with-values))
>             then
>                 for $value in $with-values
>                 return $f(annotation-arguments($value))
>             else $f()
>     };
>
> and have it work on any XQuery 4.0 capable processor.
>
> The other use case for this is for tooling, so things like xqDoc can 
> provide documentation for annotations and annotation parameters, as 
> well as accessing the annotation information in a vendor-agnostic 
> manner to generate the function signatures in the documentation. 
> Editors/IDEs could also provide features like validation, 
> auto-complete, and parameter signature tooltips for user-defined 
> annotations.
>
> Kind regards,
> Reece

Received on Thursday, 17 December 2020 08:34:41 UTC