Difference between revisions of "Fetch Module"
Jump to navigation
Jump to search
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>") Tags: Mobile web edit Mobile edit |
|||
(8 intermediate revisions by the same user not shown) | |||
Line 13: | Line 13: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>fetch:binary( |
+ | $href as xs:string | ||
+ | ) as xs:base64Binary</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Fetches the resource referred to by the given | + | |Fetches the resource referred to by the given {{Code|href}} string and returns it as [[Lazy Module|lazy]] {{Code|xs:base64Binary}} item. |
|- valign="top" | |- valign="top" | ||
| '''Errors''' | | '''Errors''' | ||
Line 32: | Line 34: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>fetch:text( |
+ | $href as xs:string, | ||
+ | $encoding as xs:string := (), | ||
+ | $fallback as xs:boolean? := false() | ||
+ | ) as xs:string</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Fetches the resource referred to by the given {{Code| | + | |Fetches the resource referred to by the given {{Code|href}} string and returns it as [[Lazy Module|lazy]] {{Code|xs:string}} item: |
* The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | * The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | ||
* By default, invalid characters will be rejected. If {{Code|$fallback}} is set to true, these characters will be replaced with the Unicode replacement character <code>FFFD</code> (�). | * By default, invalid characters will be rejected. If {{Code|$fallback}} is set to true, these characters will be replaced with the Unicode replacement character <code>FFFD</code> (�). | ||
Line 54: | Line 60: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>fetch:doc( |
+ | $href as xs:string, | ||
+ | $options as map(*)? := map { } | ||
+ | ) as document-node()</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Fetches the resource referred to by the given {{Code| | + | |Fetches the resource referred to by the given {{Code|href}} string and returns it as a document node.<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.<br/>The function differs from {{Code|fn:doc}} in various aspects: |
− | * It is '' | + | * It is ''nondeterministic'', i.e., a new document node will be created by each call of this function. |
* A document created by this function will be garbage-collected as soon as it is not referenced anymore. | * A document created by this function will be garbage-collected as soon as it is not referenced anymore. | ||
* URIs will not be resolved against existing databases. As a result, it will not trigger any locks (see [[Transaction Management#Limitations|limitations of database locking]] for more details). | * URIs will not be resolved against existing databases. As a result, it will not trigger any locks (see [[Transaction Management#Limitations|limitations of database locking]] for more details). | ||
Line 69: | Line 78: | ||
| | | | ||
* Retrieve an XML representation of the English Wikipedia main HTML page with whitespace stripped: | * Retrieve an XML representation of the English Wikipedia main HTML page with whitespace stripped: | ||
− | < | + | <pre lang='xquery'> |
fetch:doc("http://en.wikipedia.org", map { 'stripws': true() }) | fetch:doc("http://en.wikipedia.org", map { 'stripws': true() }) | ||
− | </ | + | </pre> |
* Return a web page as XML, preserve namespaces: | * Return a web page as XML, preserve namespaces: | ||
− | < | + | <pre lang='xquery'> |
fetch:doc( | fetch:doc( | ||
'http://basex.org/', | 'http://basex.org/', | ||
Line 81: | Line 90: | ||
} | } | ||
) | ) | ||
− | </ | + | </pre> |
|} | |} | ||
Line 88: | Line 97: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>fetch:binary-doc( |
+ | $input as xs:anyAtomicType, | ||
+ | $options as map(*)? := map { } | ||
+ | ) as document-node()</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
Line 97: | Line 109: | ||
| | | | ||
* Retrieves file input as binary data and parses it as XML: | * Retrieves file input as binary data and parses it as XML: | ||
− | < | + | <pre lang='xquery'> |
fetch:binary-doc(file:read-binary('doc.xml')) | fetch:binary-doc(file:read-binary('doc.xml')) | ||
− | </ | + | </pre> |
* Encodes a string as CP1252 and parses it as XML. The input and the string {{Code|touché}} will be correctly decoded because of the XML declaration: | * Encodes a string as CP1252 and parses it as XML. The input and the string {{Code|touché}} will be correctly decoded because of the XML declaration: | ||
− | < | + | <pre lang='xquery'> |
fetch:binary-doc(convert:string-to-base64( | fetch:binary-doc(convert:string-to-base64( | ||
"<?xml version='1.0' encoding='CP1252'?><xml>touché</xml>", | "<?xml version='1.0' encoding='CP1252'?><xml>touché</xml>", | ||
"CP1252" | "CP1252" | ||
)) | )) | ||
− | </ | + | </pre> |
* Encodes a string as UTF-16 and parses it as XML. The document will be correctly decoded, as the first bytes of the data indicate that the input must be UTF-16: | * Encodes a string as UTF-16 and parses it as XML. The document will be correctly decoded, as the first bytes of the data indicate that the input must be UTF-16: | ||
− | < | + | <pre lang='xquery'> |
fetch:binary-doc(convert:string-to-base64("<xml/>", "UTF16")) | fetch:binary-doc(convert:string-to-base64("<xml/>", "UTF16")) | ||
− | </ | + | </pre> |
|- valign="top" | |- valign="top" | ||
| '''Errors''' | | '''Errors''' | ||
Line 120: | Line 132: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>fetch:content-type( |
+ | $href as xs:string | ||
+ | ) as xs:string</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the content-type (also called mime-type) of the resource specified by {{Code| | + | |Returns the content-type (also called mime-type) of the resource specified by {{Code|href}} string: |
* If a remote resource is addressed, the request header will be evaluated. | * 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. | * If the addressed resource is locally stored, the content-type will be guessed based on the file extension. |
Latest revision as of 17:34, 1 December 2023
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 Client Module can be used. With the HTML Module, retrieved HTML documents can be converted to XML.
Contents
Conventions[edit]
All functions and errors in this module are assigned to the http://basex.org/modules/fetch
namespace, which is statically bound to the fetch
prefix.
URI arguments can point be URLs or point to local files. Relative file paths will be resolved against the current working directory (for more details, have a look at the File Module).
Functions[edit]
fetch:binary[edit]
Signature | fetch:binary( $href as xs:string ) as xs:base64Binary |
Summary | Fetches the resource referred to by the given href string and returns it as lazy xs:base64Binary item.
|
Errors | open : the URI could not be resolved, or the resource could not be retrieved.
|
Examples |
|
fetch:text[edit]
Signature | fetch:text( $href as xs:string, $encoding as xs:string := (), $fallback as xs:boolean? := false() ) as xs:string |
Summary | Fetches the resource referred to by the given href string and returns it as lazy xs:string item:
|
Errors | open : the URI could not be resolved, or the resource could not be retrieved.encoding : the specified encoding is not supported, or unknown.
|
Examples |
|
fetch:doc[edit]
Signature | fetch:doc( $href as xs:string, $options as map(*)? := map { } ) as document-node() |
Summary | Fetches the resource referred to by the given href string and returns it as a document node.The $options argument can be used to change the parsing behavior. Allowed options are all parsing and XML parsing options in lower case.The function differs from fn:doc in various aspects:
|
Errors | open : the URI could not be resolved, or the resource could not be retrieved.
|
Examples |
fetch:doc("http://en.wikipedia.org", map { 'stripws': true() })
fetch:doc(
'http://basex.org/',
map {
'parser': 'html',
'htmlparser': map { 'nons': false() }
}
)
|
fetch:binary-doc[edit]
Signature | fetch:binary-doc( $input as xs:anyAtomicType, $options as map(*)? := map { } ) as document-node() |
Summary | Converts the specified $input (xs:base64Binary , xs:hexBinary ) to XML and returns it as a document node.In contrast to fn:parse-xml , which expects a string, the input can be arbitrarily encoded. The encoding will be derived from the XML declaration or (in case of UTF-16 or UTF-32) from the first bytes of the input.The $options argument can be used to change the parsing behavior. Allowed options are all parsing and XML parsing options in lower case.
|
Examples |
fetch:binary-doc(file:read-binary('doc.xml'))
fetch:binary-doc(convert:string-to-base64(
"<?xml version='1.0' encoding='CP1252'?><xml>touché</xml>",
"CP1252"
))
fetch:binary-doc(convert:string-to-base64("<xml/>", "UTF16"))
|
Errors | open : the input could not be parsed.
|
fetch:content-type[edit]
Signature | fetch:content-type( $href as xs:string ) as xs:string |
Summary | Returns the content-type (also called mime-type) of the resource specified by href string:
|
Errors | open : the URI could not be resolved, or the resource could not be retrieved.
|
Examples |
|
Errors[edit]
Code | Description |
---|---|
encoding
|
The specified encoding is not supported, or unknown. |
open
|
The URI could not be resolved, or the resource could not be retrieved. |
Changelog[edit]
- Version 10.0
- Updated:
fetch:doc
renamed (before:fetch:xml
). - Updated:
fetch:binary-doc
renamed (before:fetch:xml-binary
).
- Version 9.0
- Added:
fetch:xml-binary
- Updated: error codes updated; errors now use the module namespace
- Version 8.5
- Updated:
fetch:text
:$fallback
argument added.
- Version 8.0
- Added:
fetch:xml
The module was introduced with Version 7.6.