Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
{{Mark|Introduced with Version 8.5}}==inspect:type==
==inspect:function==
Text replacement - "syntaxhighlight" to "pre"
This [[Module Library|XQuery Module]] contains functions for extracting internal information about modules and functions and generating documentation.
With {{Announce|Version 11}}, {{Code|inspect:function-annotations}} has been removed as it is now available in the official specification as [https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-function-annotations <code>fn:function-annotations</code>].
=Conventions=
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/inspect</nowiki></code> namespace, which is statically bound to the {{Code|inspect}} prefix.<br/>
xqDoc document instances are assigned to the <code><nowiki>http://www.xqdoc.org/1.0</nowiki></code> namespace, which is statically bound to the {{Code|xqdoc}} prefix.
=Reflection=
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|inspect:functions||function(*)*}}<br/pre>{{Func|inspect:functions|( $uri href as xs:string| := ()) as function(*)*}}</pre>|-valign="top"
| '''Summary'''
|Returns function items for all user-defined functions (both public and private) that are known in the current query context. If a an {{Code|$urihref}} value is specified, the addressed module 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.|-valign="top"
|'''Examples'''
|Invokes the declared functions and returns their values:<br/>
<pre classlang="brush:'xquery"'>
declare %private function local:one() { 12 };
declare %private function local:two() { 34 };
</pre>
Compiles all functions in {{Code|code.xqm}} and invokes the function named {{Code|run}}:
<pre classlang="brush:'xquery"'>
let $uri := 'code.xqm'
let $name := "'run"'
for $f in inspect:functions($uri)
where local-name-from-QName(function-name($f)) = $name
return $f()
</pre>
|- valign="top"
| '''Errors'''
|{{Error|parse|#Errors}} Error while parsing a module.
|}
==inspect:functionstatic-annotationscontext== {{Mark|Introduced with Version 8.5}}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>inspect:functionstatic-annotations|context( $function as function(*)?|map(xs:QName, $name as xs:anyAtomicTypestring) as item()*)}}<br/pre>|-valign="top"
| '''Summary'''
|Returns a component of the annotations [https://www.w3.org/TR/xquery-31/#dt-static-context static context] of a {{Code|$function}} with the specified {{Code|$name}}. If no functionis supplied, the current static context is considered.<br/>The following components can be requested:* {{Code|base-uri}}: Static base URI.* {{Code|namespaces}} in a : Prefix/URI mapwith 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|-valign="top"
| '''Examples'''
|
* Returns an empty mapthe static base URI (same as {{Code|static-base-uri()}}):<pre classlang="brush:'xquery"'>inspect:functionstatic-annotationscontext(true#0(), 'base-uri')
</pre>
* Returns a map with a single key <code><nowiki>Q{http://www.w3.org/2012/xquery}private</nowiki></code> and an empty sequence as valueall namespaces that are statically known in the module of the specified function:<pre classlang="brush:'xquery"'>declare %private function local:f() { import module namespace data = 'well hiddendata.xqm' };inspect:functionstatic-annotationscontext(localdata:fget#01, 'namespaces')
</pre>
|- valign="top"
| '''Errors'''
|{{Error|unknown|#Errors}} The specified component does not exist.
|}
==inspect:static-context=Documentation=
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>inspect:static-context|type( $function input as functionitem()*)?, $name options as |map(xs*)? :QName, = map { }) as xs:anyAtomicType*)}}string<br/pre>|-valign="top"
| '''Summary'''
|Returns a string representation of the annotations type of a the given {{Code|$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 {{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|$functionexpression}} 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}} in a map.|-valign="top"
| '''Examples'''
|
* Returns an empty map:<pre class="brush:xquery"code>inspect:function-annotationstype(true#0(<a/>, <a/>))</precode> yields <code>* Returns element(a map with a single key )+</code>* <nowikicode>Qinspect:type(map {http'a'://www(1, 2)[.w3.org/2012/xquery= 1] }private)</nowikicode>yields <code>map(xs:string, xs:integer)</code> and an empty sequence as value:* <pre class="brush:xquery"code>declare %private function localinspect:ftype() 1 to 100, map { 'well hiddenitem' };inspect:function-annotationstrue(local) })</code> yields <code>xs:f#0)integer</precode>
|}
=Documentation=inspect:function==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>inspect:function|( $function as function(*)|) as element(function)}}</pre>|-valign="top"
| '''Summary'''
|Inspects the specified {{Code|$function}} and returns an element that describes its structure. The output of this function is similar to eXist-db’s [httphttps://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.|-valign="top"
|'''Examples'''
|The query {{Code|inspect:function(count#1)}} yields:
<pre classlang="brush:xml"><function name="count" uri="http://www.w3.org/2005/xpath-functions" external="false">
<argument type="item()" occurrence="*"/>
<return type="xs:integer"/>
</pre>
The function…
<pre classlang="brush:'xquery"'>
(:~
: This function simply returns the specified integer.
</pre>
…is represented by {{Code|inspect:function(local:same#1)}} as…
<pre classlang="brush: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"/>
==inspect:context==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>inspect:context||() as element(context)}}</pre>|-valign="top"
| '''Summary'''
|Generates an element that describes all variables and functions in the current query context.
|-valign="top"
| '''Examples'''
|Evaluate all user-defined functions with zero arguments in the query context:<br/>
<pre classlang="brush:'xquery"'>
inspect:context()/function ! function-lookup(QName(@uri, @name), 0) ! .()
</pre>
Return the names of all private functions in the current context:
<pre classlang="brush:'xquery"'>
for $f in inspect:context()/function
where $f/annotation/@name = 'private'
==inspect:module==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>inspect:module|( $uri as xs:string|) as element(module)}}</pre>|-valign="top"
| '''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.|-| '''Errors'''|{{Error|FODC0002|XQuery Errors#Functions Errors}} A relative URI will be resolved against the static base URI of the addressed resource cannot be retrievedquery.|-valign="top"
|'''Examples'''
|An example is [[#Examples|shown below]].
|- valign="top"
| '''Errors'''
|{{Error|parse|#Errors}} Error while parsing a module.
|}
==inspect:xqdoc==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>inspect:xqdoc|( $uri as xs:string|) as element(xqdoc:xqdoc)}}</pre>|-valign="top"
| '''Summary'''
|Retrieves the resource located at the specified {{Code|$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.<br/>[http://xqdoc.org / 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 {{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 to do justice to the current status more recent versions of XQuery (Schema: [httphttps://files.basex.org/etc/xqdoc-1.1.30052013.xsd xqdoc-1.1.30052013.xsd]):<br/>
* an {{Code|<xqdoc:annotations/>}} node is added to each variable or function 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, xs:double) and values.
* a single {{Code|<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'''|{{Error|FODC0002|XQuery Errors#Functions Errors}} the addressed resource cannot be retrieved.|-valign="top"
|'''Examples'''
|An example is [[#Examples|shown below]].
|- valign="top"
| '''Errors'''
|{{Error|parse|#Errors}} Error while parsing a module.
|}
This is the {{Code|sample.xqm}} library module:
<pre classlang="brush:'xquery"'>
(:~
: This module provides some sample functions to demonstrate
If {{Code|inspect:module('sample.xqm')}} is run, the following output will be generated:
<pre classlang="brush:xml">
<module prefix="samples" uri="http://basex.org/modules/samples">
<description>This module provides some sample functions to demonstrate
<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"/>
The output looks as follows if {{Code|inspect:xqdoc('sample.xqm')}} is called:
<pre classlang="brush:xml">
<xqdoc:xqdoc xmlns:xqdoc="http://www.xqdoc.org/1.0">
<xqdoc:control>
</xqdoc:xqdoc>
</pre>
=Errors=
{| class="wikitable" width="100%"
! width="110"|Code
|Description
|- valign="top"
|{{Code|parse}}
|Error while parsing a module.
|- valign="top"
|{{Code|unknown}}
|The specified component does not exist.
|}
=Changelog=
;Version 11.0
* Removed: {{Code|inspect:function-annotations}}
;Version 9.6
* Updated: {{Function||inspect:type}}: options added
;Version 9.3
* Added: {{Function||inspect:type}}
;Version 8.5
* Added: [[#inspect:function-annotations{{Function||inspect:function-annotations]]}}, [[#{{Function||inspect:static-context}}* Updated: {{Code|inspectexternal}} attribute added to variables and functions* Updated:Relative URIs will always be resolved against the static-context]]base URI of the query
;Version 7.9
* Updated: a query URI can now be specified with [[#inspect:functions{{Function||inspect:functions]]}}.
This module was introduced with Version 7.7.
