Difference between revisions of "Inspection Module"

From BaseX Documentation
Jump to navigation Jump to search
(18 intermediate revisions by the same user not shown)
Line 11: Line 11:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:functions||function(*)*}}<br/>{{Func|inspect:functions|$uri as xs:string|function(*)*}}
 
|{{Func|inspect:functions||function(*)*}}<br/>{{Func|inspect:functions|$uri as xs:string|function(*)*}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns function items for all user-defined functions (both public and private) that are known in the current query context. If a {{Code|$uri}} is specified, the addressed module will be compiled, and its functions will be added to the query context and returned to the user. A relative URI will be resolved against the static base URI of the query.
+
|Returns function items for all user-defined functions (both public and private) that are known in the current query context. If a {{Code|$uri}} is specified, the specified resource will be retrieved as string and compiled, and its functions will be added to the query context and returned to the user. A relative URI will be resolved against the static base URI of the query.
|-
+
|- valign="top"
 
|'''Examples'''
 
|'''Examples'''
 
|Invokes the declared functions and returns their values:<br/>
 
|Invokes the declared functions and returns their values:<br/>
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
declare %private function local:one() { 12 };
 
declare %private function local:one() { 12 };
 
declare %private function local:two() { 34 };
 
declare %private function local:two() { 34 };
 
for $f in inspect:functions() return $f()
 
for $f in inspect:functions() return $f()
</pre>
+
</syntaxhighlight>
 
Compiles all functions in {{Code|code.xqm}} and invokes the function named {{Code|run}}:
 
Compiles all functions in {{Code|code.xqm}} and invokes the function named {{Code|run}}:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
let $uri := 'code.xqm'
 
let $uri := 'code.xqm'
let $name := "run"
+
let $name := 'run'
 
for $f in inspect:functions($uri)
 
for $f in inspect:functions($uri)
 
where local-name-from-QName(function-name($f)) = $name
 
where local-name-from-QName(function-name($f)) = $name
 
return $f()
 
return $f()
</pre>
+
</syntaxhighlight>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|parse|#Errors}} Error while parsing a module.
 
|}
 
|}
  
Line 38: Line 41:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:function-annotations|$function as function(*)?|map(xs:QName, xs:anyAtomicType*)}}<br/>
 
|{{Func|inspect:function-annotations|$function as function(*)?|map(xs:QName, xs:anyAtomicType*)}}<br/>
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the annotations of the specified {{Code|$function}} in a map.
 
|Returns the annotations of the specified {{Code|$function}} in a map.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Returns an empty map:
 
* Returns an empty map:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
inspect:function-annotations(true#0)
 
inspect:function-annotations(true#0)
</pre>
+
</syntaxhighlight>
 
* Returns a map with a single key <code><nowiki>Q{http://www.w3.org/2012/xquery}private</nowiki></code> and an empty sequence as value:
 
* Returns a map with a single key <code><nowiki>Q{http://www.w3.org/2012/xquery}private</nowiki></code> and an empty sequence as value:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
declare %private function local:f() { 'well hidden' };
 
declare %private function local:f() { 'well hidden' };
 
inspect:function-annotations(local:f#0)
 
inspect:function-annotations(local:f#0)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 61: Line 64:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:static-context|$function as function(*)?, $name as xs:string|item()*}}<br/>
 
|{{Func|inspect:static-context|$function as function(*)?, $name as xs:string|item()*}}<br/>
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns a component of the [https://www.w3.org/TR/xquery-31/#dt-static-context static context] of a {{Code|$function}} with the specified {{Code|$name}}. If no function is supplied, the current static context is considered.<br/>The following components can be requested:
 
|Returns a component of the [https://www.w3.org/TR/xquery-31/#dt-static-context static context] of a {{Code|$function}} with the specified {{Code|$name}}. If no function is supplied, the current static context is considered.<br/>The following components can be requested:
Line 78: Line 81:
 
* {{Code|copy-namespaces}}: Copy-namespaces mode ({{Code|inherit}}/{{Code|no-inherit}}, {{Code|preserve}}/{{Code|no-preserve}})
 
* {{Code|copy-namespaces}}: Copy-namespaces mode ({{Code|inherit}}/{{Code|no-inherit}}, {{Code|preserve}}/{{Code|no-preserve}})
 
* {{Code|decimal-formats}}: Nested map with all statically known decimal formats
 
* {{Code|decimal-formats}}: Nested map with all statically known decimal formats
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Returns the static base URI (same as {{Code|static-base-uri()}}):
 
* Returns the static base URI (same as {{Code|static-base-uri()}}):
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
inspect:static-context((), 'base-uri')
 
inspect:static-context((), 'base-uri')
</pre>
+
</syntaxhighlight>
 
* Returns a map with all namespaces that are statically known in the module of the specified function:
 
* Returns a map with all namespaces that are statically known in the module of the specified function:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
import module namespace data = 'data.xqm';
 
import module namespace data = 'data.xqm';
 
inspect:static-context(data:get#1, 'namespaces')
 
inspect:static-context(data:get#1, 'namespaces')
</pre>
+
</syntaxhighlight>
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|unknown|#Errors}} The specified component does not exist.
 
|{{Error|unknown|#Errors}} The specified component does not exist.
Line 96: Line 99:
  
 
=Documentation=
 
=Documentation=
 +
 +
==inspect:type==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signatures'''
 +
|{{Func|inspect:type|$value as item()*|xs:string}}<br/>{{Func|inspect:type|$value as item()*, $options as map(*)|xs:string}}
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns a string representation of the type of a {{Code|$value}}:
 +
* The string includes the occurrence indicator.
 +
* The type of functions and nodes may be stricter than the returned type.
 +
* For type checking, the standard expressions {{Code|typeswitch}} and {{Code|instance of}} should be used instead.
 +
The following {{Code|$options}} are available:
 +
* {{Code|item}}: If enabled, only the item type is returned and the occurrence indicator is omitted. The default is {{Code|false()}}.
 +
* {{Code|mode}}: If {{Code|value}} is specified, the assigned type of the result value is returned. With {{Code|expression}} the type of the input expression is returned (please note that the original expression may already have been rewritten at compile-time). With {{Code|computed}}, the exact value is computed at runtime, based on the expression and the result value. The default is {{Code|computed}}.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code>inspect:type((<a/>, <a/>))</code> yields <code>element(a)+</code>
 +
* <code>inspect:type(map { 'a': (1, 2)[. = 1] })</code> yields <code>map(xs:string, xs:integer)</code>
 +
* <code>inspect:type(1 to 100, map { 'item': true() })</code> yields <code>xs:integer</code>
 +
|}
  
 
==inspect:function==
 
==inspect:function==
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:function|$function as function(*)|element(function)}}
 
|{{Func|inspect:function|$function as function(*)|element(function)}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Inspects the specified {{Code|$function}} and returns an element that describes its structure. The output of this function is similar to eXist-db’s [http://exist-db.org/exist/apps/fundocs/view.html?uri=http://exist-db.org/xquery/inspection&location=java:org.exist.xquery.functions.inspect.InspectionModule inspect:inspect-function] function.
+
|Inspects the specified {{Code|$function}} and returns an element that describes its structure. The output of this function is similar to eXist-db’s [https://exist-db.org/exist/apps/fundocs/view.html?uri=http://exist-db.org/xquery/inspection&location=java:org.exist.xquery.functions.inspect.InspectionModule inspect:inspect-function] function.
|-
+
|- valign="top"
 
|'''Examples'''
 
|'''Examples'''
 
|The query {{Code|inspect:function(count#1)}} yields:
 
|The query {{Code|inspect:function(count#1)}} yields:
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<function name="count" uri="http://www.w3.org/2005/xpath-functions" external="false">
 
<function name="count" uri="http://www.w3.org/2005/xpath-functions" external="false">
 
   <argument type="item()" occurrence="*"/>
 
   <argument type="item()" occurrence="*"/>
 
   <return type="xs:integer"/>
 
   <return type="xs:integer"/>
 
</function>
 
</function>
</pre>
+
</syntaxhighlight>
 
The function…
 
The function…
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
(:~
 
(:~
 
  : This function simply returns the specified integer.
 
  : This function simply returns the specified integer.
Line 125: Line 151:
 
   $number
 
   $number
 
};
 
};
</pre>
+
</syntaxhighlight>
 
…is represented by {{Code|inspect:function(local:same#1)}} as…
 
…is represented by {{Code|inspect:function(local:same#1)}} as…
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<function name="local:same" uri="http://www.w3.org/2005/xquery-local-functions" external="false">
 
<function name="local:same" uri="http://www.w3.org/2005/xquery-local-functions" external="false">
 
   <argument type="xs:integer" name="number">number to return</argument>
 
   <argument type="xs:integer" name="number">number to return</argument>
Line 134: Line 160:
 
   <return type="xs:integer">specified number</return>
 
   <return type="xs:integer">specified number</return>
 
</function>
 
</function>
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 140: Line 166:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:context||element(context)}}
 
|{{Func|inspect:context||element(context)}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Generates an element that describes all variables and functions in the current query context.
 
|Generates an element that describes all variables and functions in the current query context.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|Evaluate all user-defined functions with zero arguments in the query context:<br/>
 
|Evaluate all user-defined functions with zero arguments in the query context:<br/>
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
inspect:context()/function ! function-lookup(QName(@uri, @name), 0) ! .()
 
inspect:context()/function ! function-lookup(QName(@uri, @name), 0) ! .()
</pre>
+
</syntaxhighlight>
 
Return the names of all private functions in the current context:
 
Return the names of all private functions in the current context:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
for $f in inspect:context()/function
 
for $f in inspect:context()/function
 
where $f/annotation/@name = 'private'
 
where $f/annotation/@name = 'private'
 
return $f/@name/string()
 
return $f/@name/string()
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 163: Line 189:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:module|$uri as xs:string|element(module)}}
 
|{{Func|inspect:module|$uri as xs:string|element(module)}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Retrieves the resource located at the specified {{Code|$uri}}, parses it as XQuery module, and generates an element that describes the module's structure. A relative URI will be resolved against the static base URI of the query.
 
|Retrieves the resource located at the specified {{Code|$uri}}, parses it as XQuery module, and generates an element that describes the module's structure. A relative URI will be resolved against the static base URI of the query.
|-
+
|- valign="top"
| '''Errors'''
 
|{{Error|FODC0002|XQuery Errors#Functions Errors}} the addressed resource cannot be retrieved.
 
|-
 
 
|'''Examples'''
 
|'''Examples'''
 
|An example is [[#Examples|shown below]].
 
|An example is [[#Examples|shown below]].
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|parse|#Errors}} Error while parsing a module.
 
|}
 
|}
  
Line 180: Line 206:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
 
|{{Func|inspect:xqdoc|$uri as xs:string|element(xqdoc:xqdoc)}}
 
|{{Func|inspect:xqdoc|$uri as xs:string|element(xqdoc:xqdoc)}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Retrieves the resource located at the specified {{Code|$uri}}, parses it as XQuery module, and generates an xqDoc element. A relative URI will be resolved against the static base URI of the query.<br/>[http://xqdoc.org xqDoc] provides a simple vendor-neutral solution for generating documentation from XQuery modules. The documentation conventions have been inspired by the JavaDoc standard. Documentation comments begin with {{Code|(:~}} and end with {{Code|:)}}, and tags start with {{Code|@}}. xqDoc comments can be specified for main and library modules and variable and function declarations.<br/>
+
|Retrieves the resource located at the specified {{Code|$uri}}, parses it as XQuery module, and generates an xqDoc element. A relative URI will be resolved against the static base URI of the query.<br/>[http://xqdoc.org/ xqDoc] provides a simple vendor-neutral solution for generating documentation from XQuery modules. The documentation conventions have been inspired by the JavaDoc standard. Documentation comments begin with {{Code|(:~}} and end with {{Code|:)}}, and tags start with {{Code|@}}. xqDoc comments can be specified for main and library modules and variable and function declarations.<br/>
We have slightly extended the xqDoc conventions to do justice to more recent versions of XQuery (Schema: [http://files.basex.org/etc/xqdoc-1.1.30052013.xsd xqdoc-1.1.30052013.xsd]):<br/>
+
We have slightly extended the xqDoc conventions to do justice to more recent versions of XQuery (Schema: [https://files.basex.org/etc/xqdoc-1.1.30052013.xsd xqdoc-1.1.30052013.xsd]):<br/>
 
* an {{Code|<xqdoc:annotations/>}} node is added to each variable or function that uses annotations. The xqdoc:annotation child nodes may have additional {{Code|xqdoc:literal}} elements with {{Code|type}} attributes (xs:string, xs:integer, xs:decimal, xs:double) and values.
 
* an {{Code|<xqdoc:annotations/>}} node is added to each variable or function that uses annotations. The xqdoc:annotation child nodes may have additional {{Code|xqdoc:literal}} elements with {{Code|type}} attributes (xs:string, xs:integer, xs:decimal, xs:double) and values.
 
* a single {{Code|<xqdoc:namespaces/>}} node is added to the root element, which summarizes all prefixes and namespace URIs used or declared in the module.
 
* a single {{Code|<xqdoc:namespaces/>}} node is added to the root element, which summarizes all prefixes and namespace URIs used or declared in the module.
 
* name and type elements are added to variables.
 
* name and type elements are added to variables.
|-
+
|- valign="top"
| '''Errors'''
 
|{{Error|FODC0002|XQuery Errors#Functions Errors}} the addressed resource cannot be retrieved.
 
|-
 
 
|'''Examples'''
 
|'''Examples'''
 
|An example is [[#Examples|shown below]].
 
|An example is [[#Examples|shown below]].
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|parse|#Errors}} Error while parsing a module.
 
|}
 
|}
  
Line 202: Line 228:
 
This is the {{Code|sample.xqm}} library module:
 
This is the {{Code|sample.xqm}} library module:
  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
(:~  
 
(:~  
 
  : This module provides some sample functions to demonstrate
 
  : This module provides some sample functions to demonstrate
Line 224: Line 250:
 
   $number
 
   $number
 
};
 
};
</pre>
+
</syntaxhighlight>
  
 
If {{Code|inspect:module('sample.xqm')}} is run, the following output will be generated:
 
If {{Code|inspect:module('sample.xqm')}} is run, the following output will be generated:
  
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<module prefix="samples" uri="http://basex.org/modules/samples">
 
<module prefix="samples" uri="http://basex.org/modules/samples">
 
   <description>This module provides some sample functions to demonstrate
 
   <description>This module provides some sample functions to demonstrate
Line 245: Line 271:
 
   </function>
 
   </function>
 
</module>
 
</module>
</pre>
+
</syntaxhighlight>
  
 
The output looks as follows if {{Code|inspect:xqdoc('sample.xqm')}} is called:
 
The output looks as follows if {{Code|inspect:xqdoc('sample.xqm')}} is called:
  
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
 
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
 
   <xqdoc:control>
 
   <xqdoc:control>
Line 303: Line 329:
 
   </xqdoc:functions>
 
   </xqdoc:functions>
 
</xqdoc:xqdoc>
 
</xqdoc:xqdoc>
</pre>
+
</syntaxhighlight>
  
 
=Errors=
 
=Errors=
Line 310: Line 336:
 
! width="110"|Code
 
! width="110"|Code
 
|Description
 
|Description
|-
+
|- valign="top"
 +
|{{Code|parse}}
 +
|Error while parsing a module.
 +
|- valign="top"
 
|{{Code|unknown}}
 
|{{Code|unknown}}
 
|The specified component does not exist.
 
|The specified component does not exist.
Line 316: Line 345:
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.6
 +
* Updated: {{Function||inspect:type}}: options added
 +
 +
;Version 9.3
 +
* Added: {{Function||inspect:type}}
  
 
;Version 8.5
 
;Version 8.5
* Added: [[#inspect:function-annotations|inspect:function-annotations]], [[#inspect:static-context|inspect:static-context]]
+
* Added: {{Function||inspect:function-annotations}}, {{Function||inspect:static-context}}
 
* Updated: {{Code|external}} attribute added to variables and functions
 
* Updated: {{Code|external}} attribute added to variables and functions
 
* Updated: Relative URIs will always be resolved against the static base URI of the query
 
* Updated: Relative URIs will always be resolved against the static base URI of the query
  
 
;Version 7.9
 
;Version 7.9
* Updated: a query URI can now be specified with [[#inspect:functions|inspect:functions]].
+
* Updated: a query URI can now be specified with {{Function||inspect:functions}}.
  
 
This module was introduced with Version 7.7.
 
This module was introduced with Version 7.7.

Revision as of 13:18, 20 July 2022

This XQuery Module contains functions for extracting internal information about modules and functions and generating documentation.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/inspect namespace, which is statically bound to the inspect prefix.
xqDoc document instances are assigned to the http://www.xqdoc.org/1.0 namespace, which is statically bound to the xqdoc prefix.

Reflection

inspect:functions

Signatures inspect:functions() as function(*)*
inspect:functions($uri as xs:string) as function(*)*
Summary Returns function items for all user-defined functions (both public and private) that are known in the current query context. If a $uri is specified, the specified resource will be retrieved as string and compiled, and its functions will be added to the query context and returned to the user. A relative URI will be resolved against the static base URI of the query.
Examples Invokes the declared functions and returns their values:

<syntaxhighlight lang="xquery"> declare %private function local:one() { 12 }; declare %private function local:two() { 34 }; for $f in inspect:functions() return $f() </syntaxhighlight> Compiles all functions in code.xqm and invokes the function named run: <syntaxhighlight lang="xquery"> let $uri := 'code.xqm' let $name := 'run' for $f in inspect:functions($uri) where local-name-from-QName(function-name($f)) = $name return $f() </syntaxhighlight>

Errors parse: Error while parsing a module.

inspect:function-annotations

Signatures inspect:function-annotations($function as function(*)?) as map(xs:QName, xs:anyAtomicType*)
Summary Returns the annotations of the specified $function in a map.
Examples
  • Returns an empty map:

<syntaxhighlight lang="xquery"> inspect:function-annotations(true#0) </syntaxhighlight>

  • Returns a map with a single key Q{http://www.w3.org/2012/xquery}private and an empty sequence as value:

<syntaxhighlight lang="xquery"> declare %private function local:f() { 'well hidden' }; inspect:function-annotations(local:f#0) </syntaxhighlight>

inspect:static-context

Signatures inspect:static-context($function as function(*)?, $name as xs:string) as item()*
Summary Returns a component of the static context of a $function with the specified $name. If no function is supplied, the current static context is considered.
The following components can be requested:
  • base-uri: Static base URI.
  • namespaces: Prefix/URI map with all statically known namespaces.
  • element-namespace: Default element/type namespace URI, or an empty sequence if it is absent.
  • function-namespace: Default function namespace URI, or an empty sequence if it is absent.
  • collation: URI of the default collation.
  • ordering: Ordering mode (ordered/unordered)
  • construction: Construction mode (preserve/strip)
  • default-order-empty: Default order for empty sequences (greatest/least)
  • boundary-space: Boundary-space policy (preserve/strip)
  • copy-namespaces: Copy-namespaces mode (inherit/no-inherit, preserve/no-preserve)
  • decimal-formats: Nested map with all statically known decimal formats
Examples
  • Returns the static base URI (same as static-base-uri()):

<syntaxhighlight lang="xquery"> inspect:static-context((), 'base-uri') </syntaxhighlight>

  • Returns a map with all namespaces that are statically known in the module of the specified function:

<syntaxhighlight lang="xquery"> import module namespace data = 'data.xqm'; inspect:static-context(data:get#1, 'namespaces') </syntaxhighlight>

Errors unknown: The specified component does not exist.

Documentation

inspect:type

Signatures inspect:type($value as item()*) as xs:string
inspect:type($value as item()*, $options as map(*)) as xs:string
Summary Returns a string representation of the type of a $value:
  • The string includes the occurrence indicator.
  • The type of functions and nodes may be stricter than the returned type.
  • For type checking, the standard expressions typeswitch and instance of should be used instead.

The following $options are available:

  • item: If enabled, only the item type is returned and the occurrence indicator is omitted. The default is false().
  • mode: If value is specified, the assigned type of the result value is returned. With expression the type of the input expression is returned (please note that the original expression may already have been rewritten at compile-time). With computed, the exact value is computed at runtime, based on the expression and the result value. The default is computed.
Examples
  • inspect:type((<a/>, <a/>)) yields element(a)+
  • inspect:type(map { 'a': (1, 2)[. = 1] }) yields map(xs:string, xs:integer)
  • inspect:type(1 to 100, map { 'item': true() }) yields xs:integer

inspect:function

Signatures inspect:function($function as function(*)) as element(function)
Summary Inspects the specified $function and returns an element that describes its structure. The output of this function is similar to eXist-db’s inspect:inspect-function function.
Examples The query inspect:function(count#1) yields:

<syntaxhighlight lang="xml"> <function name="count" uri="http://www.w3.org/2005/xpath-functions" external="false">

 <argument type="item()" occurrence="*"/>
 <return type="xs:integer"/>

</function> </syntaxhighlight> The function… <syntaxhighlight lang="xquery"> (:~

: This function simply returns the specified integer.
: @param $number  number to return
: @return         specified number
:)

declare %private function local:same($number as xs:integer) as xs:integer {

 $number

}; </syntaxhighlight> …is represented by inspect:function(local:same#1) as… <syntaxhighlight lang="xml"> <function name="local:same" uri="http://www.w3.org/2005/xquery-local-functions" external="false">

 <argument type="xs:integer" name="number">number to return</argument>
 <annotation name="private" uri="http://www.w3.org/2012/xquery"/>
 <description>This function simply returns the specified integer.</description>
 <return type="xs:integer">specified number</return>

</function> </syntaxhighlight>

inspect:context

Signatures inspect:context() as element(context)
Summary Generates an element that describes all variables and functions in the current query context.
Examples Evaluate all user-defined functions with zero arguments in the query context:

<syntaxhighlight lang="xquery"> inspect:context()/function ! function-lookup(QName(@uri, @name), 0) ! .() </syntaxhighlight> Return the names of all private functions in the current context: <syntaxhighlight lang="xquery"> for $f in inspect:context()/function where $f/annotation/@name = 'private' return $f/@name/string() </syntaxhighlight>

inspect:module

Signatures inspect:module($uri as xs:string) as element(module)
Summary Retrieves the resource located at the specified $uri, parses it as XQuery module, and generates an element that describes the module's structure. A relative URI will be resolved against the static base URI of the query.
Examples An example is shown below.
Errors parse: Error while parsing a module.

inspect:xqdoc

Signatures inspect:xqdoc($uri as xs:string) as element(xqdoc:xqdoc)
Summary Retrieves the resource located at the specified $uri, parses it as XQuery module, and generates an xqDoc element. A relative URI will be resolved against the static base URI of the query.
xqDoc provides a simple vendor-neutral solution for generating documentation from XQuery modules. The documentation conventions have been inspired by the JavaDoc standard. Documentation comments begin with (:~ and end with :), and tags start with @. xqDoc comments can be specified for main and library modules and variable and function declarations.

We have slightly extended the xqDoc conventions to do justice to more recent versions of XQuery (Schema: xqdoc-1.1.30052013.xsd):

  • an <xqdoc:annotations/> node is added to each variable or function that uses annotations. The xqdoc:annotation child nodes may have additional xqdoc:literal elements with type attributes (xs:string, xs:integer, xs:decimal, xs:double) and values.
  • a single <xqdoc:namespaces/> node is added to the root element, which summarizes all prefixes and namespace URIs used or declared in the module.
  • name and type elements are added to variables.
Examples An example is shown below.
Errors parse: Error while parsing a module.

Examples

This is the sample.xqm library module:

<syntaxhighlight lang="xquery"> (:~

: This module provides some sample functions to demonstrate
: the features of the Inspection Module.
:
: @author   BaseX Team
: @see      http://docs.basex.org/wiki/XQDoc_Module
: @version  1.0
:)

module namespace samples = 'http://basex.org/modules/samples';

(:~ This is a sample string. :) declare variable $samples:test-string as xs:string := 'this is a string';

(:~

: This function simply returns the specified integer.
: @param   $number number to return
: @return  specified number
:)

declare %private function samples:same($number as xs:integer) as xs:integer {

 $number

}; </syntaxhighlight>

If inspect:module('sample.xqm') is run, the following output will be generated:

<syntaxhighlight lang="xml"> <module prefix="samples" uri="http://basex.org/modules/samples">

 <description>This module provides some sample functions to demonstrate

the features of the Inspection Module.</description>

 <author>BaseX Team</author>
 <see>http://docs.basex.org/wiki/XQDoc_Module</see>
 <version>1.0</version>
 <variable name="samples:test-string" uri="http://basex.org/modules/samples" type="xs:string" external="false">
   <description>This is a sample string.</description>
 </variable>
 <function name="samples:same" uri="http://basex.org/modules/samples" external="false">
   <argument name="number" type="xs:integer">number to return</argument>
   <annotation name="private" uri="http://www.w3.org/2012/xquery"/>
   <description>This function simply returns the specified integer.</description>
   <return type="xs:integer">specified number</return>
 </function>

</module> </syntaxhighlight>

The output looks as follows if inspect:xqdoc('sample.xqm') is called:

<syntaxhighlight lang="xml"> <xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">

 <xqdoc:control>
   <xqdoc:date>2013-06-01T16:59:33.654+02:00</xqdoc:date>
   <xqdoc:version>1.1</xqdoc:version>
 </xqdoc:control>
 <xqdoc:module type="library">
   <xqdoc:uri>http://basex.org/modules/samples</xqdoc:uri>
   <xqdoc:name>sample.xqm</xqdoc:name>
   <xqdoc:comment>
     <xqdoc:description>This module provides some sample functions to demonstrate

the features of the Inspection Module.</xqdoc:description>

     <xqdoc:author>BaseX Team</xqdoc:author>
     <xqdoc:see>http://docs.basex.org/wiki/XQDoc_Module</xqdoc:see>
     <xqdoc:version>1.0</xqdoc:version>
   </xqdoc:comment>
 </xqdoc:module>
 <xqdoc:namespaces>
   <xqdoc:namespace prefix="samples" uri="http://basex.org/modules/samples"/>
 </xqdoc:namespaces>
 <xqdoc:imports/>
 <xqdoc:variables>
   <xqdoc:variable>
     <xqdoc:name>samples:test-string</xqdoc:name>
     <xqdoc:comment>
       <xqdoc:description>This is a sample string.</xqdoc:description>
     </xqdoc:comment>
     <xqdoc:type>xs:string</xqdoc:type>
   </xqdoc:variable>
 </xqdoc:variables>
 <xqdoc:functions>
   <xqdoc:function arity="1">
     <xqdoc:comment>
       <xqdoc:description>This function simply returns the specified integer.</xqdoc:description>
       <xqdoc:param>$number number to return</xqdoc:param>
       <xqdoc:return>specified number</xqdoc:return>
     </xqdoc:comment>
     <xqdoc:name>samples:same</xqdoc:name>
     <xqdoc:annotations>
       <xqdoc:annotation name="private"/>
     </xqdoc:annotations>
     <xqdoc:signature>declare %private function samples:same($number as xs:integer) as xs:integer</xqdoc:signature>
     <xqdoc:parameters>
       <xqdoc:parameter>
         <xqdoc:name>number</xqdoc:name>
         <xqdoc:type>xs:integer</xqdoc:type>
       </xqdoc:parameter>
     </xqdoc:parameters>
     <xqdoc:return>
       <xqdoc:type>xs:integer</xqdoc:type>
     </xqdoc:return>
   </xqdoc:function>
 </xqdoc:functions>

</xqdoc:xqdoc> </syntaxhighlight>

Errors

Code Description
parse Error while parsing a module.
unknown The specified component does not exist.

Changelog

Version 9.6
Version 9.3
Version 8.5
Version 7.9

This module was introduced with Version 7.7.