Difference between revisions of "Inspection Module"
Line 13: | Line 13: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:functions( |
+ | $uri as xs:string := () | ||
+ | ) as function(*)*</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 43: | Line 45: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:function-annotations( |
+ | $function as function(*)? | ||
+ | ) as map(xs:QName, xs:anyAtomicType*)</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 66: | Line 70: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:static-context( |
+ | $function as function(*)? | ||
+ | $name as xs:string | ||
+ | ) as item()*</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 105: | Line 112: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:type( |
+ | $value as item()* | ||
+ | $options as map(*) := () | ||
+ | ) as xs:string</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 128: | Line 138: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:function( |
+ | $function as function(*) | ||
+ | ) as element(function)</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 168: | Line 180: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:context() as element(context)</pre> |
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 191: | Line 203: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:module( |
+ | $uri as xs:string | ||
+ | ) as element(module)</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 208: | Line 222: | ||
|- valign="top" | |- valign="top" | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |<pre>inspect:xqdoc( |
+ | $uri as xs:string | ||
+ | ) as element(xqdoc:xqdoc)</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' |
Revision as of 13:06, 9 March 2023
This XQuery Module contains functions for extracting internal information about modules and functions and generating documentation.
Contents
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( $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 |
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 |
<syntaxhighlight lang="xquery"> inspect:function-annotations(true#0) </syntaxhighlight>
<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:
|
Examples |
<syntaxhighlight lang="xquery"> inspect:static-context((), 'base-uri') </syntaxhighlight>
<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()* $options as map(*) := () ) as xs:string |
Summary | Returns a string representation of the type of a $value :
The following
|
Examples |
|
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 <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):
|
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
- Updated:
inspect:type
: options added
- Version 9.3
- Added:
inspect:type
- Version 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.9
- Updated: a query URI can now be specified with
inspect:functions
.
This module was introduced with Version 7.7.