README.rst (7208B)
1 |build-status| |melpa-badge| |melpa-stable-badge| 2 3 ==================================== 4 request.el -- an elisp HTTP library 5 ==================================== 6 7 Uses ``curl`` as its backend or emacs's native ``url.el`` library if ``curl`` is not found. 8 9 The default encoding for requests is ``utf-8``. Please explicitly specify ``:encoding 'binary`` for binary data. 10 11 Install 12 ======= 13 As described in `Getting started`_, ensure melpa's whereabouts in ``init.el`` or ``.emacs``:: 14 15 (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/")) 16 17 Then 18 19 :: 20 21 M-x package-refresh-contents RET 22 M-x package-install RET request RET 23 24 Alternatively, directly clone this repo and ``make install``. 25 26 Examples 27 ======== 28 GET: 29 30 .. code:: emacs-lisp 31 32 (request 33 "http://httpbin.org/get" 34 :params '(("key" . "value") ("key2" . "value2")) 35 :parser 'json-read 36 :success (cl-function 37 (lambda (&key data &allow-other-keys) 38 (message "I sent: %S" (assoc-default 'args data))))) 39 40 POST: 41 42 .. code:: emacs-lisp 43 44 (request 45 "http://httpbin.org/post" 46 :type "POST" 47 :data '(("key" . "value") ("key2" . "value2")) 48 ;; :data "key=value&key2=value2" ; this is equivalent 49 :parser 'json-read 50 :success (cl-function 51 (lambda (&key data &allow-other-keys) 52 (message "I sent: %S" (assoc-default 'form data))))) 53 54 Block until completion: 55 56 .. code:: emacs-lisp 57 58 (request 59 "http://httpbin.org/get" 60 :sync t 61 :complete (cl-function 62 (lambda (&key response &allow-other-keys) 63 (message "Done: %s" (request-response-status-code response))))) 64 65 Curl authentication: 66 67 .. code:: emacs-lisp 68 69 (request 70 "http://httpbin.org/get" 71 :auth "digest" ;; or "basic", "anyauth", etc., which see curl(1) 72 :complete (cl-function 73 (lambda (&key response &allow-other-keys) 74 (message "Done: %s" (request-response-status-code response))))) 75 76 Request binary data: 77 78 .. code:: emacs-lisp 79 80 (request 81 "http://httpbin.org/get" 82 :encoding 'binary 83 :complete (cl-function 84 (lambda (&key response &allow-other-keys) 85 (message "Done: %s" (request-response-status-code response))))) 86 87 POST file (**WARNING**: it will send the contents of the current buffer!): 88 89 .. code:: emacs-lisp 90 91 (request 92 "http://httpbin.org/post" 93 :type "POST" 94 :files `(("current buffer" . ,(current-buffer)) 95 ("data" . ("data.csv" :data "1,2,3\n4,5,6\n"))) 96 :parser 'json-read 97 :success (cl-function 98 (lambda (&key data &allow-other-keys) 99 (message "I sent: %S" (assoc-default 'files data))))) 100 101 Rich callback dispatch (like `jQuery.ajax`): 102 103 .. code:: emacs-lisp 104 105 (request 106 "http://httpbin.org/status/418" ; try other codes, for example: 107 ;; "http://httpbin.org/status/200" ; success callback will be called. 108 ;; "http://httpbin.org/status/400" ; you will see "Got 400." 109 :parser 'buffer-string 110 :success 111 (cl-function (lambda (&key data &allow-other-keys) 112 (when data 113 (with-current-buffer (get-buffer-create "*request demo*") 114 (erase-buffer) 115 (insert data) 116 (pop-to-buffer (current-buffer)))))) 117 :error 118 (cl-function (lambda (&rest args &key error-thrown &allow-other-keys) 119 (message "Got error: %S" error-thrown))) 120 :complete (lambda (&rest _) (message "Finished!")) 121 :status-code '((400 . (lambda (&rest _) (message "Got 400."))) 122 (418 . (lambda (&rest _) (message "Got 418."))))) 123 124 Flexible PARSER option: 125 126 .. code:: emacs-lisp 127 128 (request 129 "https://github.com/tkf/emacs-request/commits/master.atom" 130 ;; Parse XML in response body: 131 :parser (lambda () (libxml-parse-xml-region (point) (point-max))) 132 :success (cl-function 133 (lambda (&key data &allow-other-keys) 134 ;; Just don't look at this function.... 135 (let ((get (lambda (node &rest names) 136 (if names 137 (apply get 138 (first (xml-get-children 139 node (car names))) 140 (cdr names)) 141 (first (xml-node-children node)))))) 142 (message "Latest commit: %s (by %s)" 143 (funcall get data 'entry 'title) 144 (funcall get data 'entry 'author 'name)))))) 145 146 PUT JSON data: 147 148 .. code:: emacs-lisp 149 150 (request 151 "http://httpbin.org/put" 152 :type "PUT" 153 :data (json-encode '(("key" . "value") ("key2" . "value2"))) 154 :headers '(("Content-Type" . "application/json")) 155 :parser 'json-read 156 :success (cl-function 157 (lambda (&key data &allow-other-keys) 158 (message "I sent: %S" (assoc-default 'json data))))) 159 160 PUT JSON data including non-ascii strings: 161 162 .. code:: emacs-lisp 163 164 (request 165 "http://httpbin.org/put" 166 :type "PUT" 167 :data (json-encode '(("key" . "値1") ("key2" . "値2"))) 168 :headers '(("Content-Type" . "application/json")) 169 :parser 'json-read 170 :encoding 'utf-8 171 :success (cl-function 172 (lambda (&key data &allow-other-keys) 173 (message "I sent: %S" (assoc-default 'json data))))) 174 175 Another PUT JSON example (nested JSON using alist structure, how to represent a boolean & how to selectively evaluate lisp): 176 177 .. code:: emacs-lisp 178 179 ;; (1) Prepend alist structure with a backtick (`) rather than single quote (') 180 ;; to allow elisp evaluation of selected elements prefixed with a comma (,) 181 ;; (2) This value is expected as a boolean so use the nil / t elisp alist denotation 182 ;; (3) The function will be evaluated as it has been prefixed with a comma (,) 183 (request 184 "http://httpbin.org/put" 185 :type "PUT" 186 :data (json-encode `(("jsonArray" . (("item1" . "value 1") ;; (1) 187 ("item2" . t) ;; (2) 188 ("item3" . ,(your-custom-elisp-function)))))) ;; (3) 189 :headers '(("Content-Type" . "application/json")) 190 :parser 'json-read 191 :success (cl-function 192 (lambda (&key data &allow-other-keys) 193 (message "I sent: %S" (assoc-default 'json data))))) 194 195 GET with Unix domain socket data: 196 197 .. code:: emacs-lisp 198 199 (request 200 "http:/hello.txt" 201 :unix-socket "/tmp/app.sock" 202 :parser (lambda () (buffer-string)) 203 :success (cl-function 204 (lambda (&key data &allow-other-keys) 205 (message "Got: %s" data)))) 206 207 208 Legacy documentation 209 ==================== 210 * `Github Pages <http://tkf.github.com/emacs-request/>` 211 212 .. |build-status| 213 image:: https://secure.travis-ci.org/tkf/emacs-request.svg 214 ?branch=master 215 :target: http://travis-ci.org/tkf/emacs-request 216 :alt: Build Status 217 .. |melpa-badge| 218 image:: http://melpa.org/packages/request-badge.svg 219 :target: http://melpa.org/#/request 220 :alt: MELPA Badge 221 .. |melpa-stable-badge| 222 image:: http://stable.melpa.org/packages/request-badge.svg 223 :target: http://stable.melpa.org/#/request 224 :alt: MELPA Stable Badge 225 .. _Getting started: http://melpa.org/#/getting-started