Quelle  chap1.html   Sprache: HTML

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (curl) - Chapter 1: Overview</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap1"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a>   <a href="chap0.html#contents">[Contents]</a>    <a href="chap0.html">[Previous Chapter]</a>    <a href="chapInd.html">[Next Chapter]</a>   </div>

<p id="mathjaxlink" class="pcenter"><a href="chap1_mj.html">[MathJax on]</a></p>
<p><a id="X8389AD927B74BA4A" name="X8389AD927B74BA4A"></a></p>
<div class="ChapSects"><a href="chap1.html#X8389AD927B74BA4A">1 <span class="Heading">Overview</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap1.html#X852847EC87B3F9E4">1.1 <span class="Heading">Installing curlInterface</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X8286176B85B6326F">1.1-1 <span class="Heading">Linux</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X7A3117FB8072361E">1.1-2 <span class="Heading">Cygwin</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X7FF92C7E7A41189D">1.1-3 <span class="Heading">macOS</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap1.html#X86FA580F8055B274">1.2 <span class="Heading">Functions</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X7827F7DE85113D7E">1.2-1 DownloadURL</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X81A7B7017D508BE9">1.2-2 PostToURL</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X84C36A2D86B7975B">1.2-3 DeleteURL</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap1.html#X79B1452982D2B19C">1.2-4 CurlRequest</a></span>
</div></div>
</div>

<h3>1 <span class="Heading">Overview</span></h3>

<p>CurlInterface allows a user to interact with http and https servers on the internet, using the 'curl' library. Pages can be downloaded from a URL, and http POST requests can be sent to the URL for processing.</p>

<p><a id="X852847EC87B3F9E4" name="X852847EC87B3F9E4"></a></p>

<h4>1.1 <span class="Heading">Installing curlInterface</span></h4>

<p>curlInterface requires the 'curl' library, available from <span class="URL"><a href="https://curl.haxx.se/">https://curl.haxx.se/</a></span>. Instructions for building and installing curl can be found at <span class="URL"><a href="https://curl.haxx.se/docs/install.html">https://curl.haxx.se/docs/install.html</a></span>, however in most systems curl can be installed from your OS's package manager.</p>

<p><a id="X8286176B85B6326F" name="X8286176B85B6326F"></a></p>

<h5>1.1-1 <span class="Heading">Linux</span></h5>


<ul>
<li><p>On Debian and Ubuntu, call: <code class="code">apt-get install libcurl4-gnutls-dev</code></p>

</li>
<li><p>On Redhat and derivatives, call: <code class="code">yum install curl-devel</code></p>

</li>
</ul>
<p><a id="X7A3117FB8072361E" name="X7A3117FB8072361E"></a></p>

<h5>1.1-2 <span class="Heading">Cygwin</span></h5>

<p>Install <code class="code">libcurl-devel</code> from the cygwin package manager</p>

<p><a id="X7FF92C7E7A41189D" name="X7FF92C7E7A41189D"></a></p>

<h5>1.1-3 <span class="Heading">macOS</span></h5>

<p>curl is installed by default on Macs, but libcurl may be required.</p>


<ul>
<li><p>Homebrew: <code class="code">brew install curl</code></p>

</li>
<li><p>Fink: <code class="code">fink install libcurl4</code></p>

</li>
<li><p>MacPorts: <code class="code">port install curl</code></p>

</li>
</ul>
<p><a id="X86FA580F8055B274" name="X86FA580F8055B274"></a></p>

<h4>1.2 <span class="Heading">Functions</span></h4>

<p>curlInterface currently provides the following functions for interacting with URLs:</p>

<p><a id="X7827F7DE85113D7E" name="X7827F7DE85113D7E"></a></p>

<h5>1.2-1 DownloadURL</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#an style='color: green'>8227; DownloadURL</code>( <var class="Arg">URL</var>[, <var class="Arg">opts</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a record</p>

<p>Downloads a URL from the internet. <var class="Arg">URL</var> should be a string describing the address, and should start with either "http://" or "https://". For descriptions of the output and the additional argument <var class="Arg">opts</var>, see <code class="func">CurlRequest</code> (<a href="chap1.html#X79B1452982D2B19C"><span class="RefLink">1.2-4</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">r := DownloadURL("www.gap-system.org");;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">r.success;</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">r.result{[1..50]};</span>
"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n\n<!DOCTYPE "
</pre></div>

<p><a id="X81A7B7017D508BE9" name="X81A7B7017D508BE9"></a></p>

<h5>1.2-2 PostToURL</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#an style='color: green'>8227; PostToURL</code>( <var class="Arg">URL</var>, <var class="Arg">str</var>[, <var class="Arg">opts</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a record</p>

<p>Sends an HTTP POST request to a URL on the internet. <var class="Arg">URL</var> should be a string describing the address, and should start with either "http://" or "https://". <var class="Arg">str</var> should be the string which will be sent to the server as a POST request. For descriptions of the output and the additional argument <var class="Arg">opts</var>, see <code class="func">CurlRequest</code> (<a href="chap1.html#X79B1452982D2B19C"><span class="RefLink">1.2-4</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">r := PostToURL("httpbun.com/post", "animal=tiger");;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">r.success;</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">r.result{[51..100]};</span>
"\"form\": {\n    \"animal\": \"tiger\"\n  }, \n  \"headers\":"
</pre></div>

<p><a id="X84C36A2D86B7975B" name="X84C36A2D86B7975B"></a></p>

<h5>1.2-3 DeleteURL</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#an style='color: green'>8227; DeleteURL</code>( <var class="Arg">URL</var>[, <var class="Arg">opts</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a record</p>

<p>Attempts to delete a file on the internet, by sending an HTTP DELETE request to the given URL. <var class="Arg">URL</var> should be a string describing the address to be deleted, and should start with either "http://" or "https://". For descriptions of the output and the additional argument <var class="Arg">opts</var>, see <code class="func">CurlRequest</code> (<a href="chap1.html#X79B1452982D2B19C"><span class="RefLink">1.2-4</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">r := DeleteURL("www.google.com");;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">r.success;</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">r.result{[1471..1540]};</span>
"<p>The request method <code>DELETE</code> is inappropriate for the URL"
</pre></div>

<p><a id="X79B1452982D2B19C" name="X79B1452982D2B19C"></a></p>

<h5>1.2-4 CurlRequest</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#an style='color: green'>8227; CurlRequest</code>( <var class="Arg">URL</var>, <var class="Arg">type</var>, <var class="Arg">out_string</var>[, <var class="Arg">opts</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a record</p>

<p>Sends an HTTP request of type <var class="Arg">type</var> to a URL on the internet. <var class="Arg">URL</var>, <var class="Arg">type</var>, and <var class="Arg">out_string</var> should all be strings: <var class="Arg">URL</var> is the URL of the server (which should start with "http://" or "https://"), <var class="Arg">type</var> is the type of HTTP request (e.g. "GET"), and <var class="Arg">out_string</var> is the message, if any, to send to the server (in requests such as GET this will be ignored).</p>

<p>An optional fourth argument <var class="Arg">opts</var> may be included, which should be a record specifying additional options for the request. The following options are supported:</p>


<ul>
<li><p><code class="code">verifyCert</code>: a boolean describing whether to verify HTTPS certificates (corresponds to the curl options <code class="code">CURLOPT_SSL_VERIFYPEER</code> and <code class="code">CURLOPT_SSL_VERIFYHOST</code>, the default is <code class="keyw">true</code> for both);</p>

</li>
<li><p><code class="code">verbose</code>: a boolean describing whether to print extra information to the screen (corresponds to the curl option <code class="code">CURLOPT_VERBOSE</code>, the default is <code class="keyw">false</code>);</p>

</li>
<li><p><code class="code">followRedirect</code>: a boolean describing whether to follow redirection to another URL (corresponds to the curl option <code class="code">CURLOPT_FOLLOWLOCATION</code>, the default is <code class="keyw">true</code>);</p>

</li>
<li><p><code class="code">failOnError</code>: a boolean describing whether to regard 404 (and other 4xx) status codes as error (corresponds to the curl option <code class="code">CURLOPT_FAILONERROR</code>, the default is <code class="keyw">false</code>).</p>

</li>
<li><p><code class="code">maxTime</code>: Maximum time in seconds that you allow each transfer to take. 0 means no limitation. (default <code class="keyw">0</code>).</p>

</li>
</ul>
<p>As output, this function returns a record containing some of the following components, which describe the outcome of the request:</p>


<ul>
<li><p><code class="code">success</code>: a boolean describing whether the request was successfully received by the server;</p>

</li>
<li><p><code class="code">result</code>: body of the information sent by the server (only if <code class="code">success = true</code>);</p>

</li>
<li><p><code class="code">error</code>: human-readable string saying what went wrong (only if <code class="code">success = false</code>).</p>

</li>
</ul>
<p>Most of the standard HTTP request types should work, but currently only body information is returned. To see headers, consider using the <code class="code">verbose</code> option. For convenience, dedicated functions exist for the following request types:</p>


<ul>
<li><p><code class="func">DownloadURL</code> (<a href="chap1.html#X7827F7DE85113D7E"><span class="RefLink">1.2-1</span></a>) for GET requests;</p>

</li>
<li><p><code class="func">PostToURL</code> (<a href="chap1.html#X81A7B7017D508BE9"><span class="RefLink">1.2-2</span></a>) for POST requests;</p>

</li>
<li><p><code class="func">DeleteURL</code> (<a href="chap1.html#X84C36A2D86B7975B"><span class="RefLink">1.2-3</span></a>) for DELETE requests.</p>

</li>
</ul>

<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">r := CurlRequest("https://www.google.com",</span>
<span class="GAPprompt">></span> <span class="GAPinput">                    "HEAD",</span>
<span class="GAPprompt">></span> <span class="GAPinput">                    "",</span>
<span class="GAPprompt">></span> <span class="GAPinput">                    rec(verifyCert := false));</span>
rec( result := "", success := true )
<span class="GAPprompt">gap></span> <span class="GAPinput">r := CurlRequest("httpbun.com/post", "POST", "animal=tiger");;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">r.success;</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">r.result{[51..100]};</span>
"\"form\": {\n    \"animal\": \"tiger\"\n  }, \n  \"headers\":"
</pre></div>


<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a>   <a href="chap0.html#contents">[Contents]</a>    <a href="chap0.html">[Previous Chapter]</a>    <a href="chapInd.html">[Next Chapter]</a>   </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chapInd.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="https://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>