Ultraschall Api
Feature of the Week #1
Before we start with cool features, I would love to introduce you to a very helpful feature in day-to-day-programming, which usually means: fixing bugs.
One of the main problems of fixing bugs are cryptic error-messages or even worse: error-codes.
I hate that and if you're programming a lot, you probably hate it too.
So I added an error-messaging system. You can do a lot with it, but I want to focus on one aspect that's most useful for you.
All API-functions create useful error-messages, when a problem arises. Yes, all of them!
So let me introduce to you:
ShowLastErrorMessage
This function is simple. If an error happened in one of the Ultraschall-API-functions, calling this function will open a messagebox showing you the problematic function, the problematic parametername(if applicable) and the error-message. It will be the last error that occurred, before calling ShowLastErrorMessage.
So let's assume, you want to read a file using
ReadFullFile, but for some reasons, you don't give the function a filename, but rather something else, like the number "1"
Code:
-- let's add the Ultraschall-API to our script
dofile(reaper.GetResourcePath().."/UserPlugins/ultraschall_api.lua")
-- let's pass a wrong parameter to this function
ultraschall.ReadFullFile(1)
-- see, whether we produced an error
ultraschall.ShowLastErrorMessage()
When we run this script, ShowLastErrorMessage will show us, that the first parameter filename_with_path must be a string, which tells us: it can't be a number.
PS: if you pass to ReadFullFile a filename of a file that doesn't exist, it will raise the error that the file does not exist, that you passed in parameter filename_with_path, when running ShowLastErrorMessage.
So everytime you pass a wrong value into a parameter or something else goes wrong, it will show you, what went wrong.
Include this function into your prayers, as it will quickly help you finding obvious bugs in your scripts.
I added this as programming-sugar for all of you, but quickly understood, how helpful it is for me as well.
I often put this at the end of my script, so it will show me the last error that happened in my script, if at all. If you have weird behaving functions, you should include ShowLastErrorMessage after the weird behaving functions to see, if it created an error.
This is especially useful for those of you, who use an external editor, but if you use Reaper's own ReaScript-IDE, it is helpful as well.
If you are programming in the ReaScript-IDE and want to have the error-messages shown at the bottom, just as any other error-message by Reaper or Lua, you can use another nice function:
ToggleIDE_Errormessages
This toggles, whether error-messages shall be shown like any other ReaScript/Reaper-API-function/Lua-error at the bottom of the IDE or in an error-window opened, while the IDE is closed.
Whatever you prefer, getting useful debug-information by Ultraschall-API-functions isn't hard.
PS: I mostly use ShowLastErrorMessage and I love it
PSPS: It works only for Ultraschall-API-functions. Reaper's own functions don't create such error-messages, though I already think about, how to do that as well. Maybe some day...