allow log styles to throw errors + doc cleanup

flixel/system/debug/log/Log.hx

@@ -17,7 +17,7 @@ class Log extends Window
 	var _lines:Array<String>;
 
 	/**
-	 * Creates a log window object.
+	 * Creates a log window object
 	 */
 	public function new()
 	{
@@ -37,7 +37,7 @@ class Log extends Window
 	}
 
 	/**
-	 * Clean up memory.
+	 * Clean up memory
 	 */
 	override public function destroy():Void
 	{
@@ -53,37 +53,27 @@ class Log extends Window
 
 	/**
 	 * Adds a new line to the log window.
-	 * @param 	Data		The data being logged.
-	 * @param 	Style		The LogStyle to be used for the log
-	 * @param 	FireOnce   	Whether you only want to log the Data in case it hasn't been added already
+	 * 
+	 * @param   data      The data being logged
+	 * @param   style     The LogStyle to be used
+	 * @param   fireOnce  If true, the log history is checked for matching logs
 	 */
-	public function add(Data:Array<Dynamic>, Style:LogStyle, FireOnce:Bool = false):Bool
+	public function add(data:Array<Dynamic>, style:LogStyle, fireOnce = false):Bool
 	{
-		if (Data == null)
+		if (data == null)
 		{
 			return false;
 		}
-
-		var texts:Array<String> = new Array<String>();
-
-		// Format FlxPoints, Arrays, Maps or turn the Data entry into a String
-		for (i in 0...Data.length)
-		{
-			texts[i] = Std.string(Data[i]);
-
-			// Make sure you can't insert html tags
-			texts[i] = StringTools.htmlEscape(texts[i]);
-		}
-
-		var text:String = Style.prefix + texts.join(" ");
-
+
 		// Apply text formatting
 		#if (!js && !lime_console)
-		text = flixel.util.FlxStringUtil.htmlFormat(text, Style.size, Style.color, Style.bold, Style.italic, Style.underlined);
+		final text = style.toHtmlString(data);
+		#else
+		final text = style.toLogString(data);
 		#end
-
+		
 		// Check if the text has been added yet already
-		if (FireOnce)
+		if (fireOnce)
 		{
 			for (line in _lines)
 			{

flixel/system/debug/log/LogStyle.hx

@@ -1,7 +1,9 @@
 package flixel.system.debug.log;
 
+using flixel.util.FlxStringUtil;
+
 /**
- * A class that allows you to create a custom style for FlxG.log.advanced().
+ * A class that allows you to create a custom style for `FlxG.log.advanced()`.
  * Also used internally for the pre-defined styles.
  */
 class LogStyle
@@ -13,7 +15,7 @@ class LogStyle
 	public static var CONSOLE:LogStyle = new LogStyle("> ", "5A96FA", 12, false);
 
 	/**
-	 * A prefix which is always attached to the start of the logged data.
+	 * A prefix which is always attached to the start of the logged data
 	 */
 	public var prefix:String;
 
@@ -24,44 +26,83 @@ class LogStyle
 	public var underlined:Bool;
 
 	/**
-	 * A sound to be played when this LogStyle is used.
+	 * A sound to be played when this LogStyle is used
 	 */
 	public var errorSound:String;
 
 	/**
-	 * Whether the console should be forced to open when this LogStyle is used.
+	 * Whether the console should be forced to open when this LogStyle is used
 	 */
 	public var openConsole:Bool;
 
 	/**
-	 * A callback function that is called when this LogStyle is used.
+	 * A callback function that is called when this LogStyle is used
 	 */
-	public var callbackFunction:Void->Void;
+	public var callbackFunction:()->Void;
 
 	/**
-	 * Create a new LogStyle to be used in conjunction with FlxG.log.advanced()
+	 * Whether an exception is thrown when this LogStyle is used.
+	 * **Note**: Unlike other log style properties, this happens even in release mode.
+	 * @since 5.4.0
+	 */
+	public var throwException:Bool = false;
+
+	/**
+	 * Create a new LogStyle to be used in conjunction with `FlxG.log.advanced()`
 	 *
-	 * @param	Prefix				A prefix which is always attached to the start of the logged data.
-	 * @param	Color				The text color.
-	 * @param	Size				The text size.
-	 * @param 	Bold				Whether the text is bold or not.
-	 * @param	Italic				Whether the text is italic or not.
-	 * @param	Underlined			Whether the text is underlined or not.
-	 * @param	ErrorSound			A sound to be played when this LogStyle is used.
-	 * @param	OpenConsole			Whether the console should be forced to open when this LogStyle is used.
-	 * @param	CallbackFunction	A callback function that is called when this LogStyle is used.
+	 * @param   prefix       A prefix which is always attached to the start of the logged data
+	 * @param   color        The text color
+	 * @param   size         The text size
+	 * @param   bold         Whether the text is bold or not
+	 * @param   italic       Whether the text is italic or not
+	 * @param   underlined   Whether the text is underlined or not
+	 * @param   errorSound   A sound to be played when this LogStyle is used
+	 * @param   openConsole  Whether the console should be forced to open when this LogStyle is used
+	 * @param   callback     A callback function that is called when this LogStyle is used
+	 * @param   throwError   Whether an error is thrown when this LogStyle is used
+	 */
+	public function new(prefix = "", color = "FFFFFF", size = 12, bold = false, italic = false, underlined = false,
+			?errorSound:String, openConsole = false, ?callback:()->Void, throwException = false)
+	{
+		this.prefix = prefix;
+		this.color = color;
+		this.size = size;
+		this.bold = bold;
+		this.italic = italic;
+		this.underlined = underlined;
+		this.errorSound = errorSound;
+		this.openConsole = openConsole;
+		this.callbackFunction = callback;
+		this.throwException = throwException;
+	}
+
+	/**
+	 * Converts the data into a log message according to this style.
+	 * 
+	 * @param   data  The data being logged
+	 */
+	public function toLogString(data:Array<Any>)
+	{
+		// Format FlxPoints, Arrays, Maps or turn the data entry into a String
+		final texts = new Array<String>();
+		for (i in 0...data.length)
+		{
+			final text = Std.string(data[i]);
+
+			// Make sure you can't insert html tags
+			texts.push(StringTools.htmlEscape(text));
+		}
+
+		return prefix + texts.join(" ");
+	}
+
+	/**
+	 * Converts the data into an html log message according to this style.
+	 * 
+	 * @param   data  The data being logged
 	 */
-	public function new(Prefix:String = "", Color:String = "FFFFFF", Size:Int = 12, Bold:Bool = false, Italic:Bool = false, Underlined:Bool = false,
-			?ErrorSound:String, OpenConsole:Bool = false, ?CallbackFunction:Void->Void)
+	public inline function toHtmlString(data:Array<Any>)
 	{
-		prefix = Prefix;
-		color = Color;
-		size = Size;
-		bold = Bold;
-		italic = Italic;
-		underlined = Underlined;
-		errorSound = ErrorSound;
-		openConsole = OpenConsole;
-		callbackFunction = CallbackFunction;
+		return toLogString(data).htmlFormat(size, color, bold, italic, underlined);
 	}
 }

flixel/system/frontEnds/LogFrontEnd.hx

@@ -3,7 +3,6 @@ package flixel.system.frontEnds;
 import flixel.FlxG;
 import flixel.system.debug.log.LogStyle;
 import flixel.system.FlxAssets;
-import haxe.Log;
 import haxe.PosInfos;
 
 /**
@@ -16,87 +15,70 @@ class LogFrontEnd
 	 */
 	public var redirectTraces(default, set):Bool = false;
 
-	var _standardTraceFunction:Dynamic->?PosInfos->Void;
+	var _standardTraceFunction:(Dynamic, ?PosInfos)->Void;
 
-	public inline function add(Data:Dynamic):Void
+	public inline function add(data:Dynamic):Void
 	{
-		#if FLX_DEBUG
-		advanced(Data, LogStyle.NORMAL);
-		#end
+		advanced(data, LogStyle.NORMAL);
 	}
 
-	public inline function warn(Data:Dynamic):Void
+	public inline function warn(data:Dynamic):Void
 	{
-		#if FLX_DEBUG
-		advanced(Data, LogStyle.WARNING, true);
-		#end
+		advanced(data, LogStyle.WARNING, true);
 	}
 
-	public inline function error(Data:Dynamic):Void
+	public inline function error(data:Dynamic):Void
 	{
-		#if FLX_DEBUG
-		advanced(Data, LogStyle.ERROR, true);
-		#end
+		advanced(data, LogStyle.ERROR, true);
 	}
 
-	public inline function notice(Data:Dynamic):Void
+	public inline function notice(data:Dynamic):Void
 	{
-		#if FLX_DEBUG
-		advanced(Data, LogStyle.NOTICE);
-		#end
+		advanced(data, LogStyle.NOTICE);
 	}
 
 	/**
 	 * Add an advanced log message to the debugger by also specifying a LogStyle. Backend to FlxG.log.add(), FlxG.log.warn(), FlxG.log.error() and FlxG.log.notice().
 	 *
-	 * @param	Data  		Any Data to log.
-	 * @param  	Style   	The LogStyle to use, for example LogStyle.WARNING. You can also create your own by importing the LogStyle class.
-	 * @param  	FireOnce   	Whether you only want to log the Data in case it hasn't been added already
+	 * @param   data      Any Data to log.
+	 * @param   style     The LogStyle to use, for example LogStyle.WARNING. You can also create your own by importing the LogStyle class.
+	 * @param   fireOnce  Whether you only want to log the Data in case it hasn't been added already
 	 */
-	public function advanced(Data:Dynamic, ?Style:LogStyle, FireOnce:Bool = false):Void
+	public function advanced(data:Dynamic, ?style:LogStyle, fireOnce = false):Void
 	{
+		if (style == null)
+			style = LogStyle.NORMAL;
+
+		if (!(data is Array))
+			data = [data];
+
 		#if FLX_DEBUG
 		// Check null game since `FlxG.save.bind` may be called before `new FlxGame`
 		if (FlxG.game == null || FlxG.game.debugger == null)
 		{
-			_standardTraceFunction(Data);
-			return;
+			_standardTraceFunction(data);
 		}
-
-		if (Style == null)
-		{
-			Style = LogStyle.NORMAL;
-		}
-
-		if (!(Data is Array))
-		{
-			Data = [Data];
-		}
-
-		if (FlxG.game.debugger.log.add(Data, Style, FireOnce))
+		else if (FlxG.game.debugger.log.add(data, style, fireOnce))
 		{
 			#if (FLX_SOUND_SYSTEM && !FLX_UNIT_TEST)
-			if (Style.errorSound != null)
+			if (style.errorSound != null)
 			{
-				var sound = FlxAssets.getSound(Style.errorSound);
+				final sound = FlxAssets.getSound(style.errorSound);
 				if (sound != null)
-				{
 					FlxG.sound.load(sound).play();
-				}
 			}
 			#end
-
-			if (Style.openConsole)
-			{
+
+			if (style.openConsole)
 				FlxG.debugger.visible = true;
-			}
-
-			if (Style.callbackFunction != null)
-			{
-				Style.callbackFunction();
-			}
+
+			if (style.callbackFunction != null)
+				style.callbackFunction();
 		}
 		#end
+
+		if (style.throwException)
+			throw style.toLogString(data);
 	}
 
 	/**
@@ -115,25 +97,25 @@ class LogFrontEnd
 		_standardTraceFunction = haxe.Log.trace;
 	}
 
-	inline function set_redirectTraces(Redirect:Bool):Bool
+	inline function set_redirectTraces(redirect:Bool):Bool
 	{
-		Log.trace = (Redirect) ? processTraceData : _standardTraceFunction;
-		return redirectTraces = Redirect;
+		haxe.Log.trace = (redirect) ? processTraceData : _standardTraceFunction;
+		return redirectTraces = redirect;
 	}
 
 	/**
 	 * Internal function used as a interface between trace() and add().
 	 *
-	 * @param	Data	The data that has been traced
-	 * @param	Inf		Information about the position at which trace() was called
+	 * @param   data  The data that has been traced
+	 * @param   info  Information about the position at which trace() was called
 	 */
-	function processTraceData(Data:Dynamic, ?Info:PosInfos):Void
+	function processTraceData(data:Dynamic, ?info:PosInfos):Void
 	{
-		var paramArray:Array<Dynamic> = [Data];
+		var paramArray:Array<Dynamic> = [data];
 
-		if (Info.customParams != null)
+		if (info.customParams != null)
 		{
-			for (i in Info.customParams)
+			for (i in info.customParams)
 			{
 				paramArray.push(i);
 			}