Added API for source deprecation

Author: nickclark2016

src/base/action.lua

@@ -38,6 +38,8 @@
 --
 
 	action._list = {}
+	action._aliases = {}
+	action._deprecatedaliases = {}
 
 
 ---
@@ -68,6 +70,29 @@
 		end
 
 		action._list[act.trigger] = act
+
+		-- Add aliases table
+		if act.aliases then
+			table.foreachi(act.aliases, function(alias)
+				action._aliases[alias] = act.trigger
+			end)
+		end
+
+		-- Add deprecated aliases table
+		if act.deprecatedaliases then
+			for key, value in pairs(act.deprecatedaliases) do
+				action._deprecatedaliases[key] = value
+
+				-- Check to see if the deprecated alias is in the alias table for the action
+				if not table.contains(act.aliases, key) then
+					p.warnOnce(act.trigger .. ' missing alias',
+						"action '" .. act.trigger .. "' has a deprecated alias '" .. key .. "' that is not in the " ..
+						" 'aliases' table. This alias will be added to the 'aliases' table automatically."
+					)
+					action._aliases[key] = act.trigger
+				end
+			end
+		end
 	end
 
 
@@ -145,6 +170,11 @@
 	end
 
 
+	function action.resolvealias(name)
+		return action._aliases[name] or name
+	end
+
+
 ---
 -- Retrieve an action by name.
 --
@@ -155,7 +185,13 @@
 ---
 
 	function action.get(name)
-		return action._list[name]
+		local resolved = action.resolvealias(name)
+		return action._list[resolved]
+	end
+
+
+	function action.deprecatedalias(name)
+		return action._deprecatedaliases[name]
 	end
 
 
@@ -209,10 +245,22 @@
 ---
 
 	function action.set(name)
-		_ACTION = name
+		-- If the action is an alias, resolve it to the real action
+		local resolved = action._aliases[name] or name
+
+		-- If the action is a deprecated alias, warn the user
+		local deprecated = action._deprecatedaliases[name]
+		if deprecated then
+			local onaction = deprecated["action"]
+			if onaction ~= nil and type(onaction) == "function" then
+				onaction()
+			end
+		end
+
+		_ACTION = resolved
 
 		-- Some actions imply a particular operating system or architecture
-		local act = action.get(name)
+		local act = action.get(resolved)
 		if act then
 			_TARGET_OS = act.targetos or _TARGET_OS
 			_TARGET_ARCH =  act.targetarch or _TARGET_ARCH

src/base/criteria.lua

@@ -117,6 +117,19 @@
 					end
 				end
 
+				-- Check if the prefix is an action
+				if prefix == "action" or prefix == "_action" then
+					local actname = word[1]
+					-- Resolve the action alias
+					word[1] = p.action.resolvealias(actname)
+
+					-- Check if the action was deprecated
+					local actiondeprecation = p.action.deprecatedalias(actname)
+					if actiondeprecation ~= nil and actiondeprecation.filter ~= nil and type(actiondeprecation.filter) == "function" then
+						actiondeprecation.filter()
+					end
+				end
+
 				table.insert(pattern, word)
 			end
 

website/docs/newaction.md

@@ -28,6 +28,8 @@ newaction { description }
 | onCleanProject  | A callback for each project, when the clean action is selected. |
 | onCleanTarget   | A callback for each target, when the clean action is selected. |
 | pathVars    | A map of Premake tokens to toolset specific identifiers. |
+| aliases | A list of action names to alias to this action. |
+| deprecatedaliases | A table containing a mapping of aliases to callbacks to invoke on action invocation and filters containing the deprecated alias. Each value in the deprecatedaliases table is a table optionally containing an "action" and "filter" key. The values in this table are functions taking zero arguments. See the example below. |
 
 The callbacks will fire in this order:
 
@@ -66,6 +68,26 @@ newaction {
 }
 ```
 
+Register a new action with aliases and deprecations.
+
+```lua
+newaction {
+   trigger           = "myaction",
+   description       = "Custom action",
+   aliases           = { "myalias", "deprecatedalias" },
+   deprecatedaliases = {
+      ["deprecatedalias" ] = {
+         [ "action" ] = function()
+                           p.warn("Use myaction instead of deprecatedalias.") 
+                        end,
+         [ "filter" ] = function()
+                           p.warn("deprecatedalias has been deprecated. Filter on myaction instead.") 
+                        end
+      }
+   }
+}
+```
+
 ### See Also ###
 
 * [Command Line Arguments](Command-Line-Arguments.md)