function list

[Apemant]

Name:
switch

Syntax:
(switch condition function^2 [function])

Argument List:
condition: a condition which must be fulfilled in order to execute a subsequent function
function: a function that gets invoked if the previous condition is met (i.e. evaluating to non-Nil)
optional function: a function which will be executed if all conditions evaluate to Nil, i.e. if all of them are 'false'.

Returns:
Whatever the function that eventually gets invoked, returns.

Category:
Control Structure

Description:
Allows branching of the code by more than 1 condition. For just 1 condition, 'if' is good enough. It just evaluates all the conditions (every even argument; odd arguments are corresponding functions) in left to right order, until the first one that evaluates to non-Nil. It then invokes the corresponding function, which is the argument that directly follows that condition. If all the conditions evaluate as Nil, then the last, optional function is invoked.


Example:

Code: Select all

(setq num 3)
(switch
    (eq num 1)
        (objSendMessage gPlayerShip Nil "num = 1")
    (eq num 2)
        (objSendMessage gPlayerShip Nil "num = 2")
    (eq num 3)
        (objSendMessage gPlayerShip Nil "num = 3")
    (eq num 4)
        (objSendMessage gPlayerShip Nil "num = 4")
    (objSendMessage gPlayerShip Nil "num not in (1,2,3,4)")
)

Comment:
Useful for various multiple choices in the code. In could be replaced by series of 'if's but then there would be even more parentheses than now. Also, it's interesting to notice that there probably isn't any real difference between 'conditions', 'functions' and 'optional function': these are legal switch function examples:

(switch 1 11 2 12 3 13 4 14 5 15) -> evaluates as 11
(switch Nil 11 Nil 12 3 13 4 14 5) -> evaluates as 13
(switch Nil 11 Nil 12 Nil 13 Nil 14 5) -> evaluates as 5

So it just takes a list of arguments, evaluates the first one, if it's non-Nil, evaluates the second and retuns whatever it is. If the first argument is Nil, skips the second and evaluates the third; if that one is non-Nil, evaluates the fourth and returns, etc. The 'optional function' might also be considered just another condition, which doesn't have a following argument, thus (switch Nil 11 Nil 12 3) evaluates as 3. It really is simple when you look at it this way.

[Betelgeuse]

we really need to agree on what the arguments should be called first documentation is useless if it isn't consistent.
and don't forget it would be clearer if you put the syntax like this

Syntax:
(switch condition command^2 defCommand)

I don't like naming them in the syntax descriptions are the job of the argument list

[Apemant]

we really need to agree on what the arguments should be called first documentation is useless if it isn't consistent.
and don't forget it would be clearer if you put the syntax like this

Syntax:
(switch condition command^2 defCommand)

Agreed.

So how do we call arguments consistently?

Variable arguments and optional arguments are obviously a problem. Ok, this ^2 thing sounds acceptable; what about optionals? Put them into square brackets?

[Betelgeuse]

Square brackets sounds fine. if and switch are the only two functions that I can think of with that so that is fine.

We want to be as simple and as clear as possible whenever naming arguments. If any two arguments even from different functions are the same type they need to have the same name. What they are used for in the function will be defined in the argument list.

ok how about a list of arguments

number (I don't want to call it an int everyone knows what a number is)
String (I can't think of anything that would work better that wouldn't be misleading)
List (a list is a list its hard to describe in non programming terms)
UNID (can be a number or if in the xml one of those constants)
Function (I really don't like the term command, why have them learn something new when they don't have too)
condition/Boolean (to tell the truth both have problems, condition implies logical function and that isn't the case alot of the time. Boolean is a technical term so I don't know what would be a good term for this any ideas?
itemStruct (I don't know we can't use item because it is a function any ideas?)
criteria (I know this is just a string but it must be in a certain format and it is common enough to be given special treatment.)
armorType (evil evil thing, my guess it is from the old code and never got changed)
itemListCursor (basicly a pointer to where you are in the enum for the items of a space obj)
ship
spaceObject
FlagCode (just a number representing many flags not in love with the name)
table
station
vector
screen
pane
player (only gplayer to my knowledge)
armorSegment (a number that depends on how many armors a thing has for what part it covers)
damageType

there is most likely others. So any opinions? I am more than happy with discussing better argument names.

[Apemant]

there is most likely others. So any opinions? I am more than happy with discussing better argument names.

No objections right now, sounds about fine. Condition, actually, is never really a condition, strictly speaking; it's just about anything. Nil is the only 'false' thing, and everything else is 'true'; even 0 or "" are true. So perhaps 'condition' is misleading, but Boolean is even more so, and technical on top of it.

If any new issue appears we can discuss it later.

[Betelgeuse]

hmm hopefully you are not editing it now
What is a defFunction? (yes I know what you mean but that is what I mean by consistent)

ps: don't forget to edit the if function

[Apemant]

hmm hopefully you are not editing it now
What is a defFunction? (yes I know what you mean but that is what I mean by consistent)

ps: don't forget to edit the if function

hmm should I just use 'function' again? Let's try..


Eh, I'm not satisfied... basically because those 'functions' don't need to actually be functions. They can just as well be numbers or strings, there are even couple of examples in .xml files where it is the case, esp. in lambda functions which return different things based on certain conditions.

In essence it it just
(if argument argument [argument])
and
(switch argument^1)


(switch 1) is perfectly legal, it returns 1 (just tried ), and also switch with any number of arguments, even or odd. It just treats every other argument differently, but calling them 'conditions' and 'functions' ... not sure it's warranted.

[george moromisato]

Not sure if this helps, but inside the code I call those things "expressions".

Everything in Lisp is an expression. Some expressions are "literals" (like the number 7 and the string "hello"). Some expressions are "variables" (like gPlayerShip). Some expressions are "function invocations" (e.g., (add 3 4))

[Betelgeuse]

hmm hopefully you are not editing it now
What is a defFunction? (yes I know what you mean but that is what I mean by consistent)

ps: don't forget to edit the if function

hmm should I just use 'function' again? Let's try..


Eh, I'm not satisfied... basically because those 'functions' don't need to actually be functions. They can just as well be numbers or strings, there are even couple of examples in .xml files where it is the case, esp. in lambda functions which return different things based on certain conditions.

In essence it it just
(if argument argument [argument])
and
(switch argument^1)


(switch 1) is perfectly legal, it returns 1 (just tried ), and also switch with any number of arguments, even or odd. It just treats every other argument differently, but calling them 'conditions' and 'functions' ... not sure it's warranted.

My argument is that if they see a certain type of argument they should know what goes in there. If I didn't know what you meant by defFunction I might try a string or anything. (yes I know a number would work but lets not confuse people)

I would be happy with this.
Syntax:
(switch [condition function]^2 [function])

That is saying switch wants a optional series of conditions and functions (you can not have a condition without a function or it would break the syntax, or do you have an example of that?)
with a optional function at the end.

The important thing is both the functions have to have the same name because they are the same type of arguments (anything you can put in one function is just as valid as the other function, this is not the case for condition). (I don't care if we call it something different, if you have a good name please tell me)

ps: expression would not help because we want to give some hint on what the function expects.

pps: I am putting * by the ones we have done in the first post.

[Betelgeuse]

Name:
dbgOutput

Syntax:
(dbgOutput String)

Argument List:
String: The stuff you want outputted to the debug console. If the argument is not a string it will be converted into a string.

Returns:
True if it successfully outputted the string

Category:
debug

Description:
Outputs the string onto the debug console.

Example:

Code: Select all

(dbgOutput "if you can see this you have the debug console open")

Outputs to the debug console
if you can see this you have the debug console open
True

Comment:
Very useful in testing scripts and seeing where things go wrong.
Does not handle \n but does handle \".

[Betelgeuse]

Name:
divide

Syntax:
(divide number number)

Argument List:
number: The dividend of the two numbers.
number: The divisor of the two numbers.

Returns:
The result of the two numbers divided with everything after the decimal point dropped.

Category:
math

Description:
Returns the result of the two numbers divided and dropping everything after the decimal point.

Example:

Code: Select all

(divide 5 3)

This will return a 1.

Code: Select all

(divide 5 2)

This will return a 2.

Code: Select all

(divide 5 (add 1 1))

This will also return a 2.

Comment:
Basic math function. If you hear the term integer division this is what that is referring too.

[Betelgeuse]

Name:
enum

Syntax:
(enum list variable function)

Argument List:
list: A list of elements you want to walk through.
variable: A temporary variable used to hold the current element that you are at in the enum. Does not need to be defined beforehand.
function: The function you want to run for each element using the variable as that element.

Returns:
Whatever the last function run in this returns.

Category:
Iteration, List

Description:
A function allowing you to run a function using the variable to store the element you are at for every element in a list.

Example:

Code: Select all

(enum '(a b c d) theElement
	(dbgOutput theElement)
	)

Will display on the debug console.
a
b
c
d
True

Comment:
Very useful function because you often want to do the same thing to everything in a list.

[Betelgeuse]

Name:
enumwhile

Syntax:
(enumwhile list condition variable function)

Argument List:
list: A list of elements you want to walk through.
condition: Stops enum if condition is Nil.
variable: A temporary variable used to hold the current element that you are at in the enum. Does not need to be defined beforehand.
function: The function you want to run for each element using the variable as that element.

Returns:
Whatever the last function run in this returns.

Category:
Iteration, List

Description:
A function allowing you to run a function using the variable to store the element you are at for every element in a list unless condition is Nil.

Example:

Code: Select all

(block (condition)
	(setq condition True)
	(enumwhile '(a b c d) condition theElement
		(block Nil
			(if (eq theElement 'b) (setq condition Nil))
			(dbgOutput theElement)
			)
		)
	)

This will display on the debug console.
a
b
True

Comment:
Basicly a enum with a if inside of it.

[Betelgeuse]

Name:
eq

Syntax:
(eq expression expression)

Argument List:
expression: One of the two expressions you want to compare. They can be anything.
expression: One of the two expressions you want to compare. They can be anything.

Returns:
True if they are equal. Nil otherwise.

Category:
Logical operators

Description:
Compares two expressions and returns if they are equal are not.

Example:

Code: Select all

(eq '(a b) '(a b))

This will return True.

Code: Select all

(eq 2 (add 1 1))

This will return True.

Comment:
Not as useful as first appears. If you want to compare two objects by just certain properties you need to create a custom function.

[Betelgeuse]

Name:
eval

Syntax:
(eval expression)

Argument List:
expression: The thing you want to evaluate. It can handle numbers, function, strings, and lists. What it does depends on what it gets.

Returns:
If it is passed a number or lamdba function it just returns that otherwise tries to run the list as a function and returns what that function returns, or if it is a string it returns the value of the variable with that name.

Category:
function, variable, string

Description:
Returns the evaluated expression. If it is passed a number or function it just returns that if it is a list tries to run the list as a function and return what it returns, or if it is a string it returns the value of the variable with that name.

Example:

Code: Select all

(eval '(add 1 1))

This is a list case. This will return the number 2.

Code: Select all

(block (varies)
	(setq varies "I am a variable")
	(eval "varies")
	)

This is a string case. This will return the string "I am a variable".

Code: Select all

(eval (add 1 1))

Even though it is similar to the list case this is a number case (the (add 1 1) is run first). This will return the number 2.

Code: Select all

(eval add)

This is the function case. This will return the function add.

Comment:
Some very interesting things can be done with this. The string case is the most interesting due to the list case can be emulated with apply and the other two cases being trivial.