4:54 p.m.
Mostly for the sake of practice I've implemented an XEmacs Lisp
binding for the libcurl WWW library's "easy" API as an ELL. It seems
fast, but it's not obvious that it has huge advantages over the
existing url.el and EFS, and the interface is very low-level.
Use of this module is not for the faint of heart. Many useful
operations are unimplemented, and the available interface is very
low-level and noninteractive. I don't have time right now to put it
into shape for addition to the XEmacs distribution, and don't plan to
work on it for a while, so I offer it on an "as-is" basis.
The following build instructions are for 21.5 and are untested. I
definitely will help with building, so feel free to ask. I don't see
why this module won't work with 21.4, so you're welcome to try and
send me bug reports. For now I think you can post to xemacs-beta
(which I read every day), and that might be useful to others.
To prepare, you need to install libcurl library and headers. To add
the module to your XEmacs tree, cd to the $srcdir/module directory,
and check it out from CVS:
cvs -d $CVSROOT checkout -d curl XEmacs/packages/unsupported/stephen/curl
where CVSROOT is whatever you normally use for checking out XEmacs.
Now cd back to $srcdir, and apply the patch:
patch -p1 < modules/curl/build.patch
Regenerate configure with "autoconf", configure --with-libcurl (and
your usual configuration options), and build as usual. It should also
be possible to build curl_api outside of the XEmacs source tree, but
I've not tried, and don't know how myself yet. Documentation welcome!
It turns out that the modules directory is not on the Lisp load path
at all. You need to either use `(require 'curl "path/to/curl.el")' or
copy curl.el to your load-path. This evaluates `(require 'curl_api
"curl/curl_api")', which works for me in a run-in-place environment,
but YMMV.
None of the functions are autoloaded or interactive yet. The file
curl-tests.el in the distribution contains some code that you can
evaluate in *scratch*.
What follows is the README:
XEmacs Lisp binding for libcurl
===============================
libcurl is the library API for cURL. Documentation is available at
http://curl.haxx.se/.
This is primarily a C module, not a Lisp library. There is a Lisp library
which initializes some data structures and requires the module; this
structure will probably be changed in the future.
The current version of the module exposes the libcurl "easy" interface via
the following Lisp API. It adds one object type, "URL handle", and the
functions and variables listed below.
The naming scheme will seem a little odd. My intention is to unify a number
of different URL handling implementations, probably including EFS, TRAMP and
libneon, under the url-handle interface. The generic interface will use the
url-handle-* namespace. The curl-* API provides low-level, library-specific
functions. These functions are generally named after either a library API
(eg, `curl-easy-perform' actually accesses the resource pointed to by the
URL), or the generic API it implements (`curl-make-url-handle').
Currently there are no generic equivalents to the libcurl wrappers. This is
intentional; I want to implement at least one more lowlevel API before
starting to design the generic APIs.
I do not have immediate plans to implement the libcurl "multi" and
"shared"
interfaces. It should be easy, and patches and suggestions are welcome.
DEFUN ("url-handle-p", Furl_handle_p, 1, 1, 0, /*
Return t if OBJECT is a URL_Handle connection. */
(object))
DEFUN ("url-handle-type", Furl_handle_type, 1, 1, 0, /*
Return the type of URL-HANDLE, a symbol. */
(url_handle))
DEFUN ("url-handle-live-p", Furl_handle_live_p, 1, 1, 0, /*
Return non-nil if URL_HANDLE is an active URL_HANDLE connection. */
(url_handle))
DEFUN ("url-handle-property-list", Furl_handle_host, 1, 1, 0, /*
Return the property list of URL-HANDLE. */
(url_handle))
DEFUN ("curl-make-url-handle", Fcurl_make_url_handle, 1, 3, 0, /*
Return a cURL handle for URL, wrapped in an url-handle.
URL is a string, which must be a URI scheme known to cURL.
URL is encoded according to optional argument CODESYS. (Of course cURL will
URL-encode it before sending it off.)
PLIST is a property list. These properties are set on the cURL handle.
#### This interface may change to (&rest PLIST). */
(url, codesys, plist))
DEFUN ("curl-easy-setopt", Fcurl_easy_setopt, 3, 3, 0, /*
Set OPTION to VALUE on curl url-handle HANDLE and return t.
OPTION is a string denoting an option in `curl-option-hash-table'.
VALUE must be of the appropriate type.
HANDLE must be an url-handle object of type `curl'.
A wrapper with some validation for libcurl's `curl_easy_setopt'.
Errors without useful explanations probably mean `curl-option-hash-table'
is corrupt. */
(option, value, handle))
DEFUN ("curl-easy-perform", Fcurl_easy_perform, 1, 2, 0, /*
Read from the URL represented by HANDLE into BUFFER at point.
Optional BUFFER defaults to the current buffer.
Returns t. */
(handle, buffer))
DEFUN ("curl-easy-getinfo", Fcurl_easy_getinfo, 2, 2, 0, /*
Return the value of ATTRIBUTE for HANDLE.
ATTRIBUTE is a string denoting an attribute in `curl-info-hash-table'.
HANDLE must be an url-handle object of type `curl'.
A wrapper with some validation for libcurl's `curl_easy_getinfo'.
Errors without useful explanations probably mean `curl-info-hash-table'
is corrupt. */
(attribute, handle))
DEFVAR_LISP ("curl-option-hash-table", &Vcurl_option_hash_table /*
Table of options available for `curl-easy-setopt'.
Key are strings naming options. The option names are taken from enum
CURLoption in <curl/curl.h>. They are all uppercase, and the "CURLOPT_"
prefix is omitted.
Values are lists containing a type symbol \(one of `long', `objectpoint',
`functionpoint', and `off_t') and an integer, which is the option index.
It is planned to add a list of Lisp types that can be converted to something
that is useful for the option as the 3rd element of the value list.
It is planned to add the leading comments as docstrings, to be the 4th
element of the value list corresponding to each key. */ );
Vcurl_option_hash_table = Qnil;
DEFVAR_LISP ("curl-info-hash-table", &Vcurl_info_hash_table /*
Table of attributes accessible via `curl-easy-getinfo'.
Keys are strings naming attributes. The attribute names are taken from
enum CURLinfo in <curl/curl.h>. They are all uppercase, and the
"CURLINFO_"
prefix is omitted.
Values are lists containing a type symbol (one of `long', `string',
`double', and `list') and an integer, which is the attribute index.
It is planned to add docstrings, to be the 3rd element of the value list
corresponding to each key. */ );
Vcurl_info_hash_table = Qnil;
--
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Ask not how you can "do" free software business;
ask what your business can "do for" free software.