rename nimLegacyJsonutilsHoleyEnum [backport] (#18938)

* enable nimPreviewJsonutilsHoleyEnum [backport]

* docuement nimPreviewJsonutilsHoleyEnum

changelog.md

@@ -77,8 +77,7 @@
   initialization with a small (< 30000) seed. Use `-d:nimLegacyRandomInitRand` to restore
   previous behavior for a transition time, see PR #17467.
 
-- `jsonutils` now serializes/deserializes holey enums as regular enums (via `ord`) instead of as strings.
-  Use `-d:nimLegacyJsonutilsHoleyEnum` for a transition period. `toJson` now serializes `JsonNode`
+- With `-d:nimPreviewJsonutilsHoleyEnum`, `jsonutils` now can serialize/deserialize holey enums as regular enums (via `ord`) instead of as strings. It is expected that this behavior becomes the new default in upcoming versions. `toJson` now serializes `JsonNode`
   as is via reference (without a deep copy) instead of treating `JsonNode` as a regular ref object,
   this can be customized via `jsonNodeMode`.
 

lib/std/jsonutils.nim

@@ -298,6 +298,10 @@ proc jsonTo*(b: JsonNode, T: typedesc, opt = Joptions()): T =
 proc toJson*[T](a: T, opt = initToJsonOptions()): JsonNode =
   ## serializes `a` to json; uses `toJsonHook(a: T)` if it's in scope to
   ## customize serialization, see strtabs.toJsonHook for an example.
+  ##
+  ## .. note:: With `-d:nimPreviewJsonutilsHoleyEnum`, `toJson` now can 
+  ##    serialize/deserialize holey enums as regular enums (via `ord`) instead of as strings.
+  ##    It is expected that this behavior becomes the new default in upcoming versions.
   when compiles(toJsonHook(a)): result = toJsonHook(a)
   elif T is object | tuple:
     when T is object or isNamedTuple(T):
@@ -328,7 +332,7 @@ proc toJson*[T](a: T, opt = initToJsonOptions()): JsonNode =
   elif T is enum:
     case opt.enumMode
     of joptEnumOrd:
-      when T is Ordinal or not defined(nimLegacyJsonutilsHoleyEnum): %(a.ord)
+      when T is Ordinal or defined(nimPreviewJsonutilsHoleyEnum): %(a.ord)
       else: toJson($a, opt)
     of joptEnumSymbol:
       when T is OrdinalEnum:

tests/config.nims

@@ -30,10 +30,12 @@ hint("Processing", off)
 # switch("hint", "ConvFromXtoItselfNotNeeded")
 # switch("warningAsError", "InheritFromException") # would require fixing a few tests
 
-# experimental API's are enabled in testament, refs https://github.com/timotheecour/Nim/issues/575
+# experimental APIs are enabled in testament, refs https://github.com/timotheecour/Nim/issues/575
 # sync with `kochdocs.docDefines` or refactor.
 switch("define", "nimExperimentalAsyncjsThen")
 switch("define", "nimExperimentalLinenoiseExtra")
 
+# preview APIs are expected to be the new default in upcoming versions
 switch("define", "nimPreviewFloatRoundtrip")
 switch("define", "nimPreviewDotLikeOps")
+switch("define", "nimPreviewJsonutilsHoleyEnum")