Re: Improving support for user-defined annotations

On Thu, 17 Dec 2020 at 08:38, Michael Kay <mike@saxonica.com> wrote:

> Would you like to draft a concrete proposal indicating textual changes to
> the spec?
>

Sure. I can give it a go.


> Michael Kay
> Saxonica
>
> On 17 Dec 2020, at 08:26, Reece Dunn <msclrhd@googlemail.com> wrote:
>
> 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
>
>
>