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

inspect:functions(
  $href  as xs:string  := ()
) as fn(*)*

declare %private function local:one() { 12 };
declare %private function local:two() { 34 };
for $f in inspect:functions() return $f()

let $uri := 'code.xqm'
let $name := 'run'
for $f in inspect:functions($uri)
where local-name-from-QName(function-name($f)) = $name
return $f()

inspect:static-context

inspect:static-context(
  $function  as fn(*)?,
  $name      as xs:string
) as item()*

inspect:static-context((), 'base-uri')

import module namespace data = 'data.xqm';
inspect:static-context(data:get#1, 'namespaces')

Documentation

inspect:type

inspect:type(
  $input    as item()*,
  $options  as map(*)?  := {}
) as xs:string

inspect:type((<a/>, <a/>))

inspect:type({ 'a': (1, 2)[. = 1] })

inspect:type(1 to 100, { 'item': true() })

inspect:function

inspect:function(
  $function  as fn(*)
) as element(function)

inspect:function(count#1)

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

<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

inspect:context() as element(context)

inspect:context()/function ! function-lookup(QName(@uri, @name), 0) ! .()

for $f in inspect:context()/function
where $f/annotation/@name = 'private'
return $f/@name/string()

inspect:module

inspect:module(
  $uri  as xs:string
) as element(module)

inspect:xqdoc

inspect:xqdoc(
  $uri  as xs:string
) as element(xqdoc:xqdoc)

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

Changelog

• Removed: inspect:function-annotations in favor of fn:function-annotations

• Updated: inspect:type: options added

• Added: inspect:type

• 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

• Updated: a query URI can now be specified with inspect:functions.

• Added: New module added.