Changes

Jump to navigation Jump to search
no edit summary
This [[Module Library|XQuery Module]] contains functions for extracting internal information on about modules and functions and generating documentation.
=Conventions=
All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/inspect}} </nowiki></code> namespace, which is statically bound to the {{Code|inspect}} prefix.<br/>All errors xqDoc document instances are assigned to the {{Code|<code><nowiki>http://basexwww.xqdoc.org/errors}} 1.0</nowiki></code> namespace, which is statically bound to the {{Code|bxerrxqdoc}} prefix.
=FunctionsReflection==inspect:functions== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|inspect:functions||function(*)*}}<br/>{{Func|inspect:functions|$uri as xs:string|function(*)*}}|-| '''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 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:<br/><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|code.xqm}} and invokes the function named {{Code|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)) = $namereturn $f()</syntaxhighlight>|-| '''Errors'''|{{Error|parse|#Errors}} Error while parsing a module.|} ==inspect:function-annotations== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|inspect:function-annotations|$function as function(*)?|map(xs:QName, xs:anyAtomicType*)}}<br/>|-| '''Summary'''|Returns the annotations of the specified {{Code|$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 <code><nowiki>Q{http://www.w3.org/2012/xquery}private</nowiki></code> 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== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|inspect:static-context|$function as function(*)?, $name as xs:string|item()*}}<br/>|-| '''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:* {{Code|base-uri}}: Static base URI.* {{Code|namespaces}}: Prefix/URI map with all statically known namespaces.* {{Code|element-namespace}}: Default element/type namespace URI, or an empty sequence if it is absent.* {{Code|function-namespace}}: Default function namespace URI, or an empty sequence if it is absent.* {{Code|collation}}: URI of the default collation.* {{Code|ordering}}: Ordering mode ({{Code|ordered}}/{{Code|unordered}})* {{Code|construction}}: Construction mode ({{Code|preserve}}/{{Code|strip}})* {{Code|default-order-empty}}: Default order for empty sequences ({{Code|greatest}}/{{Code|least}})* {{Code|boundary-space}}: Boundary-space policy ({{Code|preserve}}/{{Code|strip}})* {{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|-| '''Examples'''|* Returns the static base URI (same as {{Code|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'''|{{Error|unknown|#Errors}} The specified component does not exist.|} =Documentation= ==inspect:type== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|inspect:type|$value as item()*|xs:string}}<br/>{{Func|inspect:type|$value as item()*, $options as map(*)|xs:string}}|-| '''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}}.|-| '''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==
 
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|inspect:function|$function as function(*)|element(function)}}
|-
| '''Summary'''
|Inspects the specified {{Code|$function}} and returns an element that describs 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'''
|The query {{Code|inspect:function(count#1) }} yields:<pre classsyntaxhighlight lang="brush:xqueryxml"><function name="count" uri="http://www.w3.org/2005/xpath-functions" external="false"> <parameter argument type="item()" occurrence="*" name="value1"/>
<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 {{Code|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==
 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|inspect:context||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:<br/>
<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==
 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|inspect:module|$uri as xs:string|element(module)}}
|-
| '''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.
|-
|'''Examples'''
|An example is [[#Examples|shown below]].
|-
| '''Errors'''
|{{Error|parse|#Errors}} Error while parsing a module.
|}
==inspect:xqdoc==
 
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|inspect:xqdoc|$uri as xs:string|element(xqdoc:xqdoc)}}
|-
| '''Summary'''
|Retrieves the string from resource located at the specified {{Code|$inputuri}}, 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 a 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 and updated the to do justice to more recent versions of XQuery (Schema: [httphttps://files.basex.org/etc/xqdoc-1.1.30052013.xsd xqDoc schemaxqdoc-1.1.30052013.xsd]):<br/>* an {{Code|<xqdoc:namespacesannotations/>}} node lists all namespaces of a module* if annotations are attached is added to variables each variable or functionsfunction 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, an xs:double) and values.* a single {{Code|<xqdoc:annotationsnamespaces/>}} node is addedto the root element, which summarizes all prefixes and namespace URIs used or declared in the module.* variables now have a name and a typeelements are added to variables.|-|'''Examples'''|An example is [[#Examples|shown below]].
|-
| '''ExampleErrors'''|An example is [[{{Error|parse|#Example|shown below]]Errors}} Error while parsing a module.
|}
=ExampleExamples=
The query This is the {{Code|xqdoc:parse('sample.xq')xqm}} will convert the following example library module...:
<pre classsyntaxhighlight lang="brush: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
};
</presyntaxhighlightIf {{Code|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 demonstratethe 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 following outputspecified integer.</description> <return type="xs:integer">specified number</return> </function></module></syntaxhighlight>
The output looks as follows if {{Code|inspect:xqdoc('sample.xqm')}} is called: <pre classsyntaxhighlight lang="brush:xml">
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
<xqdoc:control>
<xqdoc:date>2013-0506-31T0801T16:4359:0533.123654+02:00</xqdoc:date>
<xqdoc:version>1.1</xqdoc:version>
</xqdoc:control>
<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:imports/>
<xqdoc:namespaces>
<xqdoc:namespace prefix="samples" uri="http://basex.org/modules/samples"/>
</xqdoc:namespaces>
<xqdoc:imports/>
<xqdoc:variables>
<xqdoc:variable>
</xqdoc:functions>
</xqdoc:xqdoc>
</presyntaxhighlight=Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|-|{{Code|parse}}|Error while parsing a module.|-|{{Code|unknown}}|The specified component does not exist.|}
=Changelog=
 
;Version 9.6
* Updated: [[#inspect:type|inspect:type]]: options added
 
;Version 9.3
* Added: [[#inspect:type|inspect:type]]
 
;Version 8.5
* Added: [[#inspect:function-annotations|inspect:function-annotations]], [[#inspect:static-context|inspect:static-context]]
* Updated: {{Code|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|inspect:functions]].
This module was introduced with Version 7.7.
 
[[Category:XQuery]]
Bureaucrats, editor, reviewer, Administrators
12,947

edits

Navigation menu