colors: fix 'mix' template and make most examples runnable (#12532) [backport]

* colors: fix the 'mix' template
* colors: make most examples runnable

lib/pure/colors.nim

@@ -52,12 +52,12 @@ proc `+`*(a, b: Color): Color =
   ## This uses saturated artithmetic, so that each color
   ## component cannot overflow (255 is used as a maximum).
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = Color(0xaa_00_ff)
+      a = Color(0xaa_00_ff)
-  ##     b = Color(0x11_cc_cc)
+      b = Color(0x11_cc_cc)
-  ##   assert a + b == Color(0xbb_cc_ff)
+    assert a + b == Color(0xbb_cc_ff)
-  ##
+
   colorOp(satPlus)
 
 proc `-`*(a, b: Color): Color =
@@ -66,24 +66,26 @@ proc `-`*(a, b: Color): Color =
   ## This uses saturated artithmetic, so that each color
   ## component cannot underflow (0 is used as a minimum).
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = Color(0xff_33_ff)
+      a = Color(0xff_33_ff)
-  ##     b = Color(0x11_ff_cc)
+      b = Color(0x11_ff_cc)
-  ##   assert a - b == Color(0xee_00_33)
+    assert a - b == Color(0xee_00_33)
-  ##
+
   colorOp(satMinus)
 
 proc extractRGB*(a: Color): tuple[r, g, b: range[0..255]] =
   ## Extracts the red/green/blue components of the color `a`.
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = Color(0xff_00_ff)
+      a = Color(0xff_00_ff)
-  ##     b = Color(0x00_ff_cc)
+      b = Color(0x00_ff_cc)
-  ##   echo extractRGB(a) # => (r: 255, g: 0, b: 255)
+    type
-  ##   echo extractRGB(b) # => (r: 0, g: 255, b: 204)
+      col = range[0..255]
-  ##
+    assert extractRGB(a) == (r: 255.col, g: 0.col, b: 255.col)
+    assert extractRGB(b) == (r: 0.col, g: 255.col, b: 204.col)
+
   result.r = a.int shr 16 and 0xff
   result.g = a.int shr 8 and 0xff
   result.b = a.int and 0xff
@@ -92,13 +94,13 @@ proc intensity*(a: Color, f: float): Color =
   ## Returns `a` with intensity `f`. `f` should be a float from 0.0 (completely
   ## dark) to 1.0 (full color intensity).
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = Color(0xff_00_ff)
+      a = Color(0xff_00_ff)
-  ##     b = Color(0x00_42_cc)
+      b = Color(0x00_42_cc)
-  ##   assert a.intensity(0.5) == Color(0x80_00_80)
+    assert a.intensity(0.5) == Color(0x80_00_80)
-  ##   assert b.intensity(0.5) == Color(0x00_21_66)
+    assert b.intensity(0.5) == Color(0x00_21_66)
-  ##
+
   var r = toInt(toFloat(a.int shr 16 and 0xff) * f)
   var g = toInt(toFloat(a.int shr 8 and 0xff) * f)
   var b = toInt(toFloat(a.int and 0xff) * f)
@@ -114,16 +116,16 @@ template mix*(a, b: Color, fn: untyped): untyped =
   ## If `fn`'s result is not in the `range[0..255]`,
   ## it will be saturated to be so.
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = Color(0x0a2814)
+      a = Color(0x0a2814)
-  ##     b = Color(0x050a03)
+      b = Color(0x050a03)
-  ##
+
-  ##   proc myMix(x, y: int): int =
+    proc myMix(x, y: int): int =
-  ##     2 * x - 3 * y
+      2 * x - 3 * y
-  ##
+
-  ##   assert mix(a, b, myMix) == Color(0x05_32_1f)
+    assert mix(a, b, myMix) == Color(0x05_32_1f)
-  ##
+
   template `><` (x: untyped): untyped =
     # keep it in the range 0..255
     block:
@@ -132,7 +134,6 @@ template mix*(a, b: Color, fn: untyped): untyped =
         y = if y < 0: 0 else: 255
       y
 
-  var ar, ag, ab, br, bg, bb: int
   extract(a, ar, ag, ab)
   extract(b, br, bg, bb)
   rawRGB(><fn(ar, br), ><fn(ag, bg), ><fn(ab, bb))
@@ -425,9 +426,8 @@ const
 proc `$`*(c: Color): string =
   ## Converts a color into its textual representation.
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   assert $colFuchsia == "#FF00FF"
+    assert $colFuchsia == "#FF00FF"
-  ##
   result = '#' & toHex(int(c), 6)
 
 proc colorNameCmp(x: tuple[name: string, col: Color], y: string): int =
@@ -439,15 +439,15 @@ proc parseColor*(name: string): Color =
   ## If no valid color could be parsed ``ValueError`` is raised.
   ## Case insensitive.
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = "silver"
+      a = "silver"
-  ##     b = "#0179fc"
+      b = "#0179fc"
-  ##     c = "#zzmmtt"
+      c = "#zzmmtt"
-  ##   assert parseColor(a) == Color(0xc0_c0_c0)
+    assert parseColor(a) == Color(0xc0_c0_c0)
-  ##   assert parseColor(b) == Color(0x01_79_fc)
+    assert parseColor(b) == Color(0x01_79_fc)
-  ##   doAssertRaises(ValueError): discard parseColor(c)
+    doAssertRaises(ValueError): discard parseColor(c)
-  ##
+
   if name[0] == '#':
     result = Color(parseHexInt(name))
   else:
@@ -459,15 +459,15 @@ proc isColor*(name: string): bool =
   ## Returns true if `name` is a known color name or a hexadecimal color
   ## prefixed with ``#``. Case insensitive.
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   var
+    var
-  ##     a = "silver"
+      a = "silver"
-  ##     b = "#0179fc"
+      b = "#0179fc"
-  ##     c = "#zzmmtt"
+      c = "#zzmmtt"
-  ##   assert a.isColor
+    assert a.isColor
-  ##   assert b.isColor
+    assert b.isColor
-  ##   assert not c.isColor
+    assert not c.isColor
-  ##
+
   if name[0] == '#':
     for i in 1 .. name.len-1:
       if name[i] notin {'0'..'9', 'a'..'f', 'A'..'F'}: return false
@@ -478,7 +478,7 @@ proc isColor*(name: string): bool =
 proc rgb*(r, g, b: range[0..255]): Color =
   ## Constructs a color from RGB values.
   ##
-  ## .. code-block::
+  runnableExamples:
-  ##   assert rgb(0, 255, 128) == Color(0x00_ff_80)
+    assert rgb(0, 255, 128) == Color(0x00_ff_80)
-  ##
+
   result = rawRGB(r, g, b)