our script
file...Workshop 03: Functions
I hope that you have read the previous workshop, the one about variables. I don't know about you, but I have learned quite a few things about those vars. This chapter will teach you many new and hopefully interesting things about functions.
What are these functions, anyway? Let's see a small example:
function add_numbers( )
{
a
= 3;
b
= 5;
c
= a + b;
}
Do you see what I see? A function is nothing more than a collection of lite-C commands that use vars and stuff like that. Let's see some properties for these functions:
1. A function is defined using the keyword function followed by the name of the function and a pair of parentheses ( ). The parentheses are used to pass additional parameters to the function; in our case we don't pass any parameters, so they are empty.
2. The body of the function (its content) must be written inside a pair of curly brackets { }.
3. The body of the function consists of one or more lines of lite-C code that end with a semicolon.
4. The names used for the functions follow the same naming convention as for variables.
5. You shouldn't use the same name for a var and a function; this will lead to errors.
If you can read this tutorial I hope that you know your age, too. Not in years, but in days! What, you don't know it? You would like us to write a function that computes the number of days? Ok, so let's try to write a function that computes the number of days spent by me (or you) on Earth. It will use some vars, so we'd better define them first:
var my_age = 33; // your age (in years) goes here
var days_a_year = 365;
var number_of_days;
Nothing new so far, right? We have defined three vars and two of them have received initial values, because I know my age in years and I also know that almost every year has 365 days. I'm I little nervous - will this function work?
I know how to start! I write the keyword function and then the name of the function; let's name it compute_days:
function compute_days()
{
I haven't forgotten the parenthesis after the name of the
function and I have added the first curly bracket!
Now comes the scary
part: how will I be able to tell the engine to compute the number of days?
Wait... how would I do it if I would use a pocket calculator? I would do
something like this:
number_of_days = 33 x 365 // number_of_days is just a name for the result
Now let's take a look at our vars; if I replace 33 with my_age and 365 with days_a_year I will get something like this:
number_of_days = my_age x days_a_year
This line starts to look like lite-C but we have to fix
two minor bugs first:
- lite-C uses
* to multiply values, not x
- Every line of
lite-C code must end with a semicolon
Ok, so our function should look like this:
function compute_days()
{
number_of_days = my_age * days_a_year;
}
I have remembered to add the second curly bracket so now the body of the function is enclosed by the two required curly brackets. I am really curious to see if this function works ok, so I have prepared a small script file for our tests. Fire up Lite-C, and then open the script03 file located inside the folder named workshop03:
//////////////////////////////////////////////////////////////////// #include <acknex.h> #include <default.c> var my_age = 33; var days_a_year = 365; var number_of_days; // we need to calculate this value /////////////////////////////////////////////////////////////////// PANEL* pDisplay = { digits (10, 10, 5, *, 1, number_of_days); flags = SHOW; } ///////////////////////////////////////////////////////////////////
The code looks pretty simple, doesn't it? We already know how to work with those vars, we know how to add comments... Let's copy function compute_days from this document and paste it into the script: select the entire text of the function with your mouse, right click, choose Copy, switch to Lite-C, right click the script at the end of the script and then choose Paste to paste the new function right before the main() function. The result should look like this:
//////////////////////////////////////////////////////////////////// #include <acknex.h> #include <default.c> var my_age = 33; var days_a_year = 365; var number_of_days; // we need to calculate this value /////////////////////////////////////////////////////////////////// PANEL* pDisplay = { digits (10, 10, 5, *, 1, number_of_days); flags = SHOW; } /////////////////////////////////////////////////////////////////// function compute_days() { number_of_days = my_age * days_a_year; }
Let's Test Run our script
file...
It works... but nothing has happened! I can see a black screen and a zero... I am zero days old? I thought that I am much older! There must be something wrong with this code... I know that I have copied the function correctly! What should I do?
Well, we wrote a function that is supposed to run ok, but we haven't "called" it, we didn't make it start. Let's imagine that you want to celebrate your birthday and you hire a band. They arrive at your house and they sit in a corner without doing anything, waiting for your command. And you stand there, you don't tell them to start playing and you are wondering why you can't hear their music... The same thing happens with our function: we write its code, but then we must tell it to run.
Ok, so now we're getting somewhere: how do I run my new function? Let's type a line that calls the function inside a new function main, just like in the picture below:
////////////////////////////////////////////////////////////////////
#include <acknex.h>
#include <default.c>
var my_age = 33;
var days_a_year = 365;
var number_of_days; // we need to calculate this value
///////////////////////////////////////////////////////////////////
PANEL* pDisplay =
{
digits (10, 10, 5, *, 1, number_of_days);
flags = SHOW;
}
///////////////////////////////////////////////////////////////////
function compute_days()
{
number_of_days = my_age * days_a_year;
}
function main()
{
screen_size.x = 800;
screen_size.y = 600;
screen_color.blue = 150;
compute_days();
}
Time to Test Run our level again...
Ok, this time it worked, but I'm not sure what happened; is function main() special or what? Yes, main is a predefined function name, so don't try to create another function and name it main. This special function will run by itself every time we start our script. Let's take a look at the code inside main:
function main()
{
screen_color.blue = 150;
compute_days();
}
The way I see it, the code calls (it runs) our function (after having set the screen color). Ok, now that we are here let's see how we call a function: we write its name followed by a pair of parenthesis and then we end the lite-C line of code with a semicolon. Sounds logical, doesn't it?
Important tip: write the lines of code for your functions first and call them later. The engine reads the code the same way you read a book: it starts with the top of the script page and goes down to the bottom, reading the code line by line. If I would write my script this way
function main()
{
compute_days();
}
function compute_days()
{
number_of_days = my_age *
days_a_year;
}
the engine will say: oh, that's function main. I know function main; I need to run it every time. What does it say now? compute_days(). What's with this function? I don't know it! I don't know what it wants from me. I'm going to display an error message and I will take the rest of the day off:
Don't forget to define your function first, otherwise the engine will complain when you try to use it.
By the way, what is it with these strange lines
#include <acknex.h>
#include <default.c>
that always appear at the top of the code? #include adds another piece of code to our program. acknex.h is the standard code we need always for a Pure Mode program (remember the first lesson?) and which contains all predefined variables and engine functions. And default.c contains some often-needed functions, like the console mode from the last lesson, and the ability to quit the program by pressing [Esc]. Both files can be found in the include folder. Omit the '#include <default.c>' line and [Esc] won't work anymore! If there's no #include at all at the begining of our script, both files are automatically included, though.
Aren't you anxious to learn more? Our journey through the wonderful world of lite-C proves to be pretty easy thus far, doesn't it? The following workshop will teach us how to create panels: elements that can display all kinds of figures, bars, etc. Whenever you see a picture or a figure on the screen, there's a panel definition behind it.