From 55ea6ba98cc11cad4584b3d347342eb95a54f605 Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Sat, 2 Jul 2022 15:24:37 +0200 Subject: [PATCH 1/8] silent require and requireopt Add a thired argument to the Premake require(modname, version, silent) function to disable error throwing when module failed to load. Add requireopt(m, v) as a shorthand for require(m, v, true) --- src/base/globals.lua | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/src/base/globals.lua b/src/base/globals.lua index 90ab65c926..25a9f48bbf 100644 --- a/src/base/globals.lua +++ b/src/base/globals.lua @@ -74,19 +74,34 @@ -- @param versions -- An optional version criteria string; see premake.checkVersion() -- for more information on the format. +-- @param silent +-- By default, the require function throws an error when the +-- module could not be loaded. +-- If silent is true, the function will just return false nad the error message. -- @return -- If successful, the loaded module, which is also stored into the -- global package.loaded table. --- - premake.override(_G, "require", function(base, modname, versions) + premake.override(_G, "require", function(base, modname, versions, silent) local result, mod = pcall(base,modname) if not result then + if silent then + return result, mod + end error(mod, 3) end if mod and versions and not premake.checkVersion(mod._VERSION, versions) then - error(string.format("module %s %s does not meet version criteria %s", - modname, mod._VERSION or "(none)", versions), 3) + local message = string.format("module %s %s does not meet version criteria %s", + modname, mod._VERSION or "(none)", versions) + if silent then + return false, message + end + error(message, 3) end return mod end) + + function requireopt(modname, versions) + return require(modname, versions, true) + end \ No newline at end of file From 1e187db9af540f0ba896c60dbad09014983f0af3 Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Sat, 2 Jul 2022 16:01:01 +0200 Subject: [PATCH 2/8] Add silent require test --- tests/_tests.lua | 1 + tests/base/test_module_loader_silent.lua | 31 ++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 tests/base/test_module_loader_silent.lua diff --git a/tests/_tests.lua b/tests/_tests.lua index 0ceb983728..5f45ef14ad 100644 --- a/tests/_tests.lua +++ b/tests/_tests.lua @@ -10,6 +10,7 @@ return { "base/test_detoken.lua", "base/test_include.lua", "base/test_module_loader.lua", + "base/test_module_loader_silent.lua", "base/test_option.lua", "base/test_os.lua", "base/test_override.lua", diff --git a/tests/base/test_module_loader_silent.lua b/tests/base/test_module_loader_silent.lua new file mode 100644 index 0000000000..f0bdfb2bad --- /dev/null +++ b/tests/base/test_module_loader_silent.lua @@ -0,0 +1,31 @@ +-- +-- tests/base/test_module_loader_silent.lua +-- Test the custom module loader with silent option. +-- Copyright (c) 2012-2022 Jason Perkins and the Premake project +-- + + local p = premake + local suite = test.declare("module_loader_silent") + +-- +-- Setup +-- + + function suite.setup() + end + + function suite.teardown() + end + +-- +-- Check that premake's module loader will failed to +-- load module silently +-- + + function suite.silentLoadingFailure() + local result, msg = require("i-am-not-a-module", nil, true) + test.isfalse(result) + p.w(msg) + test.capture("module 'i-am-not-a-module' not found") + end + \ No newline at end of file From 1af25ebe3a9442503d579f060c625c66f9ae5ad8 Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Sat, 2 Jul 2022 16:53:17 +0200 Subject: [PATCH 3/8] Add requireopt and require third parameter documentation --- website/docs/globals/require.md | 10 ++++++++-- website/docs/globals/requireopt.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) create mode 100644 website/docs/globals/requireopt.md diff --git a/website/docs/globals/require.md b/website/docs/globals/require.md index 15d0be373a..6a1b2eed02 100644 --- a/website/docs/globals/require.md +++ b/website/docs/globals/require.md @@ -1,7 +1,7 @@ An extension of [Lua's require() function](http://www.lua.org/pil/8.1.html) which adds support for Premake modules and version checking. ```lua -require ("modname", "versions") +require ("modname", "versions", silent) ``` Premake will use its [extended set of module locations](Locating-Scripts.md) when locating the requested module. @@ -12,10 +12,15 @@ Premake will use its [extended set of module locations](Locating-Scripts.md) whe `versions` is an optional string of a version requirements. See the examples below for more information on the format of the requirements string. If the requirements are not met, an error will be raised. +`silent` will change the default error handling behavior. +By default, `require` raises an error if the module could not be loaded +or if the module version odes not meat the `versions` criteria. +If `silent` is set, the `require` function will return `false` and the error message instead. + ### Returns ### -The module object. +The module object on success, `false, error_message` on error when `silent` is set. ### Availability ### @@ -59,3 +64,4 @@ require("foo", ">=1.1") ### See Also ### * [_PREMAKE_VERSION](globals/premake_PREMAKE_VERSION.md) +* [requireopt](globals/requireopt.md) diff --git a/website/docs/globals/requireopt.md b/website/docs/globals/requireopt.md new file mode 100644 index 0000000000..bbfb0879cb --- /dev/null +++ b/website/docs/globals/requireopt.md @@ -0,0 +1,28 @@ +Require a module or return `false` if module could not be loaded. + + +```lua +requireopt ("modname", "versions") +``` + +`requireopt` is an alias of `require(modname, versions, true)` + +### Returns ### + +* The module on success +* `false`, `error_message` on error + +### Examples ### + +``` +local optionalmodule = require "not-mandatory-but-recommended" +if not optionalmodule +then + premake.warn ("You will not run this at full power") +end +``` + +### See Also ### + +* [require](require.md) +* [dofileopt](dofileopt.md) From f9207c9f5926e38617a2c1890e67e804907b0be0 Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Thu, 14 Jul 2022 19:37:33 +0200 Subject: [PATCH 4/8] Fix typo Co-authored-by: Joris Dauphin --- src/base/globals.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/base/globals.lua b/src/base/globals.lua index 25a9f48bbf..6ad91a0d05 100644 --- a/src/base/globals.lua +++ b/src/base/globals.lua @@ -77,7 +77,7 @@ -- @param silent -- By default, the require function throws an error when the -- module could not be loaded. --- If silent is true, the function will just return false nad the error message. +-- If silent is true, the function will just return false and the error message. -- @return -- If successful, the loaded module, which is also stored into the -- global package.loaded table. From 5eaee3e633207401010eaa6fc6fab327164069ff Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Thu, 14 Jul 2022 19:39:34 +0200 Subject: [PATCH 5/8] Fix typo Co-authored-by: Joris Dauphin --- website/docs/globals/require.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/globals/require.md b/website/docs/globals/require.md index 6a1b2eed02..31a7886b3a 100644 --- a/website/docs/globals/require.md +++ b/website/docs/globals/require.md @@ -14,7 +14,7 @@ Premake will use its [extended set of module locations](Locating-Scripts.md) whe `silent` will change the default error handling behavior. By default, `require` raises an error if the module could not be loaded -or if the module version odes not meat the `versions` criteria. +or if the module version does not meet the `versions` criteria. If `silent` is set, the `require` function will return `false` and the error message instead. From 10abcf3f08c9298f7a7f3bab5941bf4e22f6cf12 Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Thu, 14 Jul 2022 19:50:44 +0200 Subject: [PATCH 6/8] Improve requireopt example --- website/docs/globals/requireopt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/globals/requireopt.md b/website/docs/globals/requireopt.md index bbfb0879cb..a235165431 100644 --- a/website/docs/globals/requireopt.md +++ b/website/docs/globals/requireopt.md @@ -15,10 +15,10 @@ requireopt ("modname", "versions") ### Examples ### ``` -local optionalmodule = require "not-mandatory-but-recommended" +local optionalmodule, message = require "not-mandatory-but-recommended" if not optionalmodule then - premake.warn ("You will not run this at full power") + premake.warn ("You will not run this at full power: " .. message) end ``` From f11555411ed5d6c8979be0bc48f345dbfa16577c Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Fri, 15 Jul 2022 19:44:30 +0200 Subject: [PATCH 7/8] Update website/docs/requireopt.md Co-authored-by: Joris Dauphin --- website/docs/globals/requireopt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/globals/requireopt.md b/website/docs/globals/requireopt.md index a235165431..a89fc9b35b 100644 --- a/website/docs/globals/requireopt.md +++ b/website/docs/globals/requireopt.md @@ -15,7 +15,7 @@ requireopt ("modname", "versions") ### Examples ### ``` -local optionalmodule, message = require "not-mandatory-but-recommended" +local optionalmodule, message = requireopt "not-mandatory-but-recommended" if not optionalmodule then premake.warn ("You will not run this at full power: " .. message) From a52c3c0fcc8d9fb694d3188c281e2f3de4bea782 Mon Sep 17 00:00:00 2001 From: Renaud Guillard Date: Sun, 12 Jan 2025 17:59:48 +0100 Subject: [PATCH 8/8] Rewrite documentation of the `silent` parameter of the `require` function --- website/docs/globals/require.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/website/docs/globals/require.md b/website/docs/globals/require.md index 31a7886b3a..f2235e8e6e 100644 --- a/website/docs/globals/require.md +++ b/website/docs/globals/require.md @@ -12,10 +12,7 @@ Premake will use its [extended set of module locations](Locating-Scripts.md) whe `versions` is an optional string of a version requirements. See the examples below for more information on the format of the requirements string. If the requirements are not met, an error will be raised. -`silent` will change the default error handling behavior. -By default, `require` raises an error if the module could not be loaded -or if the module version does not meet the `versions` criteria. -If `silent` is set, the `require` function will return `false` and the error message instead. +`silent` is not set or set to false, the require function will raise an error if the module fails to load or the version does not meet the criteria set by versions. If silent is set to true, then require shall return a tuple of false and the error message. ### Returns ###