Documentation for async httpclient. Notes for url modules.

3 files changed, 43 insertions, 5 deletions

diff --git a/lib/pure/httpclient.nim b/lib/pure/httpclient.nim
index 415775583..1e3a1032c 100644
--- a/lib/pure/httpclient.nim
+++ b/lib/pure/httpclient.nim
@@ -435,15 +435,25 @@ type
     connected: bool
     currentURL: TURL ## Where we are currently connected.
     headers: PStringTable
+    maxRedirects: int
     userAgent: string
 
-proc newAsyncHttpClient*(): PAsyncHttpClient =
+proc newAsyncHttpClient*(userAgent = defUserAgent,
+    maxRedirects = 5): PAsyncHttpClient =
+  ## Creates a new PAsyncHttpClient instance.
+  ##
+  ## ``userAgent`` specifies the user agent that will be used when making
+  ## requests.
+  ##
+  ## ``maxRedirects`` specifies the maximum amount of redirects to follow,
+  ## default is 5.
   new result
   result.headers = newStringTable(modeCaseInsensitive)
   result.userAgent = defUserAgent
+  result.maxRedirects = maxRedirects
 
 proc close*(client: PAsyncHttpClient) =
-  ## Closes any connections held by the HttpClient.
+  ## Closes any connections held by the HTTP client.
   if client.connected:
     client.socket.close()
     client.connected = false
@@ -588,6 +598,14 @@ proc newConnection(client: PAsyncHttpClient, url: TURL) {.async.} =
 
 proc request*(client: PAsyncHttpClient, url: string, httpMethod = httpGET,
               body = ""): PFuture[TResponse] {.async.} =
+  ## Connects to the hostname specified by the URL and performs a request
+  ## using the method specified.
+  ##
+  ## Connection will kept alive. Further requests on the same ``client`` to
+  ## the same hostname will not require a new connection to be made. The
+  ## connection can be closed by using the ``close`` procedure.
+  ##
+  ## The returned future will complete once the request is completed.
   let r = parseUrl(url)
   await newConnection(client, r)
 
@@ -602,6 +620,19 @@ proc request*(client: PAsyncHttpClient, url: string, httpMethod = httpGET,
   
   result = await parseResponse(client, httpMethod != httpHEAD)
 
+proc get*(client: PAsyncHttpClient, url: string): PFuture[TResponse] {.async.} =
+  ## Connects to the hostname specified by the URL and performs a GET request.
+  ##
+  ## This procedure will follow redirects up to a maximum number of redirects
+  ## specified in ``newAsyncHttpClient``.
+  result = await client.request(url, httpGET)
+  var lastURL = url
+  for i in 1..client.maxRedirects:
+    if result.status.redirection():
+      let redirectTo = getNewLocation(lastURL, result.headers)
+      result = await client.request(redirectTo, httpGET)
+      lastUrl = redirectTo
+
 when isMainModule:
   when true:
     # Async
diff --git a/lib/pure/parseurl.nim b/lib/pure/parseurl.nim
index 937f26f6f..357d1df0f 100644
--- a/lib/pure/parseurl.nim
+++ b/lib/pure/parseurl.nim
@@ -1,13 +1,16 @@
 #
 #
 #            Nimrod's Runtime Library
-#        (c) Copyright 2010 Dominik Picheta
+#        (c) Copyright 2014 Dominik Picheta
 #
 #    See the file "copying.txt", included in this
 #    distribution, for details about the copyright.
 #
 
 ## Parses & constructs URLs.
+##
+## **Note**: This module will be deprecated in the future and merged into a
+## new ``url`` module.
 
 import strutils
 
diff --git a/lib/pure/uri.nim b/lib/pure/uri.nim
index 18afd4af6..ee1226a35 100644
--- a/lib/pure/uri.nim
+++ b/lib/pure/uri.nim
@@ -1,11 +1,15 @@
 #
 #
 #            Nimrod's Runtime Library
-#        (c) Copyright 2012 Dominik Picheta
+#        (c) Copyright 2014 Dominik Picheta
 #
 #    See the file "copying.txt", included in this
 #    distribution, for details about the copyright.
 #
+
+## **Note**: This module will be deprecated in the future and merged into a
+## new ``url`` module.
+
 import strutils
 type
   TUrl* = distinct string
@@ -30,4 +34,4 @@ proc add*(url: var TUrl, a: TUrl) =
   url = url / a
 
 when isMainModule:
-  assert($("http://".TUrl / "localhost:5000".TUrl) == "http://localhost:5000")
\ No newline at end of file
+  assert($("http://".TUrl / "localhost:5000".TUrl) == "http://localhost:5000")