Difference between revisions of "Fetch Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "assigned to the \{\{Code\|([^}]*)\}\} namespace" to "assigned to the <code><nowiki>$1</nowiki></code> namespace")
Line 49: Line 49:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|fetch:xml|$uri as xs:string|document-node()}}<br/>{{Func|fetch:xml|$uri as xs:string, $options as item()|document-node()}}
+
|{{Func|fetch:xml|$uri as xs:string|document-node()}}<br/>{{Func|fetch:xml|$uri as xs:string, $options as map(xs:string, item())|document-node()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Fetches the resource referred to by the given {{Code|$uri}} and returns it as an XML document.<br/>In contrast to <code>fn:doc</code>, each function call returns a different document node. As a consequence, document instances created by this function will not be kept in memory until the end of query evaluation.<br/>The {{Code|$options}} argument can be used to change the parsing behavior. Allowed options are all [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options in lower case. Options can be specified either...<br />
+
|Fetches the resource referred to by the given {{Code|$uri}} and returns it as an XML document.<br/>In contrast to <code>fn:doc</code>, each function call returns a different document node. As a consequence, document instances created by this function will not be kept in memory until the end of query evaluation.<br/>The {{Code|$options}} argument can be used to change the parsing behavior. Allowed options are all [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options in lower case.
* as children of an {{Code|<options/>}} element, e.g.
 
<pre class="brush:xml">
 
<options>
 
  <chop value='false'/>
 
</options>
 
</pre>
 
* or as map, which contains all key/value pairs:
 
<pre class="brush:xquery">
 
map { "chop": false() }
 
</pre>
 
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 69: Line 59:
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code><nowiki>fetch:xml("http://en.wikipedia.org")</nowiki></code> returns an XML representation of the English Wikipedia main HTML page.
+
* <code><nowiki>fetch:xml("http://en.wikipedia.org", map { 'chop': true()))</nowiki></code> returns an XML representation of the English Wikipedia main HTML page and chops all whitespace nodes.
 
|}
 
|}
  

Revision as of 15:36, 24 June 2015

This XQuery Module provides simple functions to fetch the content of resources identified by URIs. Resources can be stored locally or remotely and e.g. use the file:// or http:// scheme. If more control over HTTP requests is required, the HTTP Module can be used. With the HTML Module, retrieved HTML documents can be converted to XML.

Conventions

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

Functions

fetch:binary

Signatures fetch:binary($uri as xs:string) as xs:base64Binary
Summary Fetches the resource referred to by the given URI and returns it as streamable xs:base64Binary.
Errors BXFE0001: the URI could not be resolved, or the resource could not be retrieved.
Examples
  • fetch:binary("http://images.trulia.com/blogimg/c/5/f/4/679932_1298401950553_o.jpg") returns the addressed image.
  • stream:materialize(fetch:binary("http://en.wikipedia.org")) returns a materialized representation of the streamable result.

fetch:text

Signatures fetch:text($uri as xs:string) as xs:string
fetch:text($uri as xs:string, $encoding as xs:string) as xs:string
Summary Fetches the resource referred to by the given URI and returns it as streamable xs:string.
Errors BXFE0001: the URI could not be resolved, or the resource could not be retrieved. Invalid XML characters will be ignored if the CHECKSTRINGS option is turned off.
BXFE0002: the specified encoding is not supported, or unknown.
Examples
  • fetch:text("http://en.wikipedia.org") returns a string representation of the English Wikipedia main HTML page.
  • stream:materialize(fetch:text("http://en.wikipedia.org")) returns a materialized representation of the streamable result.

fetch:xml

Signatures fetch:xml($uri as xs:string) as document-node()
fetch:xml($uri as xs:string, $options as map(xs:string, item())) as document-node()
Summary Fetches the resource referred to by the given $uri and returns it as an XML document.
In contrast to fn:doc, each function call returns a different document node. As a consequence, document instances created by this function will not be kept in memory until the end of query evaluation.
The $options argument can be used to change the parsing behavior. Allowed options are all parsing and XML parsing options in lower case.
Errors BXFE0001: the URI could not be resolved, or the resource could not be retrieved.
Examples
  • fetch:xml("http://en.wikipedia.org", map { 'chop': true())) returns an XML representation of the English Wikipedia main HTML page and chops all whitespace nodes.

fetch:content-type

Signatures fetch:content-type($uri as xs:string) as xs:string
Summary Returns the content-type (also called mime-type) of the resource specified by $uri:
  • If a remote resource is addressed, the request header will be evaluated.
  • If the addressed resource is locally stored, the content-type will be guessed based on the file extension.
Errors BXFE0001: the URI could not be resolved, or the resource could not be retrieved.
Examples
  • fetch:content-type("http://docs.basex.org/skins/vector/images/wiki.png") returns image/png.

Errors

Code Description
BXFE0001 The URI could not be resolved, or the resource could not be retrieved.
BXFE0002 The specified encoding is not supported, or unknown.

Changelog

Version 8.0

The module was introduced with Version 7.6.