feat(compat) add a 5.4 compatible "warn" function

also updates the derpecation warnings to use the warn function

lua/pl/compat.lua

@@ -218,4 +218,32 @@ if not package.searchpath then
     end
 end
 
+--- Global exported functions (for Lua < 5.4)
+-- @section lua54
+
+--- raise a warning message.
+-- This functions mimics the `warn` function added in Lua 5.4.
+-- @function warn
+-- @param ... any arguments
+if not warn then  -- luacheck: ignore
+    local enabled = false -- TODO: what is the default
+    function warn(arg1, ...)  -- luacheck: ignore
+        if type(arg1) == "string" and arg1:sub(1.1) == "@" then
+            -- control message
+            if arg1 == "@on" then
+                enabled = true
+                return
+            end
+            if arg1 == "@off" then
+                enabled = false
+                return
+            end
+            return -- ignore unknown control messages
+        end
+        if enabled then
+            io.stderr:write(arg1, ...) -- TODO: validate output, newlines, etc.
+        end
+    end
+end
+
 return compat

lua/pl/permute.lua

@@ -170,7 +170,7 @@ function permute.iter(...)
     source = "Penlight " .. utils._VERSION,
     message = "function 'iter' was renamed to 'order_iter'",
     version_removed = "2.0.0",
-    version_deprecated = "1.9.2",
+    deprecated_after = "1.9.2",
   }
 
   return permute.order_iter(...)
@@ -184,7 +184,7 @@ function permute.table(...)
     source = "Penlight " .. utils._VERSION,
     message = "function 'table' was renamed to 'order_table'",
     version_removed = "2.0.0",
-    version_deprecated = "1.9.2",
+    deprecated_after = "1.9.2",
   }
 
   return permute.order_table(...)

lua/pl/utils.lua

@@ -618,24 +618,30 @@ end
 -- An application can override this function to support proper output of
 -- deprecation warnings. The warnings can be generated from libraries or
 -- functions by calling `utils.raise_deprecation`. By default this function
--- doesn't do anything.
+-- will write to the 'warn' system (introduced in Lua 5.4, or the compatibility
+-- function from the `compat` module for earlier versions).
 --
 -- Note: only applications should override this function, libraries should not.
 -- @string msg the message to display/log
 -- @string trace the traceback from where the deprecated element was invoked
 -- @usage
+-- -- write to some logger at notice level
 -- function utils.deprecation_warning(msg, trace)
---   io.stderr:write(msg .. "\n" .. trace .."\n")
+--   log:notice(msg, " ", trace)
+-- end
+--
+-- -- disable deprecation warnings
+-- function utils.deprecation_warning(msg, trace)
+--   -- do nothing
 -- end
 function utils.deprecation_warning(msg, trace)
-  -- this does nothing by default
+  warn(msg, "\n", trace)  -- luacheck: ignore
 end
 
-
 --- raises a deprecation warning.
 -- For options see the usage example below.
 --
--- Note: the `opts.version_deprecated` field is the last version in which
+-- Note: the `opts.deprecated_after` field is the last version in which
 -- a feature or option was NOT YET deprecated! Because when writing the code it
 -- is quite often not known in what version the code will land. But the last
 -- released version is usually known.
@@ -647,7 +653,7 @@ end
 --     source = "Penlight " .. utils._VERSION,                  -- optional
 --     message = "function 'islower' was renamed to 'is_lower'" -- required
 --     version_removed = "2.0.0",                               -- optional
---     version_deprecated = "1.2.3",                            -- optional
+--     deprecated_after = "1.2.3",                              -- optional
 --   }
 --   return stringx.is_lower(str)
 -- end
@@ -659,11 +665,11 @@ function utils.raise_deprecation(opts)
   end
   local trace = debug.traceback("", 2):match("[\n%s]*(.-)$")
   local msg
-  if opts.version_deprecated and opts.version_removed then
+  if opts.deprecated_after and opts.version_removed then
     msg = (" (deprecated after %s, scheduled for removal in %s)"):format(
-      tostring(opts.version_deprecated), tostring(opts.version_removed))
-  elseif opts.version_deprecated then
-    msg = (" (deprecated after %s)"):format(tostring(opts.version_deprecated))
+      tostring(opts.deprecated_after), tostring(opts.version_removed))
+  elseif opts.deprecated_after then
+    msg = (" (deprecated after %s)"):format(tostring(opts.deprecated_after))
   elseif opts.version_removed then
     msg = (" (scheduled for removal in %s)"):format(tostring(opts.version_removed))
   else
@@ -674,6 +680,11 @@ function utils.raise_deprecation(opts)
 
   if opts.source then
     msg = "[" .. opts.source .."] " .. msg
+  else
+    if msg:sub(1,1) == "@" then
+      -- in Lua 5.4 "@" prefixed messages are control messages to the warn system
+      error("message cannot start with '@'", 2)
+    end
   end
 
   utils.deprecation_warning(msg, trace)

spec/utils-deprecate_spec.lua

@@ -46,7 +46,7 @@ describe("pl.utils", function ()
     it("should output the deprecated version", function ()
       utils.raise_deprecation {
         message = "hello world",
-        version_deprecated = "2.0.0",
+        deprecated_after = "2.0.0",
       }
       assert.equal("hello world (deprecated after 2.0.0)", last_msg)
     end)
@@ -64,7 +64,7 @@ describe("pl.utils", function ()
     it("should output the deprecated and removal versions", function ()
       utils.raise_deprecation {
         message = "hello world",
-        version_deprecated = "2.0.0",
+        deprecated_after = "2.0.0",
         version_removed = "3.0.0",
       }
       assert.equal("hello world (deprecated after 2.0.0, scheduled for removal in 3.0.0)", last_msg)
@@ -75,7 +75,7 @@ describe("pl.utils", function ()
       utils.raise_deprecation {
         source = "MyApp 1.2.3",
         message = "hello world",
-        version_deprecated = "2.0.0",
+        deprecated_after = "2.0.0",
         version_removed = "3.0.0",
       }
       assert.equal("[MyApp 1.2.3] hello world (deprecated after 2.0.0, scheduled for removal in 3.0.0)", last_msg)
@@ -87,7 +87,7 @@ describe("pl.utils", function ()
         utils.raise_deprecation {
           source = "MyApp 1.2.3",
           message = "hello world",
-          version_deprecated = "2.0.0",
+          deprecated_after = "2.0.0",
           version_removed = "3.0.0",
         }
       end

tests/test-strict.lua

@@ -1,3 +1,4 @@
+warn = warn or true-- declare 'warn' as a global, to be added in compat module
 local strict = require 'pl.strict'
 local test = require 'pl.test'
 local app = require 'pl.app'