Inspection Module

From BaseX Documentation
Jump to navigation Jump to search

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

Conventions

All functions in this module are assigned to the http://basex.org/modules/inspect namespace, which is statically bound to the inspect prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr prefix.

Functions

inspect:function

Signatures inspect:function($function as function()) as element(function)
Summary Inspects the specified $function and returns an element that describs 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:
<function name="count" uri="http://www.w3.org/2005/xpath-functions">
  <parameter type="item()" occurrence="*"/>
  <return type="xs:integer"/>
</function>

The function…

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

…is represented by inspect:function(local:same#1) as…

<function name="local:same" uri="http://www.w3.org/2005/xquery-local-functions">
  <parameter type="xs:integer" name="number">number to return</parameter>
  <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>

inspect:xqdoc

Signatures inspect:xqdoc($uri as xs:string) as element(xqdoc:xqdoc)
Summary Retrieves the string from the specified $input, parses it as XQuery module, and generates an xqDoc element.
xqDoc provides a simple vendor neutral solution for generating a 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 conventions and updated the xqDoc schema:
  • an <xqdoc:namespaces/> node lists all namespaces of a module
  • if annotations are attached to variables or functions, an <xqdoc:annotations/> node is added
  • variables now have a name and a type.
Errors FODC0002: the addressed resource cannot be retrieved.
Example Examples are shown below.

Example

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

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

<module prefix="samples" uri="http://basex.org/modules/samples">
  <variable name="samples:test-string" uri="http://basex.org/modules/samples" type="xs:string">
    <description>This is a sample string.</description>
  </variable>
  <function name="samples:same" uri="http://basex.org/modules/samples">
    <parameter name="number" type="xs:integer">number to return</parameter>
    <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>

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-05-31T08:43:05.123+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:module>
  <xqdoc:imports/>
  <xqdoc:namespaces>
    <xqdoc:namespace prefix="samples" uri="http://basex.org/modules/samples"/>
  </xqdoc:namespaces>
  <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>

Changelog

This module was introduced with Version 7.7.