last stdlib cleanups

changelog.md

@@ -67,6 +67,31 @@ type
 
 - Consistent error handling of two `exec` overloads. (#10967)
 
+- Officially the following modules now have an unstable API:
+
+  - std/varints
+  - core/allocators
+  - core/hotcodereloading
+  - asyncstreams
+  - base64
+  - browsers
+  - collections/rtarrays
+  - collections/sharedlist
+  - collections/sharedtable
+  - concurrency/atomics
+  - concurrency/cpuload
+  - concurrency/threadpool
+  - coro
+  - endians
+  - httpcore
+  - parsesql
+  - pathnorm
+  - reservedmem
+  - typetraits
+
+  Every other stdlib module is API stable with respect to version 1.
+
+
 ## Language additions
 
 - Inline iterators returning `lent T` types are now supported, similarly to iterators returning `var T`:

lib/core/allocators.nim

@@ -7,6 +7,8 @@
 #    distribution, for details about the copyright.
 #
 
+## Unstable API.
+
 type
   AllocatorFlag* {.pure.} = enum  ## flags describing the properties of the allocator
     ThreadLocal ## the allocator is thread local only.

lib/core/hotcodereloading.nim

@@ -1,3 +1,14 @@
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2019 Nim contributors
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## Unstable API.
+
 when defined(hotcodereloading):
   import
     macros

lib/pure/asyncftpclient.nim

@@ -321,7 +321,7 @@ proc getFile(ftp: AsyncFtpClient, file: File, total: BiggestInt,
   assertReply(await(ftp.expectReply()), "226")
 
 proc defaultOnProgressChanged*(total, progress: BiggestInt,
-    speed: float): Future[void] {.nimcall,gcsafe,procvar.} =
+    speed: float): Future[void] {.nimcall, gcsafe, procvar.} =
   ## Default FTP ``onProgressChanged`` handler. Does nothing.
   result = newFuture[void]()
   #echo(total, " ", progress, " ", speed)

lib/pure/asyncfutures.nim

@@ -1,3 +1,12 @@
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2015 Dominik Picheta
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
 import os, tables, strutils, times, heapqueue, options, deques, cstrutils
 
 # TODO: This shouldn't need to be included, but should ideally be exported.

lib/pure/asynchttpserver.nim

@@ -296,7 +296,7 @@ proc processClient(server: AsyncHttpServer, client: AsyncSocket, address: string
     if not retry: break
 
 proc serve*(server: AsyncHttpServer, port: Port,
-            callback: proc (request: Request): Future[void] {.closure,gcsafe.},
+            callback: proc (request: Request): Future[void] {.closure, gcsafe.},
             address = "") {.async.} =
   ## Starts the process of listening for incoming HTTP connections on the
   ## specified address and port.

lib/pure/asyncstreams.nim

@@ -1,3 +1,14 @@
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2015 Dominik Picheta
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## Unstable API.
+
 import asyncfutures
 
 import deques

lib/pure/base64.nim

@@ -9,6 +9,8 @@
 
 ## This module implements a base64 encoder and decoder.
 ##
+## Unstable API.
+##
 ## Base64 is an encoding and decoding technique used to convert binary
 ## data to an ASCII string format.
 ## Each Base64 digit represents exactly 6 bits of data. Three 8-bit
@@ -110,7 +112,7 @@ template encodeInternal(s: typed, lineLen: int, newLine: string): untyped =
     #assert(r == result.len)
     discard
 
-proc encode*[T:SomeInteger|char](s: openArray[T], lineLen = 75, newLine=""): string =
+proc encode*[T: SomeInteger|char](s: openArray[T], lineLen = 75, newLine=""): string =
   ## Encodes ``s`` into base64 representation. After ``lineLen`` characters, a
   ## ``newline`` is added.
   ##

lib/pure/browsers.nim

@@ -9,6 +9,8 @@
 
 ## This module implements a simple proc for opening URLs with the user's
 ## default browser.
+##
+## Unstable API.
 
 import strutils
 
@@ -22,8 +24,10 @@ proc openDefaultBrowser*(url: string) =
   ##
   ## Under Windows, ``ShellExecute`` is used. Under Mac OS X the ``open``
   ## command is used. Under Unix, it is checked if ``xdg-open`` exists and
-  ## used if it does. Otherwise the environment variable ``BROWSER`` is 
+  ## used if it does. Otherwise the environment variable ``BROWSER`` is
   ## used to determine the default browser to use.
+  ##
+  ## This proc doesn't raise an exception on error, beware.
   when defined(windows):
     var o = newWideCString("open")
     var u = newWideCString(url)

lib/pure/collections/rtarrays.nim

@@ -10,6 +10,8 @@
 
 ## Module that implements a fixed length array whose size
 ## is determined at runtime. Note: This is not ready for other people to use!
+##
+## Unstable API.
 
 const
   ArrayPartSize = 10

lib/pure/collections/sharedlist.nim

@@ -8,6 +8,8 @@
 #
 
 ## Shared list support.
+##
+## Unstable API.
 
 {.push stackTrace: off.}
 

lib/pure/collections/sharedtables.nim

@@ -11,6 +11,8 @@
 ## you'll be in trouble. Uses a single lock to protect the table, lockfree
 ## implementations welcome but if lock contention is so high that you need a
 ## lockfree hash table, you're doing it wrong.
+##
+## Unstable API.
 
 import
   hashes, math, locks

lib/pure/concurrency/atomics.nim

@@ -8,6 +8,8 @@
 #
 
 ## Types and operations for atomic operations and lockless algorithms.
+##
+## Unstable API.
 
 import macros
 
@@ -18,7 +20,7 @@ when defined(cpp) or defined(nimdoc):
 
   type
     MemoryOrder* {.importcpp: "std::memory_order".} = enum
-      ## Specifies how non-atomic operations can be reordered around atomic 
+      ## Specifies how non-atomic operations can be reordered around atomic
       ## operations.
 
       moRelaxed
@@ -131,7 +133,7 @@ else:
   # Since MSVC does not implement C11, we fall back to MS intrinsics
   # where available.
 
-  type 
+  type
     Trivial = SomeNumber | bool | ptr | pointer
       # A type that is known to be atomic and whose size is known at
       # compile time to be 8 bytes or less
@@ -144,7 +146,7 @@ else:
     elif sizeof(T) == 8: int64
 
   when defined(vcc):
-    
+
     # TODO: Trivial types should be volatile and use VC's special volatile
     # semantics for store and loads.
 
@@ -231,7 +233,7 @@ else:
       cast[T](interlockedOr(addr(location.value), cast[nonAtomicType(T)](value)))
     proc fetchXor*[T: SomeInteger](location: var Atomic[T]; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.inline.} =
       cast[T](interlockedXor(addr(location.value), cast[nonAtomicType(T)](value)))
-    
+
   else:
     {.push, header: "<stdatomic.h>".}
 
@@ -275,22 +277,22 @@ else:
     proc atomic_exchange_explicit[T, A](location: ptr A; desired: T; order: MemoryOrder = moSequentiallyConsistent): T {.importc.}
     proc atomic_compare_exchange_strong_explicit[T, A](location: ptr A; expected: ptr T; desired: T; success, failure: MemoryOrder): bool {.importc.}
     proc atomic_compare_exchange_weak_explicit[T, A](location: ptr A; expected: ptr T; desired: T; success, failure: MemoryOrder): bool {.importc.}
-      
+
     # Numerical operations
     proc atomic_fetch_add_explicit[T, A](location: ptr A; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.importc.}
     proc atomic_fetch_sub_explicit[T, A](location: ptr A; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.importc.}
     proc atomic_fetch_and_explicit[T, A](location: ptr A; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.importc.}
     proc atomic_fetch_or_explicit[T, A](location: ptr A; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.importc.}
     proc atomic_fetch_xor_explicit[T, A](location: ptr A; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.importc.}
-  
+
     # Flag operations
     # var ATOMIC_FLAG_INIT {.importc, nodecl.}: AtomicFlag
     # proc init*(location: var AtomicFlag) {.inline.} = location = ATOMIC_FLAG_INIT
     proc testAndSet*(location: var AtomicFlag; order: MemoryOrder = moSequentiallyConsistent): bool {.importc: "atomic_flag_test_and_set_explicit".}
     proc clear*(location: var AtomicFlag; order: MemoryOrder = moSequentiallyConsistent) {.importc: "atomic_flag_clear_explicit".}
-  
+
     proc fence*(order: MemoryOrder) {.importc: "atomic_thread_fence".}
-    proc signalFence*(order: MemoryOrder) {.importc: "atomic_signal_fence".}  
+    proc signalFence*(order: MemoryOrder) {.importc: "atomic_signal_fence".}
 
     {.pop.}
 
@@ -309,7 +311,7 @@ else:
       atomic_compare_exchange_weak_explicit(addr(location.value), cast[ptr nonAtomicType(T)](addr(expected)), cast[nonAtomicType(T)](desired), success, failure)
     proc compareExchangeWeak*[T: Trivial](location: var Atomic[T]; expected: var T; desired: T; order: MemoryOrder = moSequentiallyConsistent): bool {.inline.} =
       compareExchangeWeak(location, expected, desired, order, order)
-  
+
     # Numerical operations
     proc fetchAdd*[T: SomeInteger](location: var Atomic[T]; value: T; order: MemoryOrder = moSequentiallyConsistent): T {.inline.} =
       cast[T](atomic_fetch_add_explicit(addr(location.value), cast[nonAtomicType(T)](value), order))
@@ -327,11 +329,11 @@ else:
     body
     location.guard.clear(moRelease)
 
-  proc load*[T: not Trivial](location: var Atomic[T]; order: MemoryOrder = moSequentiallyConsistent): T {.inline.} =      
+  proc load*[T: not Trivial](location: var Atomic[T]; order: MemoryOrder = moSequentiallyConsistent): T {.inline.} =
     withLock(location, order):
       result = location.nonAtomicValue
 
-  proc store*[T: not Trivial](location: var Atomic[T]; desired: T; order: MemoryOrder = moSequentiallyConsistent) {.inline.} =      
+  proc store*[T: not Trivial](location: var Atomic[T]; desired: T; order: MemoryOrder = moSequentiallyConsistent) {.inline.} =
     withLock(location, order):
       location.nonAtomicValue = desired
 
@@ -375,4 +377,3 @@ proc `+=`*[T: SomeInteger](location: var Atomic[T]; value: T) {.inline.} =
 proc `-=`*[T: SomeInteger](location: var Atomic[T]; value: T) {.inline.} =
   ## Atomically decrements the atomic integer by some `value`.
   discard location.fetchSub(value)
-  

lib/pure/concurrency/cpuload.nim

@@ -9,6 +9,8 @@
 
 ## This module implements a helper for a thread pool to determine whether
 ## creating a thread is a good idea.
+##
+## Unstable API.
 
 when defined(windows):
   import winlean, os, strutils, math

lib/pure/concurrency/threadpool.nim

@@ -14,6 +14,8 @@
 ## * `channels module <channels.html>`_
 ## * `locks module <locks.html>`_
 ## * `asyncdispatch module <asyncdispatch.html>`_
+##
+## Unstable API.
 
 when not compileOption("threads"):
   {.error: "Threadpool requires --threads:on option.".}

lib/pure/coro.nim

@@ -6,6 +6,7 @@
 #    See the file "copying.txt", included in this
 #    distribution, for details about the copyright.
 #
+
 ## Nim coroutines implementation, supports several context switching methods:
 ## --------  ------------
 ## ucontext  available on unix and alike (default)
@@ -17,6 +18,8 @@
 ## -d:nimCoroutinesUcontext       Use ucontext backend.
 ## -d:nimCoroutinesSetjmp         Use setjmp backend.
 ## -d:nimCoroutinesSetjmpBundled  Use bundled setjmp implementation.
+##
+## Unstable API.
 
 when not nimCoroutines and not defined(nimdoc):
   when defined(noNimCoroutines):

lib/pure/endians.nim

@@ -9,6 +9,8 @@
 
 ## This module contains helpers that deal with different byte orders
 ## (`endian`:idx:).
+##
+## Unstable API.
 
 when defined(gcc) or defined(llvm_gcc) or defined(clang):
   const useBuiltinSwap = true

lib/pure/htmlparser.nim

@@ -7,8 +7,8 @@
 #    distribution, for details about the copyright.
 #
 
-## This module parses an HTML document and creates its XML tree representation.
-## It is supposed to handle the *wild* HTML the real world uses.
+## **NOTE**: The behaviour might change in future versions as it is not
+## clear what "*wild* HTML the real world uses" really implies.
 ##
 ## It can be used to parse a wild HTML document and output it as valid XHTML
 ## document (well, if you are lucky):

lib/pure/httpcore.nim

@@ -9,6 +9,8 @@
 
 ## Contains functionality shared between the ``httpclient`` and
 ## ``asynchttpserver`` modules.
+##
+## Unstable API.
 
 import tables, strutils, parseutils
 

lib/pure/lenientops.nim

@@ -57,4 +57,4 @@ proc `<=`*[I: SomeInteger, F: SomeFloat](f: F, i: I): bool {.noSideEffect, inlin
 
 # Note that we must not defined `>=` and `>`, because system.nim already has a
 # template with signature (x, y: untyped): untyped, which would lead to
-# ambigous calls.
+# ambiguous calls.

lib/pure/parsesql.nim

@@ -9,6 +9,8 @@
 
 ## The ``parsesql`` module implements a high performance SQL file
 ## parser. It parses PostgreSQL syntax and the SQL ANSI standard.
+##
+## Unstable API.
 
 import
   strutils, lexbase

lib/pure/pathnorm.nim

@@ -8,8 +8,9 @@
 #
 
 ## OS-Path normalization. Used by ``os.nim`` but also
-## generally useful for dealing with paths. Note that this module
-## does not provide a stable API.
+## generally useful for dealing with paths.
+##
+## Unstable API.
 
 # Yes, this uses import here, not include so that
 # we don't end up exporting these symbols from pathnorm and os:

lib/pure/punycode.nim

@@ -7,6 +7,9 @@
 #    distribution, for details about the copyright.
 #
 
+## Implements a representation of Unicode with the limited
+## ASCII character subset.
+
 import strutils
 import unicode
 
@@ -23,7 +26,7 @@ const
   Delimiter = '-'
 
 type
-  PunyError* = object of Exception
+  PunyError* = object of ValueError
 
 proc decodeDigit(x: char): int {.raises: [PunyError].} =
   if '0' <= x and x <= '9':

lib/pure/rationals.nim

@@ -18,7 +18,7 @@ type Rational*[T] = object
   ## a rational number, consisting of a numerator and denominator
   num*, den*: T
 
-proc initRational*[T:SomeInteger](num, den: T): Rational[T] =
+proc initRational*[T: SomeInteger](num, den: T): Rational[T] =
   ## Create a new rational number.
   assert(den != 0, "a denominator of zero value is invalid")
   result.num = num
@@ -34,7 +34,7 @@ proc `$`*[T](x: Rational[T]): string =
   ## Turn a rational number into a string.
   result = $x.num & "/" & $x.den
 
-proc toRational*[T:SomeInteger](x: T): Rational[T] =
+proc toRational*[T: SomeInteger](x: T): Rational[T] =
   ## Convert some integer `x` to a rational number.
   result.num = x
   result.den = 1
@@ -82,7 +82,7 @@ proc toInt*[T](x: Rational[T]): int =
   ## `x` does not contain an integer value.
   x.num div x.den
 
-proc reduce*[T:SomeInteger](x: var Rational[T]) =
+proc reduce*[T: SomeInteger](x: var Rational[T]) =
   ## Reduce rational `x`.
   let common = gcd(x.num, x.den)
   if x.den > 0:
@@ -288,20 +288,20 @@ when isMainModule:
     m1 = -1 // 1
     tt = 10 // 2
 
-  assert( a     == a )
+  assert( a == a )
   assert( (a-a) == z )
   assert( (a+b) == o )
   assert( (a/b) == o )
   assert( (a*b) == 1 // 4 )
   assert( (3/a) == 6 // 1 )
   assert( (a/3) == 1 // 6 )
-  assert( a*b   == 1 // 4 )
-  assert( tt*z  == z )
-  assert( 10*a  == tt )
-  assert( a*10  == tt )
+  assert( a*b == 1 // 4 )
+  assert( tt*z == z )
+  assert( 10*a == tt )
+  assert( a*10 == tt )
   assert( tt/10 == a  )
-  assert( a-m1  == 3 // 2 )
-  assert( a+m1  == -1 // 2 )
+  assert( a-m1 == 3 // 2 )
+  assert( a+m1 == -1 // 2 )
   assert( m1+tt == 16 // 4 )
   assert( m1-tt == 6 // -1 )
 

lib/pure/reservedmem.nim

@@ -15,6 +15,8 @@
 ## is guaranteed to remain in the same memory location. The buffer
 ## will be able to grow up to the size of the initially reserved
 ## portion of the address space.
+##
+## Unstable API.
 
 from ospaths import raiseOSError, osLastError
 

lib/pure/segfaults.nim

@@ -13,6 +13,8 @@
 ##
 ## Tested on these OSes: Linux, Windows, OSX
 
+{.used.}
+
 # do allocate memory upfront:
 var se: ref NilAccessError
 new(se)

lib/pure/typetraits.nim

@@ -9,6 +9,8 @@
 
 ## This module defines compile-time reflection procs for
 ## working with types.
+##
+## Unstable API.
 
 export system.`$` # for backward compatibility
 

lib/pure/unittest.nim

@@ -9,6 +9,11 @@
 
 ## :Author: Zahary Karadjov
 ##
+## **Note**: Instead of ``unittest.nim``, please consider to use
+## the ``testament`` tool which offers process isolation for your tests.
+## Also ``when isMainModule: doAssert conditionHere`` is usually a
+## much simpler solution for testing purposes.
+##
 ## This module implements boilerplate to make unit testing easy.
 ##
 ## The test status and name is printed after any output or traceback.
@@ -306,7 +311,7 @@ method testEnded*(formatter: JUnitOutputFormatter, testResult: TestResult) =
   let time = epochTime() - formatter.testStartTime
   let timeStr = time.formatFloat(ffDecimal, precision = 8)
   formatter.stream.writeLine("\t\t<testcase name=\"$#\" time=\"$#\">" % [xmlEscape(testResult.testName), timeStr])
-  case testResult.status:
+  case testResult.status
   of OK:
     discard
   of SKIPPED:

lib/std/varints.nim

@@ -7,8 +7,10 @@
 #    distribution, for details about the copyright.
 #
 
-## Note this API is still experimental! A variable length integer
+## A variable length integer
 ## encoding implementation inspired by SQLite.
+##
+## Unstable API.
 
 const
   maxVarIntLen* = 9 ## the maximal number of bytes a varint can take

lib/system/inclrtl.nim

@@ -44,15 +44,7 @@ else:
   {.pragma: inl, inline.}
   {.pragma: compilerRtl, compilerproc.}
 
-when not defined(nimsuperops):
-  {.pragma: operator.}
-
 when defined(nimlocks):
   {.pragma: benign, gcsafe, locks: 0.}
 else:
   {.pragma: benign, gcsafe.}
-
-when defined(nimTableGet):
-  {.pragma: deprecatedGet, deprecated.}
-else:
-  {.pragma: deprecatedGet.}

tools/kochdocs.nim

@@ -156,6 +156,7 @@ lib/experimental/diff.nim
 lib/pure/algorithm.nim
 lib/pure/stats.nim
 lib/windows/winlean.nim
+lib/windows/registry.nim
 lib/pure/random.nim
 lib/pure/complex.nim
 lib/pure/times.nim