Added Helpers library

Examples/Helpers/HL_Convert_BytesTo.hws

@@ -0,0 +1,24 @@
+/*
+**************************************************
+*** Helpers.hws Example : HL.Convert.BytesTo() ***
+**************************************************
+*/
+
+@INCLUDE "../../+Includes.hws"
+@INCLUDE #INC_HELPERS
+
+NPrint("HL.Convert.BytesTo Example")
+NPrint("--------------------------\n")
+
+Local bytes = 24589798800
+Local decimals = 2
+
+NPrint("Converting " .. bytes .. " bytes to")
+NPrint("   Kb : " .. HL.Convert.BytesTo(bytes, #HL_KILOBYTES, decimals))
+NPrint("   Mb : " .. HL.Convert.BytesTo(bytes, #HL_MEGABYTES, decimals))
+NPrint("   Gb : " .. HL.Convert.BytesTo(bytes, #HL_GIGABYTES, decimals))
+NPrint("   Tb : " .. HL.Convert.BytesTo(bytes, #HL_TERABYTES, decimals))
+NPrint(" Auto : " .. HL.Convert.BytesTo(bytes, #HL_AUTO, decimals))
+
+NPrint("\n--- Left mouse button to quit ---")
+WaitLeftMouse()

Examples/Helpers/HL_ParseRunArgs.hws

@@ -0,0 +1,22 @@
+/*
+***********************************************
+*** Helpers.hws Example : HL.ParseRunArgs() ***
+***********************************************
+************************************************************************
+*** THIS EXAMPLE MUST BE COMPILED AND EXECUTED USING THE COMMANDLINE ***
+***                WITH SOME Argument - value PAIRS                  ***
+***     Example: prompt>compiled.exe -param1 first -param2 second    ***
+************************************************************************
+*/
+
+@INCLUDE "../../+Includes.hws"
+@INCLUDE #INC_HELPERS
+
+NPrint("HL.ParseRunArgs Example")
+NPrint("---------------------\n")
+
+Local Arguments = HL.ParseRunArgs(False)
+ForEach(Arguments, NPrint)
+
+NPrint("\n--- Left mouse button to quit ---")
+WaitLeftMouse()

Examples/Helpers/HL_Safe.hws

@@ -0,0 +1,18 @@
+/*
+***************************************
+*** Helpers.hws Example : HL.Safe() ***
+***************************************
+*/
+
+@INCLUDE "../../+Includes.hws"
+@INCLUDE #INC_HELPERS
+
+NPrint("HL.Safe Example")
+NPrint("---------------\n")
+
+Local Uninitialized = Nil
+Local initialized = "Hello!"
+NPrint(HL.Safe(Uninitialized) .. " - " .. HL.Safe(Initialized))
+
+NPrint("\n--- Left mouse button to quit ---")
+WaitLeftMouse()

Examples/Helpers/HL_SizeString.hws

@@ -0,0 +1,40 @@
+/*
+*********************************************
+*** Helpers.hws Example : HL.SizeString() ***
+*********************************************
+*/
+
+@INCLUDE "../../+Includes.hws"
+@INCLUDE #INC_HELPERS
+
+NPrint("HL.SizeString Example")
+NPrint("---------------------\n")
+
+; Suppose you have 40 character screen and a table with <n> entries with the
+; fields <name> and <surnames>, you want to print a table with these
+; informations:
+
+; Initialize the table with some items
+Local people =
+   { { name = "Clark", surname = "Kent"   },
+     { name = "Peter", surname = "Parker" },
+     { name = "Bruce", surname = "Wayne"  } }
+
+; Now we will print a nice table to the screen with the first column of 14
+; characters and the second one of 22 (plus 3 separators):
+
+; Header
+NPrint("|" .. HL.SizeString("NAME", 14) .. "|" .. HL.SizeString("SURNAME", 22) .. "|")
+
+; Contents
+For Local i = 0 To 2
+   NPrint("|" .. HL.SizeString(people[i].name, 14) ..
+          "|" .. HL.SizeString(people[i].surname, 22) .. "|")
+Next
+
+; Exemple with string exceeding the available space
+NPrint("|" .. HL.SizeString("This is an extremely long line!", 14) ..
+       "|" .. HL.SizeString("Another line, see how it works?", 22) .. "|")
+
+NPrint("\n--- Left mouse button to quit ---")
+WaitLeftMouse()

Examples/Helpers/HL_Value2Perc.hws

@@ -0,0 +1,19 @@
+/*
+*********************************************
+*** Helpers.hws Example : HL.Value2Perc() ***
+*********************************************
+*/
+
+@INCLUDE "../../+Includes.hws"
+@INCLUDE #INC_HELPERS
+
+NPrint("HL.Value2Perc Example")
+NPrint("---------------------\n")
+
+NPrint("1) Range=( 1: 100), Value= 89, Converted=" .. HL.Value2Perc({ 1,  100},  89))
+NPrint("2) Range=(21: 120), Value=109, Converted=" .. HL.Value2Perc({21,  120}, 109))
+NPrint("3) Range=(40:1500), Value= 91, Converted=" .. HL.Value2Perc({40, 1500},  91))
+NPrint("4) Range=( 5:  70), Value=104, Converted=" .. HL.Value2Perc({ 5,   70}, 104))
+
+NPrint("\n--- Left mouse button to quit ---")
+WaitLeftMouse()

Examples/Helpers/HL_WaitForAction.hws

@@ -0,0 +1,33 @@
+/*
+************************************************
+*** Helpers.hws Example : HL.WaitForAction() ***
+************************************************
+*/
+
+@INCLUDE "../../+Includes.hws"
+@INCLUDE #INC_HELPERS
+
+Function update_callback() 
+  If IsKeyDown("SPACE")
+    Return(True)
+  Else
+    Return(False)
+  EndIf
+  
+EndFunction
+
+Function timeout_callback()
+  NPrint("TIMED OUT!!!")
+  
+EndFunction
+
+NPrint("HL.WaitForAction Example")
+NPrint("------------------------\n")
+
+NPrint("Hold down the 'p' key or the left mouse button, timeout is 10 seconds...")
+NPrint("SPACE key is used to break the wait loop.")
+HL.WaitForAction("p", 25, update_callback, 10000, timeout_callback, Nil)
+
+NPrint("\n--- Left mouse button to quit ---")
+Wait(50)
+WaitLeftMouse()

Helpers_license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2025 Fabio Falcucci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.