From b280c8a9d7b8434650698ac912dc9b74bb087124 Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Wed, 6 Jan 2021 13:47:00 +0100 Subject: [PATCH] feat(compat) add a 5.4 compatible "warn" function also updates the derpecation warnings to use the warn function --- lua/pl/compat.lua | 28 ++++++++++++++++++++++++++++ lua/pl/permute.lua | 4 ++-- lua/pl/utils.lua | 31 +++++++++++++++++++++---------- spec/utils-deprecate_spec.lua | 8 ++++---- tests/test-strict.lua | 1 + 5 files changed, 56 insertions(+), 16 deletions(-) diff --git a/lua/pl/compat.lua b/lua/pl/compat.lua index 68113a2c..f77625d2 100644 --- a/lua/pl/compat.lua +++ b/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 diff --git a/lua/pl/permute.lua b/lua/pl/permute.lua index 1169f224..f69da2da 100644 --- a/lua/pl/permute.lua +++ b/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(...) diff --git a/lua/pl/utils.lua b/lua/pl/utils.lua index 8eb24c8d..52abf531 100644 --- a/lua/pl/utils.lua +++ b/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) diff --git a/spec/utils-deprecate_spec.lua b/spec/utils-deprecate_spec.lua index b236cb06..61bdfaa1 100644 --- a/spec/utils-deprecate_spec.lua +++ b/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 diff --git a/tests/test-strict.lua b/tests/test-strict.lua index 9dfd0dc2..5b873567 100644 --- a/tests/test-strict.lua +++ b/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'