/usr/lib/swi-prolog/doc/Manual/url.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section A.26</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="ugraphs.html">
<LINK REL=next HREF="hack.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="ugraphs.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="hack.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:A.26"><SPAN class="sec-nr">A.26</SPAN> <SPAN class="sec-title">library(url): 
Analysing and constructing URL</SPAN></A></H2>

<P><A NAME="sec:url"></A>

<DL>
<DT><B>author</B><DD>- Jan Wielemaker <BR>
- Lukas Faulstich
<DT><B>deprecated</B><DD> New code should use library(uri), provided by 
the <CODE>clib</CODE> package.
</DL>

<P>This library deals with the analysis and construction of a URL, 
Universal Resource Locator. URL is the basis for communicating locations 
of resources (data) on the web. A URL consists of a protocol identifier 
(e.g. HTTP, FTP, and a protocol-specific syntax further defining the 
location. URLs are standardized in RFC-1738.

<P>The implementation in this library covers only a small portion of the 
defined protocols. Though the initial implementation followed RFC-1738 
strictly, the current is more relaxed to deal with frequent violations 
of the standard encountered in practical use.

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="global_url/3"><STRONG>global_url</STRONG>(<VAR>+URL, 
+Base, -Global</VAR>)</A></DT>
<DD class="defbody">
Translate a possibly relative <VAR>URL</VAR> into an absolute one.

<DL>
<DT><B>Errors</B><DD> syntax_error(illegal_url) if <VAR>URL</VAR> is not 
legal.
</DL>

</DD>
<DT class="pubdef"><A NAME="is_absolute_url/1"><STRONG>is_absolute_url</STRONG>(<VAR>+URL</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>URL</VAR> is an absolute <VAR>URL</VAR>. That is, a <VAR>URL</VAR> 
that starts with a protocol identifier.</DD>
<DT class="pubdef"><A NAME="http_location/2"><STRONG>http_location</STRONG>(<VAR>?Parts, 
?Location</VAR>)</A></DT>
<DD class="defbody">
Construct or analyze an HTTP location. This is similar to
<A class="pred" href="url.html#parse_url/2">parse_url/2</A>, but only 
deals with the location part of an HTTP URL. That is, the path, search 
and fragment specifiers. In the HTTP protocol, the first line of a 
message is

<PRE class="code">
&lt;Action&gt; &lt;Location&gt; HTTP/&lt;version&gt;
</PRE>

<TABLE class="paramlist">
<TR VALIGN=top><TD><VAR>Location</VAR> </TD><TD>Atom or list of 
character codes. </TD></TR>
</TABLE>

</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="parse_url/2"><STRONG>parse_url</STRONG>(<VAR>+URL, 
-Attributes</VAR>)</A></DT>
<DD class="defbody">
Construct or analyse a <VAR>URL</VAR>. <VAR>URL</VAR> is an atom holding 
a <VAR>URL</VAR> or a variable. Parts is a list of components. Each 
component is of the format Name(Value). Defined components are:

<DL class="latex">
<DT><STRONG>protocol</STRONG>(<VAR>Protocol</VAR>)</DT>
<DD class="defbody">
The used protocol. This is, after the optional <CODE>url:</CODE>, an 
identifier separated from the remainder of the <VAR>URL</VAR> using :.
<A class="pred" href="url.html#parse_url/2">parse_url/2</A> assumes the <CODE>http</CODE> 
protocol if no protocol is specified and the <VAR>URL</VAR> can be 
parsed as a valid HTTP url. In addition to the RFC-1738 specified 
protocols, the <CODE>file</CODE> protocol is supported as well.
</DD>
<DT><STRONG>host</STRONG>(<VAR>Host</VAR>)</DT>
<DD class="defbody">
Host-name or IP-address on which the resource is located. Supported by 
all network-based protocols.
</DD>
<DT><STRONG>port</STRONG>(<VAR>Port</VAR>)</DT>
<DD class="defbody">
Integer port-number to access on the <CODE>\</CODE>arg{Host}. This only 
appears if the port is explicitly specified in the <VAR>URL</VAR>. 
Implicit default ports (e.g., 80 for HTTP) do <I>not</I> appear in the 
part-list.
</DD>
<DT><STRONG>path</STRONG>(<VAR>Path</VAR>)</DT>
<DD class="defbody">
(File-) path addressed by the <VAR>URL</VAR>. This is supported for the
<CODE>ftp</CODE>, <CODE>http</CODE> and <CODE>file</CODE> protocols. If 
no path appears, the library generates the path <CODE>/</CODE>.
</DD>
<DT><STRONG>search</STRONG>(<VAR>ListOfNameValue</VAR>)</DT>
<DD class="defbody">
Search-specification of HTTP <VAR>URL</VAR>. This is the part after the
<CODE>?</CODE>, normally used to transfer data from HTML forms that use 
the <CODE>GET</CODE> protocol. In the <VAR>URL</VAR> it consists of a 
www-form-encoded list of Name=Value pairs. This is mapped to a list of 
Prolog Name=Value terms with decoded names and values.
</DD>
<DT><STRONG>fragment</STRONG>(<VAR>Fragment</VAR>)</DT>
<DD class="defbody">
Fragment specification of HTTP <VAR>URL</VAR>. This is the part after 
the <CODE>#</CODE> character.
</DD>
</DL>

<P>The example below illustrates the all this for an HTTP <VAR>URL</VAR>.

<PRE class="code">
?- parse_url('http://swi.psy.uva.nl/message.cgi?msg=Hello+World%21#x', P).

P = [ protocol(http),
      host('swi.psy.uva.nl'),
      fragment(x),
      search([ msg = 'Hello World!'
             ]),
      path('/message.cgi')
    ]
</PRE>

<P>By instantiating the parts-list this predicate can be used to create 
a <VAR>URL</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="parse_url/3"><STRONG>parse_url</STRONG>(<VAR>+URL, 
+BaseURL, -Attributes</VAR>)</A></DT>
<DD class="defbody">
Similar to <A class="pred" href="url.html#parse_url/2">parse_url/2</A> 
for relative URLs. If <VAR>URL</VAR> is relative, it is resolved using 
the absolute <VAR>URL</VAR> <VAR>BaseURL</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="www_form_encode/2"><STRONG>www_form_encode</STRONG>(<VAR>+Value, 
-XWWWFormEncoded</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="www_form_encode/2"><STRONG>www_form_encode</STRONG>(<VAR>-Value, 
+XWWWFormEncoded</VAR>)</A></DT>
<DD class="defbody">
En/Decode between native value and application/x-www-form-encoded. Maps 
space to +, keeps alnum, maps anything else to <CODE>%XX</CODE> and 
newlines to <CODE>%OD%OA</CODE>. When decoding, newlines appear as a 
single newline (10) character.</DD>
<DT class="pubdef"><span class="pred-tag">[semidet]</span><A NAME="set_url_encoding/2"><STRONG>set_url_encoding</STRONG>(<VAR>?Old, 
+New</VAR>)</A></DT>
<DD class="defbody">
Query and set the encoding for URLs. The default is <CODE>utf8</CODE>. 
The only other defined value is <CODE>iso_latin_1</CODE>.

<DL>
<DT><B>To be done</B><DD> Having a global flag is highly inconvenient, 
but a work-around for old sites using ISO Latin 1 encoding.
</DL>

</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="url_iri/2"><STRONG>url_iri</STRONG>(<VAR>+Encoded, 
-Decoded</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="url_iri/2"><STRONG>url_iri</STRONG>(<VAR>-Encoded, 
+Decoded</VAR>)</A></DT>
<DD class="defbody">
Convert between a URL, encoding in US-ASCII and an IRI. An IRI is a 
fully expanded Unicode string. Unicode strings are first encoded into 
UTF-8, after which %-encoding takes place.</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="parse_url_search/2"><STRONG>parse_url_search</STRONG>(<VAR>?Spec, 
?Fields:list(Name=Value)</VAR>)</A></DT>
<DD class="defbody">
Construct or analyze an HTTP search specification. This deals with form 
data using the MIME-type =application/x-www-form-urlencoded= as used in 
HTTP GET requests.</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="file_name_to_url/2"><STRONG>file_name_to_url</STRONG>(<VAR>+File, 
-URL</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[semidet]</span><A NAME="file_name_to_url/2"><STRONG>file_name_to_url</STRONG>(<VAR>-File, 
+URL</VAR>)</A></DT>
<DD class="defbody">
Translate between a filename and a file:<CODE>//</CODE> <VAR>URL</VAR>.

<DL>
<DT><B>To be done</B><DD> Current implementation does not deal with 
paths that need special encoding.
</DL>

</DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / url.html
