Main Page » XQuery » Functions » Inspection Functions

Inspection Functions

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

Updated: inspect:function-annotations has been removed as it is now available in the official specification as fn:function-annotations.

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

Signature
inspect:functions(
  $href  as xs:string  := ()
) as fn(*)*
SummaryReturns function items for all user-defined functions (both public and private) that are known in the current query context. If an $href value is specified, the specified resource will be retrieved as a 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.
Errors
parseError while parsing a module.
Examples
declare %private function local:one() { 12 };
declare %private function local:two() { 34 };
for $f in inspect:functions() return $f()
Invokes the declared functions and returns their values.
let $uri := 'code.xqm'
let $name := 'run'
for $f in inspect:functions($uri)
where local-name-from-QName(function-name($f)) = $name
return $f()
Compiles all functions in code.xqm and invokes the function named run.

inspect:static-context

Signature
inspect:static-context(
  $function  as fn(*)?,
  $name      as xs:string
) as item()*
SummaryReturns 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
Errors
unknownThe specified component does not exist.
Examples
inspect:static-context((), 'base-uri')
Returns the static base URI (same as static-base-uri()).
import module namespace data = 'data.xqm';
inspect:static-context(data:get#1, 'namespaces')
Returns a map with all namespaces that are statically known in the module of the specified function.

Documentation

inspect:type

Signature
inspect:type(
  $input    as item()*,
  $options  as map(*)?  := {}
) as xs:string
SummaryReturns a string representation of the type of a the given $input:
  • 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:

optiondefaultdescription
itemfalse() If enabled, only the item type is returned and the occurrence indicator is omitted.
modecomputed
  • 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.
Examples
inspect:type((<a/>, <a/>))
Yields element(a)+.
inspect:type({ 'a': (1, 2)[. = 1] })
Yields map(xs:string, xs:integer).
inspect:type(1 to 100, { 'item': true() })
Yields xs:integer.

inspect:function

Signature
inspect:function(
  $function  as fn(*)
) as element(function)
SummaryInspects the specified $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.
Examples
inspect:function(count#1)
The result:
<function name="count" uri="http://www.w3.org/2005/xpath-functions"
    external="false">
  <argument type="item()" occurrence="*"/>
  <return type="xs:integer"/>
</function>

(:~
 : This function 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
};
inspect:function(local:same#1)
The result:
<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 returns the specified integer.</description>
  <return type="xs:integer">specified number</return>
</function>

inspect:context

Signature
inspect:context() as element(context)
SummaryGenerates an element that describes all variables and functions in the current query context.
Examples
inspect:context()/function ! function-lookup(QName(@uri, @name), 0) ! .()
Evaluate all user-defined functions with zero arguments in the query context.
for $f in inspect:context()/function
where $f/annotation/@name = 'private'
return $f/@name/string()
Return the names of all private functions in the current context.

inspect:module

Signature
inspect:module(
  $uri  as xs:string
) as element(module)
SummaryRetrieves 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.
Errors
parseError while parsing a module.
ExamplesAn example is shown below.

inspect:xqdoc

Signature
inspect:xqdoc(
  $uri  as xs:string
) as element(xqdoc:xqdoc)
SummaryRetrieves 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.
Errors
parseError while parsing a module.
ExamplesAn example is shown below.

Examples

This is the sample.xqm library module:

(:~ 
 : 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 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
};

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

<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 returns the specified integer.</description>
    <return type="xs:integer">specified number</return>
  </function>
</module>

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

<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 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>

Errors

CodeDescription
parseError while parsing a module.
unknownThe specified component does not exist.

Changelog

Version 11.0Version 9.6Version 9.3Version 8.5
  • Added: inspect:function-annotations, inspect:static-context
  • Updated: external attribute added to variables and functions
  • Updated: Relative URIs will always be resolved against the static base URI of the query
Version 7.9Version 7.7
  • Added: New module added.

⚡Generated with XQuery