Merge remote-tracking branch 'nim-lang/devel' into emscripten-support

lib/pure/asyncftpclient.nim

@@ -6,23 +6,74 @@
 #    distribution, for details about the copyright.
 #
 
-## This module implement an asynchronous FTP client.
+## This module implements an asynchronous FTP client. It allows you to connect
+## to an FTP server and perform operations on it such as for example:
 ##
-## Examples
-## --------
+## * The upload of new files.
+## * The removal of existing files.
+## * Download of files.
+## * Changing of files' permissions.
+## * Navigation through the FTP server's directories.
 ##
-## .. code-block::nim
+## Connecting to an FTP server
+## ------------------------
 ##
-##      var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
-##      proc main(ftp: AsyncFtpClient) {.async.} =
+## In order to begin any sort of transfer of files you must first
+## connect to an FTP server. You can do so with the ``connect`` procedure.
+##
+##   .. code-block::nim
+##      import asyncdispatch, asyncftpclient
+##      proc main() {.async.} =
+##        var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
 ##        await ftp.connect()
-##        echo await ftp.pwd()
-##        echo await ftp.listDirs()
-##        await ftp.store("payload.jpg", "payload.jpg")
-##        await ftp.retrFile("payload.jpg", "payload2.jpg")
-##        echo("Finished")
+##        echo("Connected")
+##      waitFor(main())
 ##
-##      waitFor main(ftp)
+## A new ``main`` async procedure must be declared to allow the use of the
+## ``await`` keyword. The connection will complete asynchronously and the
+## client will be connected after the ``await ftp.connect()`` call.
+##
+## Uploading a new file
+## --------------------
+##
+## After a connection is made you can use the ``store`` procedure to upload
+## a new file to the FTP server. Make sure to check you are in the correct
+## working directory before you do so with the ``pwd`` procedure, you can also
+## instead specify an absolute path.
+##
+##   .. code-block::nim
+##      import asyncdispatch, asyncftpclient
+##      proc main() {.async.} =
+##        var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
+##        await ftp.connect()
+##        let currentDir = await ftp.pwd()
+##        assert currentDir == "/home/user/"
+##        await ftp.store("file.txt", "file.txt")
+##        echo("File finished uploading")
+##      waitFor(main())
+##
+## Checking the progress of a file transfer
+## ----------------------------------------
+##
+## The progress of either a file upload or a file download can be checked
+## by specifying a ``onProgressChanged`` procedure to the ``store`` or
+## ``retrFile`` procedures.
+##
+##   .. code-block::nim
+##      import asyncdispatch, asyncftpclient
+##
+##      proc onProgressChanged(total, progress: BiggestInt,
+##                              speed: float): Future[void] =
+##        echo("Uploaded ", progress, " of ", total, " bytes")
+##        echo("Current speed: ", speed, " kb/s")
+##
+##      proc main() {.async.} =
+##        var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
+##        await ftp.connect()
+##        await ftp.store("file.txt", "/home/user/file.txt", onProgressChanged)
+##        echo("File finished uploading")
+##      waitFor(main())
+
 
 import asyncdispatch, asyncnet, strutils, parseutils, os, times
 

lib/pure/asynchttpserver.nim

@@ -67,6 +67,12 @@ type
     Http409 = "409 Conflict",
     Http410 = "410 Gone",
     Http411 = "411 Length Required",
+    Http412 = "412 Precondition Failed",
+    Http413 = "413 Request Entity Too Large",
+    Http414 = "414 Request-URI Too Long",
+    Http415 = "415 Unsupported Media Type",
+    Http416 = "416 Requested Range Not Satisfiable",
+    Http417 = "417 Expectation Failed",
     Http418 = "418 I'm a teapot",
     Http500 = "500 Internal Server Error",
     Http501 = "501 Not Implemented",

lib/pure/base64.nim

@@ -8,6 +8,38 @@
 #
 
 ## This module implements a base64 encoder and decoder.
+##
+## Encoding data
+## -------------
+##
+## In order to encode some text simply call the ``encode`` procedure:
+##
+##   .. code-block::nim
+##      import base64
+##      let encoded = encode("Hello World")
+##      echo(encoded) # SGVsbG8gV29ybGQ=
+##
+## Apart from strings you can also encode lists of integers or characters:
+##
+##   .. code-block::nim
+##      import base64
+##      let encodedInts = encode([1,2,3])
+##      echo(encodedInts) # AQID
+##      let encodedChars = encode(['h','e','y'])
+##      echo(encodedChars) # aGV5
+##
+## The ``encode`` procedure takes an ``openarray`` so both arrays and sequences
+## can be passed as parameters.
+##
+## Decoding data
+## -------------
+##
+## To decode a base64 encoded data string simply call the ``decode``
+## procedure:
+##
+##   .. code-block::nim
+##      import base64
+##      echo(decode("SGVsbG8gV29ybGQ=")) # Hello World
 
 const
   cb64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
@@ -64,11 +96,16 @@ template encodeInternal(s: expr, lineLen: int, newLine: string): stmt {.immediat
 proc encode*[T:SomeInteger|char](s: openarray[T], lineLen = 75, newLine="\13\10"): string =
   ## encodes `s` into base64 representation. After `lineLen` characters, a
   ## `newline` is added.
+  ##
+  ## This procedure encodes an openarray (array or sequence) of either integers
+  ## or characters.
   encodeInternal(s, lineLen, newLine)
 
 proc encode*(s: string, lineLen = 75, newLine="\13\10"): string =
   ## encodes `s` into base64 representation. After `lineLen` characters, a
   ## `newline` is added.
+  ##
+  ## This procedure encodes a string.
   encodeInternal(s, lineLen, newLine)
 
 proc decodeByte(b: char): int {.inline.} =

lib/pure/ftpclient.nim

@@ -13,7 +13,12 @@ import sockets, strutils, parseutils, times, os, asyncio
 from asyncnet import nil
 from rawsockets import nil
 from asyncdispatch import PFuture
-
+## **Note**: This module is deprecated since version 0.11.3.
+## You should use the async version of this module
+## `asyncftpclient <asyncftpclient.html>`_.
+##
+## ----
+##
 ## This module **partially** implements an FTP client as specified
 ## by `RFC 959 <http://tools.ietf.org/html/rfc959>`_.
 ##
@@ -36,6 +41,8 @@ from asyncdispatch import PFuture
 ## **Warning:** The API of this module is unstable, and therefore is subject
 ## to change.
 
+{.deprecated.}
+
 type
   FtpBase*[SockType] = ref FtpBaseObj[SockType]
   FtpBaseObj*[SockType] = object

lib/pure/json.nim

@@ -622,9 +622,12 @@ proc getNum*(n: JsonNode, default: BiggestInt = 0): BiggestInt =
 proc getFNum*(n: JsonNode, default: float = 0.0): float =
   ## Retrieves the float value of a `JFloat JsonNode`.
   ##
-  ## Returns ``default`` if ``n`` is not a ``JFloat``, or if ``n`` is nil.
-  if n.isNil or n.kind != JFloat: return default
-  else: return n.fnum
+  ## Returns ``default`` if ``n`` is not a ``JFloat`` or ``JInt``, or if ``n`` is nil.
+  if n.isNil: return default
+  case n.kind
+  of JFloat: return n.fnum
+  of JInt: return float(n.num)
+  else: return default
 
 proc getBVal*(n: JsonNode, default: bool = false): bool =
   ## Retrieves the bool value of a `JBool JsonNode`.

lib/pure/math.nim

@@ -21,6 +21,20 @@ include "system/inclrtl"
 {.push debugger:off .} # the user does not want to trace a part
                        # of the standard library!
 
+proc binom*(n, k: int): int {.noSideEffect.} =
+  ## Computes the binomial coefficient
+  if k <= 0: return 1
+  if 2*k > n: return binom(n, n-k)
+  result = n
+  for i in countup(2, k):
+    result = (result * (n + 1 - i)) div i
+
+proc fac*(n: int): int {.noSideEffect.} =
+  ## Computes the faculty/factorial function.
+  result = 1
+  for i in countup(2, n):
+    result = result * i
+
 {.push checks:off, line_dir:off, stack_trace:off.}
 
 when defined(Posix) and not defined(haiku):
@@ -72,21 +86,6 @@ proc classify*(x: float): FloatClass =
   return fcNormal
   # XXX: fcSubnormal is not detected!
 
-
-proc binom*(n, k: int): int {.noSideEffect.} =
-  ## Computes the binomial coefficient
-  if k <= 0: return 1
-  if 2*k > n: return binom(n, n-k)
-  result = n
-  for i in countup(2, k):
-    result = (result * (n + 1 - i)) div i
-
-proc fac*(n: int): int {.noSideEffect.} =
-  ## Computes the faculty/factorial function.
-  result = 1
-  for i in countup(2, n):
-    result = result * i
-
 proc isPowerOfTwo*(x: int): bool {.noSideEffect.} =
   ## Returns true, if `x` is a power of two, false otherwise.
   ## Zero and negative numbers are not a power of two.