Make broadcast() trigger events consistently + Extend broadcast() docs

- Make broadcast(message, players) fire an event through its Bukkit implementation so that it matches the broadcast(message) and broadcast(message, permission) behaviour.
- Extend broadcast() documentation to include all behaviour.

Author: Pieter12345

src/main/java/com/laytonsmith/abstraction/MCServer.java

@@ -33,6 +33,8 @@ public interface MCServer extends AbstractionObject {
 
 	void broadcastMessage(String message, String permission);
 
+	void broadcastMessage(String message, Set<MCCommandSender> recipients);
+
 	MCConsoleCommandSender getConsole();
 
 	MCItemFactory getItemFactory();

src/main/java/com/laytonsmith/abstraction/bukkit/BukkitMCServer.java

@@ -38,6 +38,7 @@
 import org.bukkit.command.SimpleCommandMap;
 import org.bukkit.entity.Player;
 import org.bukkit.event.inventory.InventoryType;
+import org.bukkit.event.server.BroadcastMessageEvent;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.Recipe;
 
@@ -214,6 +215,35 @@ public void broadcastMessage(String message, String permission) {
 		s.broadcast(message, permission);
 	}
 
+	@Override
+	public void broadcastMessage(String message, Set<MCCommandSender> recipients) {
+
+		// Convert MCCommandsSender recipients to CommandSender recipients.
+		Set<CommandSender> bukkitRecipients = new HashSet<>();
+		if(recipients != null) {
+			for(MCCommandSender mcSender : recipients) {
+				bukkitRecipients.add((CommandSender) mcSender.getHandle());
+			}
+		}
+
+		// Fire a BroadcastMessageEvent for this broadcast.
+		BroadcastMessageEvent broadcastMessageEvent = new BroadcastMessageEvent(message, bukkitRecipients);
+		this.s.getPluginManager().callEvent(broadcastMessageEvent);
+
+		// Return if the event was cancelled.
+		if(broadcastMessageEvent.isCancelled()) {
+			return;
+		}
+
+		// Get the possibly modified message.
+		message = broadcastMessageEvent.getMessage();
+
+		// Perform the actual broadcast to all remaining recipients.
+		for(CommandSender recipient : broadcastMessageEvent.getRecipients()) {
+			recipient.sendMessage(message);
+		}
+	}
+
 	@Override
 	public MCConsoleCommandSender getConsole() {
 		return new BukkitMCConsoleCommandSender(s.getConsoleSender());
@@ -490,8 +520,8 @@ public List<MCRecipe> getRecipesFor(MCItemStack result) {
 	@Override
 	public List<MCRecipe> allRecipes() {
 		List<MCRecipe> ret = new ArrayList<>();
-		for(Iterator recipes = s.recipeIterator(); recipes.hasNext();) {
-			Recipe recipe = (Recipe) recipes.next();
+		for(Iterator<Recipe> recipes = s.recipeIterator(); recipes.hasNext();) {
+			Recipe recipe = recipes.next();
 			ret.add(BukkitConvertor.BukkitGetRecipe(recipe));
 		}
 		return ret;

src/main/java/com/laytonsmith/core/functions/Echoes.java

@@ -30,6 +30,7 @@
 import com.laytonsmith.core.exceptions.ConfigRuntimeException;
 import java.util.Collections;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
 import java.util.TreeMap;
@@ -625,7 +626,10 @@ public Integer[] numArgs() {
 		public String docs() {
 			return "void {message, [permission] | message, [players]} Broadcasts a message to all or some players."
 					+ " If permission is given, only players with that permission will see the broadcast."
-					+ " If an array is given, only players in the list will see the broadcast.";
+					+ " If an array is given, only online players in the list will see the broadcast."
+					+ " Offline players in the list will be ignored."
+					+ " If permission/players is null, all players will see the broadcast."
+					+ " Throws a CREFormatException when the given players array is associative.";
 		}
 
 		@Override
@@ -646,29 +650,41 @@ public CHVersion since() {
 		@Override
 		public Construct exec(Target t, Environment env, Construct... args) throws ConfigRuntimeException {
 			final MCServer server = Static.getServer();
-			String permission = null;
-			if(args.length == 2) {
-				if(args[1] instanceof CArray) {
-					CArray array = (CArray) args[1];
-					if(!array.isAssociative()) {
-						for(Construct p : array.asList()) {
-							try {
-								Static.GetPlayer(p, t).sendMessage(args[0].val());
-							} catch (CREPlayerOfflineException cre) {
-								// ignore offline players
-							}
-						}
-						return CVoid.VOID;
+
+			// Handle "broadcast(message, [null])".
+			if(args.length == 1 || args[1].nval() == null) { // args.length can only be 1 or 2 due to the numArgs().
+				server.broadcastMessage(args[0].val());
+				return CVoid.VOID;
+			}
+
+			// Handle "broadcast(message, playerArray)".
+			if(args[1] instanceof CArray) {
+
+				// Get the CArray and validate that it is non-associative.
+				CArray array = (CArray) args[1];
+				if(array.isAssociative()) {
+					throw new CREFormatException(
+							"Expected a non-associative array or permission as the second parameter.", t);
+				}
+
+				// Get the player recipients from the array.
+				Set<MCCommandSender> recipients = new HashSet<>();
+				for(Construct p : array.asList()) {
+					try {
+						recipients.add(Static.GetPlayer(p, t));
+					} catch (CREPlayerOfflineException cre) {
+						// Ignore offline players.
 					}
-					throw new CREFormatException("Expected a normal array or permission as the second parameter.", t);
 				}
-				permission = args[1].nval();
-			}
-			if(permission == null) {
-				server.broadcastMessage(args[0].val());
-			} else {
-				server.broadcastMessage(args[0].val(), permission);
+
+				// Perform the broadcast and return cvoid.
+				server.broadcastMessage(args[0].val(), recipients);
+				return CVoid.VOID;
 			}
+
+			// Handle "broadcast(message, permission)".
+			String permission = args[1].nval();
+			server.broadcastMessage(args[0].val(), permission);
 			return CVoid.VOID;
 		}