this article explains the user defined function in KSP. At the end of this article there is also a comparison between classic and advanced functions with sublime text.
1. Content
What’s a (user defined) function?
a “user defined function” – or in other programming languages just called “function” – is a set of instructions that perform a specific task. Thereby we can perform one and the same task over and over again by calling the function throughout our code. This saves time and reduces the amount of code needed. In simpler terms, a function is like a blueprint that we can use over and over again to automatically build the same thing with different (amounts of) material.
Usually functions also accept input values (also named parameters), and return values. However classic KSP user defined functions don’t. There are also advanced functions with sublime text which can do partly.
If you want to learn more about advanced function read “advanced functions with arguments & local variables “
USER-DEFINED FUNCTIONS explained
syntax: declaring a function
function <function_name>
message("classic user defined function")
end function
DECLARING A FUNCTION
- we declare a function by using the term “function” followed by any name we define for our function similar to a variable name.
- we close the function via “end function”.
- we can then include code instructions inside
function ... end functionthat is performed whenever the function is called.
Syntax: calling a function
call <function_name>
CALLING A FUNCTION
- once declared, we can execute (or call) the function via
call <function_name> - we can only call functions inside other functions and callbacks like the
on ui_control,on note,on releaseoron async_completecallback. - however unfortunately we can not call functions inside the
on initcallback. This is only possible in sublime text.
IMPORTANT: Unlike many other programming languages, in KSP a function must be declared before it is called (also see below under special notes)!
SPECIAL NOTES
- a function can only be called after it has been declared:
{##### THIS WILL WORK #####} on init declare ui_button $button end on function myFunction message("works") end function on ui_control ($button) call myFunction end on {###### THIS WILL NOT WORK #######} on init declare ui_button $button end on on ui_control ($button) call myFunction end on function myFunction message("works") end function
- functions CAN NOT be called inside the on init callback:
(advanced functions can be called inside the on init though){THIS IS NOT ALLOWED AND PRODUCES AN ERROR} function myFunction message("works") end function on init call myFunction end on
what is (not) possible compared to other languages:
arguments / parameters / passing values
we can not use arguments to pass values, objects or other functions into a classic ksp function.
we can use global variables to “inject values”, though. But only values, no objects or other functions (see the example below)
we can define functions with arguments in Sublime Text. But we can also only pass values.
local variables
local variables do not exist in KSP.
Instead we have to use the usual global variables that we have declared inside the on init. With advanced functions in sublime text we can also declare variables inside the function itself. Due to the compilation process, these variables behave at least like local variables, but also have a global scope.
What are local & global variables? Learn more
callback functions
we can not build callback functions
A callback function is a function that is passed as an argument to another function and is then called when the other function finishes its execution. This allows for more flexible and dynamic programming, especially in event-driven and asynchronous programming.
Instead, we can call another function within a function, e.g. if certain conditions are true.
NOTE: in this case the other function must also be declared before it can be called in classic KSP, which limits certain applications.
allowed scope for functions
KSP functions can only be called inside other functions and callbacks, like in the on control, on async_complete or on note callback. They can not be called in the on init callback.
Example
on init
declare ui_button $call_me
declare $x
$x := 0
declare @times
declare @placeholder
make_perfview
end on
function classic_function
inc($x)
if($x = 1)
@times := " time"
else
@times := " times"
end if
message(@placeholder & "you called me " & $x & " " & @times)
end function
on ui_control($call_me)
@placeholder := "on ui_control: "
call classic_function
end on
on async_complete
@placeholder := "on async_complete: "
call classic_function
end on
WHAT THE FUNCTION DOES:
This simple function counts the number of calls and outputs the total calls, with a dynamic text that changes depending on where the call was made.
The function is called inside a on ui_control callback when pressing a simple button. Or it is also called on async_complete.
> By pressing the call_me button
this will output “on ui_control: you called me x times”. Where x is the count
> On async_complete
this will output “on async_complete: you called me x times”. Where x is the count
THE COUNTER
To increase the counter we use a global variable $x which will be increased inside the function with each call of the function.
PASSING VALUES:
We further use a global string variable @placeholder from outside the function to “pass” a string value into the function. But since the variable can not be local and since we can’t assign individual arguments to functions this is not as convenient as in other programming languages but it works!
@TIMES
We can ignore the whole @times if case. This is just to add a little sugar to the whole thing .. grammatical correctness, you know.
It simply switches the word “time” to plural “times” so that it says “you called me 1 time” at the first call and “you called me 2 times” from the second call.
CALLING THE FUNCTION
we call the function via call classic_function inside the on ui_control($call_me) callback when hitting the button. Learn all about the on ui_control callback here.
it gets also called automatically on async_complete. An async_complete call won’t happen in this script though.
IMPORTANT: again, a classic function has to be declared before it is called. So this won’t work:
on init
declare ui_button $call_me
make_perfview
end on
{THIS PRODUCES AN ERROR, because the function is defined below the call}
on ui_control($call_me)
call classic_function
end on
function classic_function
message("I'm a classic function")
end function
Classic vs Advanced user defined functions
In Sublime Text we got more possibilities with user defined functions. Here is a comparison between the classic KSP functions and the more advanced functions in Sublime Text.
If you want to learn more about advanced functions read “advanced functions with arguments & local variables “
| advanced function (Sublime Text) |
classic function | |
|---|---|---|
| arguments / parameters | only virtually |
|
| local variables | only virtually |
|
| can be called anywhere | | not inside the on init |
| can be defined anywhere | | |
| user-defined callback functions | | |
Leave a Reply