startup: // do something return;Although some commonly refer to a block of code beginning with a message name and ending with a return as a "message," this is a misuse of the term. It should be called a message handler. The message itself is what JK sends to the cog. The cog's code will "handle" that message. A message name ended with a colon in the code section is called a label. Labels are like starting points in the code section. JK will start executing code right after a label and stop executing when the return command is given or when JK reaches the end of the cog.
The engine is not the only thing that can send messages. There are commands that we can use to send messages to cogs the same way the engine does.
var2 = var1;The '=' is the operator and var1 and var2 are the operands. The semicolon at the end marks the end of the statement. Here's a more complicated example:
var2 = var1 * var3;Here there are two operations: the assignment of var2 and the multiplication of var1 and var3. The multiplication has a higher precedence (refer to the Precedence Chart) and will be performed first. Then JK will assign var2 to the resultant value. You should already be familiar with mathmatical operations involving multiple operators and parentheses.
Assignments are easy to use as examples because they form a statement and nothing else has to be explained for you to understand them. Some languages treat assignments as operations that return a value - so you could write y = x = 1, and y would get the value of 1. Cog does not allow this, though.
You'll see operations used in many places throughout cog. In any place in the code section that you can input a value, you can give an equation, a variable, or a verb that returns a value (a function - which we'll cover later).
return
works to end code execution, and how
end
ends both the code and symbols sections. Other common keywords include if, for, while, do, else, and call. These other keywords
will be covered later on.
But you will also hear these commands refered to as procedures or functions. A procedure is a command that simply performs an action, and a fuction is a command that performs an action and then returns a value to whatever is assigned to it.
A typical procedure will look like this:
DoSomething();The syntax here is simple. The procedure has a name, followed by a set of parentheses to enclose its parameters, and then a semicolon to end the command. The standard naming convention for verbs is camel-hump notation with the first letter capitalized - at least, that's what this reference will use.
All verbs have a set of parentheses to enclose their parameters. In programming, a parameter is an allotted space for an argument (variable or value) to be passed to the verb. When an argument is passed to a verb, the verb will use that value to perform whatever command it is meant to do. It is important to remember that a parameter is only a space for a type of variable; parameters do not have a value - arguments are the values. The example procedure above has no parameters, but it still must have the parentheses. This procedure has three parameters:
DoSomethingMore(1, 2, var3);The first two arguments are given directly as numbers, but the third argument is a variable. The value of this variable will be used by the procedure - the variable will not be changed (this is known as passing by value). When used by themselves, verbs form a complete statement and end with a semicolon.
A function works much the same as a procedure, but the function will return a value to any variable assigned to it. A typical function will look like:
myVar = ReturnSomething();myVar is a variable that you have declared in your symbols section. The equals sign is cog's assignment operator - the value taken from the right will be given to the variable on the left (right-to-left Associativity). The function does not need to have a variable assigned to it. Although it's considered bad syntax, you can leave out the variable assignment and the function will work the same as a procedure.
When cog reads a verb's parameters, it will start from the right and go to the left. Cog will ignore any extra parameters on the left, and any ones not entered will have a default value of -1. It's not bad syntax to leave out arguments if they should be given the default value.
startup: statement1; { statement2; statement3; } statement4; Return;Statements 1 and 4 are outside of the block, and statements 2 and 3 are inside. Although we haven't gone over any reasons to use code blocks, you will need to understand them before going on to the conditions tutorial. Just remember that code blocks are used to group many statements so they can be treated as a whole.
The example above is properly indented, but this is not a syntax requirement. This last example will look the same as the first to JK:
startup: statement1; {statement2;statement3;} statement4; Return;