lib/curl: revamp style, doc and implementation of HeaderMap
[nit.git] / lib / curl / curl.nit
index dbfc157..02427c9 100644 (file)
 # Network functionnalities based on Curl_c module.
 module curl
 
-import curl_c
+import native_curl
 
 # Top level of Curl
 class Curl
-       protected var prim_curl = new CCurl.easy_init
 
        init
        do
@@ -29,12 +28,13 @@ class Curl
                        print "Curl must be instancied to be used"
                end
        end
+       protected var native = new NativeCurl.easy_init
 
        # Check for correct initialization
-       fun is_ok: Bool do return self.prim_curl.is_init
+       fun is_ok: Bool do return self.native.is_init
 
        # Release Curl instance
-       fun destroy do self.prim_curl.easy_clean
+       fun destroy do self.native.easy_clean
 end
 
 # CURL Request
@@ -53,10 +53,10 @@ class CurlRequest
 
                var err
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.verbose, self.verbose)
+               err = self.curl.native.easy_setopt(new CURLOption.verbose, self.verbose)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.easy_perform
+               err = self.curl.native.easy_perform
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                return null
@@ -72,17 +72,17 @@ end
 # CURL HTTP Request
 class CurlHTTPRequest
        super CurlRequest
-       super CCurlCallbacks
-       super CurlCallbacksRegisterIntern
+       super NativeCurlCallbacks
 
        var url: String
        var datas: nullable HeaderMap = null is writable
        var headers: nullable HeaderMap = null is writable
+       var delegate: nullable CurlCallbacks = null is writable
 
        # Set the user agent for all following HTTP requests
        fun user_agent=(name: String)
        do
-               curl.prim_curl.easy_setopt(new CURLOption.user_agent, name)
+               curl.native.easy_setopt(new CURLOption.user_agent, name)
        end
 
        init (url: String, curl: nullable Curl) is old_style_init do
@@ -101,37 +101,37 @@ class CurlHTTPRequest
 
                var err
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.follow_location, 1)
+               err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.url, url)
+               err = self.curl.native.easy_setopt(new CURLOption.url, url)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                # Callbacks
-               err = self.curl.prim_curl.register_callback(callback_receiver, new CURLCallbackType.header)
+               err = self.curl.native.register_callback_header(callback_receiver)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.register_callback(callback_receiver, new CURLCallbackType.body)
+               err = self.curl.native.register_callback_body(callback_receiver)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                # HTTP Header
                if self.headers != null then
                        var headers_joined = self.headers.join_pairs(": ")
-                       err = self.curl.prim_curl.easy_setopt(new CURLOption.httpheader, headers_joined.to_curlslist)
+                       err = self.curl.native.easy_setopt(new CURLOption.httpheader, headers_joined.to_curlslist)
                        if not err.is_ok then return answer_failure(err.to_i, err.to_s)
                end
 
                # Datas
                if self.datas != null then
-                       var postdatas = self.datas.to_url_encoded(self.curl.prim_curl)
-                       err = self.curl.prim_curl.easy_setopt(new CURLOption.postfields, postdatas)
+                       var postdatas = self.datas.to_url_encoded(self.curl.native)
+                       err = self.curl.native.easy_setopt(new CURLOption.postfields, postdatas)
                        if not err.is_ok then return answer_failure(err.to_i, err.to_s)
                end
 
                var err_resp = perform
                if err_resp != null then return err_resp
 
-               var st_code = self.curl.prim_curl.easy_getinfo_long(new CURLInfoLong.response_code)
+               var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
                if not st_code == null then success_response.status_code = st_code.response
 
                return success_response
@@ -147,16 +147,16 @@ class CurlHTTPRequest
 
                var err
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.follow_location, 1)
+               err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.url, url)
+               err = self.curl.native.easy_setopt(new CURLOption.url, url)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.register_callback(callback_receiver, new CURLCallbackType.header)
+               err = self.curl.native.register_callback_header(callback_receiver)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.register_callback(callback_receiver, new CURLCallbackType.stream)
+               err = self.curl.native.register_callback_stream(callback_receiver)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                var opt_name
@@ -168,28 +168,27 @@ class CurlHTTPRequest
                        return answer_failure(0, "Unable to extract file name, please specify one")
                end
 
-               success_response.i_file = new OFile.open(opt_name.to_cstring)
-               if not success_response.i_file.is_valid then
-                       success_response.i_file.close
+               success_response.file = new FileWriter.open(opt_name)
+               if not success_response.file.is_writable then
                        return answer_failure(0, "Unable to create associated file")
                end
 
                var err_resp = perform
                if err_resp != null then return err_resp
 
-               var st_code = self.curl.prim_curl.easy_getinfo_long(new CURLInfoLong.response_code)
+               var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
                if not st_code == null then success_response.status_code = st_code.response
 
-               var speed = self.curl.prim_curl.easy_getinfo_double(new CURLInfoDouble.speed_download)
+               var speed = self.curl.native.easy_getinfo_double(new CURLInfoDouble.speed_download)
                if not speed == null then success_response.speed_download = speed.response
 
-               var size = self.curl.prim_curl.easy_getinfo_double(new CURLInfoDouble.size_download)
+               var size = self.curl.native.easy_getinfo_double(new CURLInfoDouble.size_download)
                if not size == null then success_response.size_download = size.response
 
-               var time = self.curl.prim_curl.easy_getinfo_double(new CURLInfoDouble.total_time)
+               var time = self.curl.native.easy_getinfo_double(new CURLInfoDouble.total_time)
                if not time == null then success_response.total_time = time.response
 
-               success_response.i_file.close
+               success_response.file.close
 
                return success_response
        end
@@ -198,7 +197,7 @@ end
 # CURL Mail Request
 class CurlMailRequest
        super CurlRequest
-       super CCurlCallbacks
+       super NativeCurlCallbacks
 
        var headers: nullable HeaderMap = null is writable
        var headers_body: nullable HeaderMap = null is writable
@@ -250,14 +249,14 @@ class CurlMailRequest
                # Host & Protocol
                err = is_supported_outgoing_protocol(host)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.url, host)
+               err = self.curl.native.easy_setopt(new CURLOption.url, host)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                # Credentials
                if not user == null and not pwd == null then
-                       err = self.curl.prim_curl.easy_setopt(new CURLOption.username, user)
+                       err = self.curl.native.easy_setopt(new CURLOption.username, user)
                        if not err.is_ok then return answer_failure(err.to_i, err.to_s)
-                       err = self.curl.prim_curl.easy_setopt(new CURLOption.password, pwd)
+                       err = self.curl.native.easy_setopt(new CURLOption.password, pwd)
                        if not err.is_ok then return answer_failure(err.to_i, err.to_s)
                end
 
@@ -292,16 +291,16 @@ class CurlMailRequest
 
                var err
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.follow_location, 1)
+               err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
-               err = self.curl.prim_curl.easy_setopt(new CURLOption.mail_rcpt, g_rec.to_curlslist)
+               err = self.curl.native.easy_setopt(new CURLOption.mail_rcpt, g_rec.to_curlslist)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                # From
                if not self.from == null then
                        content = add_pair_to_content(content, "From:", self.from)
-                       err = self.curl.prim_curl.easy_setopt(new CURLOption.mail_from, self.from.as(not null))
+                       err = self.curl.native.easy_setopt(new CURLOption.mail_from, self.from.as(not null))
                        if not err.is_ok then return answer_failure(err.to_i, err.to_s)
                end
 
@@ -317,9 +316,11 @@ class CurlMailRequest
                content = add_conventional_space(content)
                content = add_pair_to_content(content, "", self.body)
                content = add_conventional_space(content)
-               err = self.curl.prim_curl.register_callback(self, once new CURLCallbackType.read)
+
+               err = self.curl.native.register_callback_read(self)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
-               err = self.curl.prim_curl.register_read_datas_callback(self, content)
+
+               err = self.curl.native.register_read_datas_callback(self, content)
                if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 
                var err_resp = perform
@@ -331,12 +332,7 @@ end
 
 # Callbacks Interface, allow you to manage in your way the different streams
 interface CurlCallbacks
-       super CCurlCallbacks
-end
-
-# Callbacks attributes
-abstract class CurlCallbacksRegisterIntern
-       var delegate: nullable CurlCallbacks = null is writable
+       super NativeCurlCallbacks
 end
 
 # Abstract Curl request response
@@ -395,51 +391,55 @@ class CurlFileResponseSuccess
        var speed_download = 0
        var size_download = 0
        var total_time = 0
-       private var i_file: nullable OFile = null
+       private var file: nullable FileWriter = null
 
        # Receive bytes stream from request due to stream callback registering
-       redef fun stream_callback(buffer, size, count)
+       redef fun stream_callback(buffer)
        do
-               self.i_file.write(buffer, size, count)
+               file.write buffer
        end
 end
 
-# Pseudo map associating Strings to Strings,
-# each key can have multiple associations
-# and the order of insertion is important.
+# Pseudo map associating `String` to `String` for HTTP exchanges
+#
+# This structure differs from `Map` as each key can have multiple associations
+# and the order of insertion is important to some services.
 class HeaderMap
-       private var arr = new Array[Couple[String, String]]
+       private var array = new Array[Couple[String, String]]
 
-       fun []=(k, v: String) do arr.add(new Couple[String, String](k, v))
+       # Add a `value` associated to `key`
+       fun []=(key, value: String)
+       do
+               array.add new Couple[String, String](key, value)
+       end
 
+       # Get a list of the keys associated to `key`
        fun [](k: String): Array[String]
        do
                var res = new Array[String]
-               for c in arr do if c.first == k then res.add(c.second)
+               for c in array do if c.first == k then res.add c.second
                return res
        end
 
+       # Iterate over all the associations in `self`
        fun iterator: MapIterator[String, String] do return new HeaderMapIterator(self)
 
-       # Convert Self to a single string used to post http fields
-       fun to_url_encoded(curl: CCurl): String
+       # Get `self` as a single string for HTTP POST
+       #
+       # Require: `curl.is_ok`
+       fun to_url_encoded(curl: Curl): String
        do
-               assert curlNotInitialized: curl.is_init else
-                       print "to_url_encoded required a valid instance of CCurl Object."
-               end
-               var str = ""
-               var length = self.length
-               var i = 0
+               assert curl.is_ok
+
+               var lines = new Array[String]
                for k, v in self do
-                       if k.length > 0 then
-                               k = curl.escape(k)
-                               v = curl.escape(v)
-                               str = "{str}{k}={v}"
-                               if i < length-1 then str = "{str}&"
-                       end
-                       i += 1
+                       if k.length == 0 then continue
+
+                       k = curl.native.escape(k)
+                       v = curl.native.escape(v)
+                       lines.add "{k}={v}"
                end
-               return str
+               return lines.join("&")
        end
 
        # Concatenate couple of 'key value' separated by 'sep' in Array
@@ -450,15 +450,18 @@ class HeaderMap
                return col
        end
 
-       fun length: Int do return arr.length
-       fun is_empty: Bool do return arr.is_empty
+       # Number of values in `self`
+       fun length: Int do return array.length
+
+       # Is this map empty?
+       fun is_empty: Bool do return array.is_empty
 end
 
-class HeaderMapIterator
+private class HeaderMapIterator
        super MapIterator[String, String]
 
-       private var iterator: Iterator[Couple[String, String]]
-       init(map: HeaderMap) is old_style_init do self.iterator = map.arr.iterator
+       var map: HeaderMap
+       var iterator: Iterator[Couple[String, String]] = map.array.iterator is lazy
 
        redef fun is_ok do return self.iterator.is_ok
        redef fun next do self.iterator.next