feat: Add idiomatic use of headers (#11)

Initialize and release HTTP headers adding three different ways to
to add headers.

Closes #10

Author: fraya

documentation/source/introduction.rst

@@ -202,3 +202,104 @@ wrapper, you access the information directly using property syntax.
       format-err("curl easy perform failed: %s\n",
                  err.curl-error-message)
    end block;
+
+Headers
+-------
+
+Libcurl offers manipulation of HTTP headers using `CURLOPT_HTTPHEADER`
+option.
+
+Libcurl's `CURLOPT_HTTPHEADER` option allows you to send custom HTTP
+headers with your requests.  The option accepts a linked list of
+header strings, which you build using `curl_slist` and `curl_slist_append`.
+
+.. code-block:: C
+   :caption: Libcurl example using HTTP headers
+
+   CURL *curl;
+   CURLcode res;
+
+   curl_global_init(CURL_GLOBAL_DEFAULT);
+   curl = curl_easy_init();
+
+   struct curl_slist *headers = NULL;
+   headers = curl_slist_append(headers, "Content-Type: application/json");
+   headers = curl_slist_append(headers, "Authorization: Bearer your_token_here");
+   headers = curl_slist_append(headers, "X-Custom-Header: Custom Value");
+
+   if (curl) {
+     curl_easy_setopt(curl, CURLOPT_URL, "https://api.example.com/data");
+     curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
+
+     // ... other curl options ...
+
+     res = curl_easy_perform(curl);
+
+     if (res != CURLE_OK) {
+        fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
+     }
+
+     curl_slist_free_all(headers);
+     curl_easy_cleanup(curl);
+   }
+   curl_global_cleanup();
+
+The above example could be translated to Opendylan in three ways:
+
+.. code-block:: dylan
+   :caption: Using `add-header!`
+
+   with-curl-global($curl-global-default)
+     with-curl-easy(curl = make(<curl-easy>),
+                    url = "https://api.example.com/data")
+
+       add-header!(curl,
+                   "Content-Type: application/json",
+                   "Authorization: Bearer your_token_here",
+                   "X-Custom-Header: Custom Value");
+
+       // ... other curl options ...
+
+       curl-easy-perform(curl);
+
+       end with-curl-easy;
+   end with-curl-global;
+
+Or passing the options to :macro:`with-curl-easy`:
+
+.. code-block:: dylan
+   :caption: Using `with-curl-easy` options
+
+   with-curl-global($curl-global-default)
+     with-curl-easy(curl = make(<curl-easy>),
+                    url = "https://api.example.com/data",
+                    header = "Content-Type: application/json",
+                    header = "Authorization: Bearer your_token_here",
+                    header = "X-Custom-Header: Custom Value")
+
+       // ... other curl options ...
+
+       curl-easy-perform(curl);
+
+     end with-curl-easy;
+   end with-curl-global;
+
+Or using the setter method :meth:`curl-header-setter`
+
+.. code-block:: dylan
+   :caption: Using `curl-header-setter`
+
+   with-curl-global($curl-global-default)
+     with-curl-easy(curl = make(<curl-easy>),
+                           url = "https://api.example.com/data")
+
+       curl.curl-header := "Content-Type: application/json";
+       curl.curl-header := "Authorization: Bearer your_token_here";
+       curl.curl-header := "X-Custom-Header: Custom Value";
+
+       // ... other curl options ...
+
+       curl-easy-perform(curl);
+
+     end with-curl-easy;
+   end with-curl-global;

documentation/source/reference.rst

@@ -166,7 +166,7 @@ Macros
         end;
 
    :example:
-    
+
      .. code-block:: dylan
         :caption: Passing options to macro
 
@@ -189,13 +189,13 @@ Macros
 
      .. code-block:: dylan
 
-	let curl = #f;
+        let curl = #f;
         block ()
-	  curl := make(<curl-easy>);
-	  ... body ...
-	cleanup
-	  curl-easy-cleanup(curl)
-	end block;
+          curl := make(<curl-easy>);
+          body ...
+        cleanup
+          curl-easy-cleanup(curl)
+        end block;
 
 .. dylan:macro:: with-curl-global
    :statement:
@@ -207,19 +207,19 @@ Macros
 
    :macrocall:
       .. parsed-literal::
-	 with-curl-global (*flags*) body end
+         with-curl-global (*flags*) body end
 
    :discussion:
 
       This code is equivalent to:
 
       .. code-block:: dylan
 
-	 block()
-	   curl-library-setup(flags)
-	   body;
-	 rescue
-	   curl-library-cleanup()
+         block()
+           curl-library-setup(flags)
+           body;
+         rescue
+           curl-library-cleanup()
          end;
 
    :example:
@@ -230,7 +230,7 @@ Macros
           with-curl-easy (curl)
             curl.curl-url := "https://example.com";
             curl-easy-perform(curl);
-	    // do staff
+            // retrieve information
           end;
         end with-curl-global;
 
@@ -241,6 +241,53 @@ Macros
       * :func:`curl-library-setup`
       * :func:`curl-library-cleanup`
 
+Headers
+=======
+
+.. function:: add-header!
+
+   :signature:
+
+      add-header! (*curl* #rest *headers*) => (*curl*)
+
+   :parameter curl:
+      An instance of :class:`<curl-easy>`
+   :parameter #rest headers:
+      0 or more :drm:`<string>` headers
+   :value curl:
+      An instance of :class:`<curl-easy>`
+
+   :example:
+
+      .. code-block:: dylan
+
+         add-header!("Content-type: application/json",
+                     "Authorization: Bearer you_token_here");
+
+.. method:: curl-header-setter
+   :specializer: <string>
+
+   :signature:
+
+      curl-header-setter (header curl) => (header)
+
+   :parameter curl: An instance of :class:`<curl-easy>`
+   :parameter header: An instance of :drm:`<string>`
+   :value header: An instance of :drm:`<string>`
+
+   :description:
+
+      Sets a HTTP header. Each use adds a header to the headers
+      list.
+
+      If the key is repeated the values are appended, not replaced.
+
+      .. code-block:: dylan
+
+         curl.curl-header := "X-friend: you";
+         curl.curl-header := "X-friend: her";
+         // "X-friend: you, her"
+
 Options
 =======
 

src/curl-easy-module.dylan

@@ -259,6 +259,12 @@ define module curl-easy
     curl-header-anchor,
     curl-header-anchor-setter;
 
+  // header related methods
+
+  create
+    add-header!,
+    curl-header-setter;
+
   // Curl slist
 
   create
@@ -325,8 +331,6 @@ define module curl-easy
     // curl-easy-recv,
     curl-easy-reset,
     curl-easy-unescape,
-    curl-slist-append,
-    curl-slist-free-all,
     curl-version;
 
   // callbacks

src/curl-easy.dylan

@@ -607,6 +607,8 @@ define abstract class <curl> (<object>) end;
 define open class <curl-easy> (<curl>)
   constant slot curl-handle :: <curl-easy-handle> = c-curl-easy-init(),
     init-keyword: handle:;
+  slot curl-headers :: <curlopt-slistpoint> = null-pointer(<curlopt-slistpoint>),
+    init-keyword: headers:;
 end;
 
 define method initialize
@@ -619,6 +621,7 @@ end method;
 
 define function curl-easy-cleanup
     (curl :: <curl-easy>) => ()
+  curl-slist-free-all(curl.curl-headers);
   c-curl-easy-cleanup(curl.curl-handle)
 end;
 
@@ -628,6 +631,20 @@ define function curl-easy-dup
        handle: c-curl-easy-duphandle(curl.curl-handle))
 end;
 
+define function add-header!
+    (curl :: <curl-easy>, #rest headers) => (curl :: <curl-easy>)
+  for (header in headers)
+    curl.curl-headers := curl-slist-append(curl.curl-headers, header)
+  end;
+  curl
+end;
+
+define method curl-header-setter
+    (header :: <string>, curl :: <curl-easy>) => (header :: <string>)
+  add-header!(curl, header);
+  header
+end;
+
 define function curl-easy-escape
     (curl :: <curl-easy>, url :: <string>, #key length :: false-or(<integer>) = #f)
  => (escaped-url :: <string>)
@@ -641,6 +658,11 @@ end;
 
 define function curl-easy-perform
     (curl :: <curl-easy>) => ()
+  // set headers
+  unless (null-pointer?(curl.curl-headers))
+    curl.curl-httpheader := curl.curl-headers
+  end;
+  // perform request
   let curl-code = c-curl-easy-perform(curl.curl-handle);
   unless (curl-code = $curle-ok)
     signal(make(<curl-perform-error>, code: curl-code))
@@ -649,6 +671,7 @@ end;
 
 define function curl-easy-reset
     (curl :: <curl-easy>) => ()
+  curl.curl-headers := null-pointer(<curlopt-slistpoint>);
   c-curl-easy-reset(curl.curl-handle)
 end;
 

tests/test-httpbin.dylan

@@ -47,19 +47,13 @@ define test test-auth-basic (tags: #("io", "httpbin"))
 end test;
 
 define test test-auth-bearer (tags: #("io", "httpbin"))
-  let headers = null-pointer(<curlopt-slistpoint>);
   let bearer = "hunter42";
-  block ()
-    headers := curl-slist-append(headers, concatenate("Authorization: Bearer ", bearer));
-    with-curl-easy (curl = make(<curl-easy>),
-                    url = httpbin("/bearer"),
-	                  httpheader = headers)
-      curl-easy-perform(curl);
-      assert-equal(200, curl.curl-response-code);
-    end with-curl-easy;      
-  cleanup
-      curl-slist-free-all(headers);
-  end block;
+  with-curl-easy (curl = make(<curl-easy>),
+                  url = httpbin("/bearer"))
+    curl.curl-header := concatenate("Authorization: Bearer ", bearer);
+    curl-easy-perform(curl);
+    assert-equal(200, curl.curl-response-code);
+  end with-curl-easy;
 end test test-auth-bearer;
 
 define test test-auth-digest (tags: #("io", "httpbin"))

tests/test-option-headers.dylan

@@ -5,14 +5,15 @@ License:    See License.txt in this distribution for details.
 
 define test test-option-headers (tags: #("io", "httpbin"))
   with-curl-global($curl-global-default)
-    let headers = null-pointer(<curlopt-slistpoint>);
-    headers := curl-slist-append(headers, "X-Custom-Header: Chucho");
-    headers := curl-slist-append(headers, "Another-Header: Good");
     with-curl-easy (curl = make(<curl-easy>),
                     url = httpbin("/headers"),
-                    httpheader = headers)
+                    header = "Content-Type: application/json")
+      curl.curl-header := "Authorization: Bearer your_token_here";
+      curl.curl-header := "X-friend: Foo";
+      add-header!(curl,
+                  "X-Custom-Header: Chucho",
+                  "Another-Header: Good");
       curl-easy-perform(curl);
-      curl-slist-free-all(headers);
       assert-true(#t);
     end with-curl-easy;
   end with-curl-global;