Skip to content

Commit

Permalink
Add. Lua-cURLv2 documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@moteus
moteus committed Sep 10, 2014
1 parent 3b9399c commit 5919390
Show file tree
Hide file tree
Showing 8 changed files with 690 additions and 9 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
\.*~
Binary file added images/bkg.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/blacktocat.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
381 changes: 372 additions & 9 deletions index.html
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,377 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>Untitled</title>
<link rel="stylesheet" type="text/css" href="default.css" />
</head>
<body>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">

<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />

<title>Lua-cURL by msva</title>
</head>

<body>

<header>
<div class="container">
<h1>Lua-cURL</h1>
<h2>Lua-cURL is aiming for a full-fledged libcurl binding (easy/multi/share interface) to the functionality of Lua</h2>

<section id="downloads">
<a href="https://github.com/msva/lua-curl/zipball/master" class="btn">Download as .zip</a>
<a href="https://github.com/msva/lua-curl/tarball/master" class="btn">Download as .tar.gz</a>
<a href="https://github.com/msva/lua-curl" class="btn btn-github"><span class="icon"></span>View on GitHub</a>
</section>
</div>
</header>

<div class="container">
<section id="main_content">
<table frame="void" rules="none">
<tr>
<th>Original Author (before of 4Q-2011):</th>
<td>Jürgen Hötzel</td>
</tr>
<tr>
<th>Current Lead Developer:</th>
<td>Vadim A. Misbakh-Soloviov</td>
</tr>
<tr>
<th>Contact:</th>
<td><a href="http://mva.name/">http://mva.name/</a></td>
</tr>
</table>
<p><a name="contents">Contents</a></p>
<ul>
<li/><a href="lcurl/index.html">lcurl</a>
<li><a href="#introduction" name="id1">Introduction</a></li>
<li><a href="#installation" name="id2">Installation</a></li>
<li>
<a href="#easy-interface" name="id3">Easy interface</a><ul>
<li><a href="#example-1-fetch-the-example-com-homepage" name="id4">Example 1: Fetch the example.com homepage</a></li>
<li><a href="#example-2-on-the-fly-file-upload" name="id5">Example 2: "On-The-Fly" file upload</a></li>
<li><a href="#example-3-posting-data" name="id6">Example 3: "Posting" data</a></li>
</ul>
</li>
<li>
<a href="#multi-interface" name="id7">Multi interface</a><ul>
<li><a href="#example-1-on-the-fly-xml-parsing" name="id8">Example 1: "On-The-Fly" XML parsing</a></li>
</ul>
</li>
<li>
<a href="#share-interface" name="id9">Share interface</a><ul>
<li><a href="#example-1-share-cookie-date-across-easy-handles" name="id10">Example 1: Share Cookie date across easy handles</a></li>
</ul>
</li>
<li>
<a href="#appendix" name="id11">Appendix</a><ul>
<li><a href="#using-ssl" name="id12">Using SSL</a></li>
</ul>
</li>
</ul>

</body></html>

<h1><a href="#id1" name="introduction">Introduction</a></h1>
<p>This project is <strong>not</strong> a fork of <a href="http://luaforge.net/projects/luacurl/">LuaCURL</a>, which is a direct mapping of parts of the <a href="http://curl.haxx.se/libcurl/c/libcurl-easy.html">libcurl-easy</a> interface.</p>
<p>The intent of Lua-cURL is to adapt the</p>
<ul>
<li>Easy Interface</li>
<li>Multi Interface</li>
<li>Shared Interface</li>
</ul><p>of <a href="http://curl.haxx.se/libcurl/c/">libcurl</a> to the functionality of Lua (for example by using iterators instead of callbacks when possible).</p>



<h1><a href="#id2" name="installation">Installation</a></h1>
<p>We now using <a href="http://cmake.org/">CMake</a> to configure, build and install. Just run:</p>
<pre>
cmake ${CMAKE_ARGUMENTS} . &amp;&amp; make ${MAKE_ARGUMENTS} install
</pre>
<p>Where <code>CMAKE_ARGUMENTS</code> may contain one or all of the following (in one space-delimited string or bash's array, without comments):</p>
<pre>
-DCMAKE_C_FLAGS="-flto"
# to use LTO (Link-Time Optimisations). Requires GCC>=4.6

-DUSE_LUAJIT=ON
# to use LuaJIT includes instead of 'C' Lua library. Requires LuaJIT>=2.0

-DCMAKE_LINKER="/usr/bin/ld.gold"
# To use 'gold' linker. Requires newer binutils.

-DUSE_LUA52=ON
# to install for Lua 5.2. Requires Lua>=5.2
</pre>
<p>And <code>MAKE_ARGUMENTS</code> may also contain one or all of the following (in one space-delimited string or bash's array, without comments):</p>
<pre>
-jN
# Where N = Number of processor cores * Number of processors + 1,
# to build in N threads, to speedup compilation (by default, -j1)

DESTDIR="<PATH>"
# Where <PATH> can be either absolute or relative prefix-path to the place,
# where you want to install Lua-cURL (by default, DESTDIR=/)
</pre>
<p>On some systems, CMake may fail to include the right lua header files.
This error can be identified at runtime, after requiring the cURL module, by the
error message "undefined symbol". In that case the module must be recompiled
specifying the include path for lua header files. This can be done with the
LUA_DIR environment variable. E.g. in a posix-compliant shell:</p>
<pre>
LUA_DIR="/usr/include/lua5.1" cmake ${CMAKE_ARGUMENTS}
</pre>



<h1><a href="#id3" name="easy-interface">Easy interface</a></h1>
<dl>
<dt><strong>cURL.easy_init()</strong></dt>
<dd>returns a new easy handle.</dd>
<dt><strong>cURL.version_info()</strong></dt>
<dd>returns a table containing version info and features/protocols sub table</dd>
<dt><strong>easy:escape(string)</strong></dt>
<dd>return URL encoded string</dd>
<dt><strong>easy:unescape(string)</strong></dt>
<dd>return URL decoded string</dd>
<dt><strong>easy:setopt*(value)</strong></dt>
<dd><dl>
<dt>libcurl properties an options are mapped to individual functions:</dt>
<dd><ul>
<li><strong>easy:setopt_url(string)</strong></li>
<li><strong>easy:setopt_verbose(number)</strong></li>
<li><strong>easy:setopt_proxytype(string)</strong></li>
<li>
<strong>easy:setopt_share(share)</strong> (See: <a href="#share">share</a>)</li>
<li>...</li>
</ul></dd>
</dl></dd>
<dt><strong>easy:perform(table)</strong></dt>
<dd><dl>
<dt>Perform the transfer as described in the options, using an optional callback table.The callback table indices are named after the equivalent cURL callbacks:</dt>
<dd><ul>
<li><strong>writefunction = function(str)</strong></li>
<li><strong>readfunction = function()</strong></li>
<li><strong>headerfunction = function(str)</strong></li>
</ul></dd>
</dl></dd>
<dt><strong>easy:post(table)</strong></dt>
<dd>
<p>Prepare a multipart/formdata post. The table indices are named after the form fields and should map to string values:</p>
<pre>
{field1 = value1,
field2 = value1}
</pre>
<p>or more generic descriptions in tables:</p>
<pre>
{field1 = {file="/tmp/test.txt",
type="text/plain"},
{field2 = {file="dummy.html",
data="&lt;html&gt;&lt;bold&gt;bold&lt;/bold&gt;&lt;/html&gt;,
type="text/html"}}
</pre>
</dd>
</dl>
<h2><a href="#id4" name="example-1-fetch-the-example-com-homepage">Example 1: Fetch the example.com homepage</a></h2>
<pre>
require("cURL")

-- open output file
f = io.open("example_homepage", "w")

c = cURL.easy_init()
-- setup url
c:setopt_url("<a href="http://www.example.com/&quot;">http://www.example.com/"</a>)
-- perform, invokes callbacks
c:perform({writefunction = function(str)
f:write(str)
end})

-- close output file
f:close()
print("Done")
</pre>



<h2><a href="#id5" name="example-2-on-the-fly-file-upload">Example 2: "On-The-Fly" file upload</a></h2>
<pre>
-- simple "On the fly" fileupload

require("cURL")

c=cURL.easy_init()
c:setopt_url("ftp://ftptest:secret0815@targethost/file.dat")
c:setopt_upload(1)
count=0
c:perform({readfunction=function(n)
count = count + 1
if (count &lt; 10) then
return "Line " .. count .. "\n"
end
return nil
end})
print("Fileupload done")
</pre>



<h2><a href="#id6" name="example-3-posting-data">Example 3: "Posting" data</a></h2>
<pre>
require("cURL")

c = cURL.easy_init()

c:setopt_url("http://localhost")
postdata = {
-- post file from filesystem
name = {file="post.lua",
type="text/plain"},
-- post file from data variable
name2 = {file="dummy.html",
data="&lt;html&gt;&lt;bold&gt;bold&lt;/bold&gt;&lt;/html&gt;",
type="text/html"}}
c:post(postdata)
c:perform()

print("Done")
</pre>


<p></p>


<h1><a href="#id7" name="multi-interface">Multi interface</a></h1>
<dl>
<dt><strong>cURL.multi_init()</strong></dt>
<dd>returns a new multi handle</dd>
<dt><strong>multi:add_handle(easy)</strong></dt>
<dd>add an easy handle to a multi session</dd>
<dt><strong>multi:perform()</strong></dt>
<dd>
<p>returns an iterator function that, each time it is called, returns the next data, type and corresponding easy handle:</p>
<blockquote>
<dl>
<dt>
<strong>data</strong>:</dt>
<dd>data returned by the cURL library</dd>
<dt><strong>type</strong></dt>
<dd>type of data returned ("header" or "data")</dd>
<dt><strong>easy</strong></dt>
<dd>corresponding easy handle of the data returned</dd>
</dl>
</blockquote>
</dd>
</dl>
<h2><a href="#id8" name="example-1-on-the-fly-xml-parsing">Example 1: "On-The-Fly" XML parsing</a></h2>
<pre>
-- use LuaExpat and Lua-CuRL together for On-The-Fly XML parsing
require("lxp")
require("cURL")

tags = {}
items = {}

callback = {}

function callback.StartElement(parser, tagname)
tags[#tags + 1] = tagname
if (tagname == "item") then
items[#items + 1] = {}
end
end

function callback.CharacterData(parser, str)
if (tags[#tags -1] == "item") then
--we are parsing a item, get rid of trailing whitespace
items[#items][tags[#tags]] = string.gsub(str, "%s*$", "")
end
end
function callback.EndElement(parser, tagname)
--assuming well formed xml
tags[#tags] = nil
end

p = lxp.new(callback)

-- create and setup easy handle
c = cURL.easy_init()
c:setopt_url("<a href="http://www.lua.org/news.rss&quot;">http://www.lua.org/news.rss"</a>)

m = cURL.multi_init()
m:add_handle(c)

for data,type in m:perform() do
-- ign "header"
if (type == "data") then
assert(p:parse(data))
end
end

--finish document
assert(p:parse())
p:close()

for i, item in ipairs(items) do
for k, v in pairs(item) do
print(k,v)
end
print()
end
</pre>


<p></p>


<h1><a href="#id9" name="share-interface">Share interface</a></h1>
<dl>
<dt><strong>cURL.share_init()</strong></dt>
<dd>returns a new share handle</dd>
<dt><strong>share:setopt_share(string)</strong></dt>
<dd>specifies the type of data that should be shared ("DNS" or "COOKIE")</dd>
</dl><p>Since Lua is single-threaded, there is no mapping for the lock options.</p>

<h2><a href="#id10" name="example-1-share-cookie-date-across-easy-handles">Example 1: Share Cookie date across easy handles</a></h2>
<pre>
-- Cookie data will be shared across the easy handles to do an authorized download
require("cURL")

-- create share handle (share COOKIE and DNS Cache)
s = cURL.share_init()
s:setopt_share("COOKIE")
s:setopt_share("DNS")

-- create first easy handle to do the login
c = cURL.easy_init()
c:setopt_share(s)
c:setopt_url("http://targethost/login.php?username=foo&amp;password=bar")

-- create second easy handle to do the download
c2 = cURL.easy_init()
c2:setopt_share(s)
c2:setopt_url("http://targethost/download.php?id=test")

--login
c:perform()

--download
c2:perform()
</pre>



<h1><a href="#id11" name="appendix">Appendix</a></h1>

<h2><a href="#id12" name="using-ssl">Using SSL</a></h2>
<p>The cert bundle distributed with cURL may be out of date and cannot validate many certificates. You can supply a different
PEM cert bundle by using <strong>easy:setopt_cainfo(string)</strong>.
Also, it is a shell script, writen by original author (Jürgen), that can be used for converting the cacert keystore distributed with the Java Runtime Environment to PEM. This script currently distributed in «examples» folder in repository</p>


<p></p>

</section>
</div>


</body>
</html>
1 change: 1 addition & 0 deletions javascripts/main.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
console.log('This would be the main JS file.');
Loading

0 comments on commit 5919390

Please sign in to comment.