Clash macro language description.

Please read it (and criticize it)

Rules:
1. Basic types: Number (no distinction between real and integers)
String
Boolean (true and false)
2. Non case sensitive.
3. Two different kind of code module: Library
Trigger
4. Library: only functions and local variables in functions, but no constants and global variables.
Trigger: functions, variables, constants and the main function which has the same name like the trigger source code and will start when the system call that trigger.
5. Functions can contain variable declaration, but no constant declaration. Those variables are local in the function.
6. Comments with // (double slash).

Syntax:

Library source file:

// here start the library source code
Library;

Number | String | Boolean | Void Function1(Type Name, Type Name, ...) {
Variable
Type Name1 := Value;
Type Name2 := Value;
EndVariable
Statements;
Return;
}

Number | String | Boolean | Void Function2(Type Name, Type Name, ...) {
Variable
Type Name1 := Value;
Type Name2 := Value;
EndVariable
Statements;
Return;
}

// Here is the end of the library source code. The file name must have a .cli extension.

// Here starts the trigger source code.

Trigger;

Library Library1Name;
Library Library2Name;

Constant
Type Name1 := Value;
Type Name2 := Value;
EndConstant

Variable
Type Name1 := Value;
Type Name2 := Value;
Array Type Name1[Index1, Index2, ...];
Array Type Name2[Index1, Index2, ...];
EndVariable;

Number | String | Boolean | Void Function1(Type Name, Type Name, ...) {
Variable
Type Name1 := Value;
Type Name2 := Value;
EndVariable
Statements;
Return;
}

Number | String | Boolean | Void Function2(Type Name, Type Name, ...) {
Variable
Type Name1 := Value;
Type Name2 := Value;
EndVariable
Statements;
Return;
}

Void Trigger(Type Name, Type Name, ... ) {
Variable
Type Name1 := Value;
Type Name2 := Value;
EndVariable
Statements;
Return;
}
// Here is the end of the trigger source code. The file name must have a .ctr extension.

The Trigger function ALWAYS Void. The Trigger Function name the same like the trigger source code name and the same like the built in trigger name:
Let say we have a trigger in the game: EndOfTurn
In this case the trigger source code name is: EndOfTurn.ctr
The trigger main function:
Void EndOfTurn(Turn Number) {
Variable
Type Name1 := Value;
Type Name2 := Value;
Variableend
Statement1;
.
.
.
StatementN;
Return;
}

Instructions:

Statements:

Simple Statements:

Assignment:
variable := expression;
expression: must be type compatible with the variable

Void function calls:
i.e.:
MyFunction(First,Second);

Structured statements:

1. Compound statement:
All the simple statements between the { and } brackets.
i.e.:
{
a := 158;
b := MyFunc(125,25);
}

2. If statement:

If (Boolean expression)
Simple or compound statement1
//optional
else
Simple or compound statement2

If the Boolean expression is true then statement1 is executed, otherwise the statement2 is executed.

3. While statement:

While (Boolean expression)
Simple or compound statement

The while statement executes as long as the Boolean expression returns true.

4. Do While statement:

Do
Simple or compound statement
While (Boolean expression)

The while statement executes as long as the Boolean expression returns true.

5. For statement:

For(Initial value, final value, counter)
Simple or compound statement

The for statement executes as long as the final value is true.

Expression:
The order of the execution can be determined by brackets ( and )
1. Numeric:

Constant (i.e. 16)
Variable (i.e. N)
Function Sum(A, B, C);
Addition + Op1 + Op2 (i.e. 16+12)
Subtraction - Op1 - Op2 (i.e. 16-N)
Multiplication * Op1 * Op2 (i.e. 12*N)
Division / Op1 / Op2 (i.e. 12/2)
Negation - -Op (i.e. -N)
Increment ++ ++Op or Op++ (i.e. ++N) Op must be a number variable!
Decrement -- --Op or Op-- (i.e. N--) Op must be a number variable!

2. String

Constant (i.e. 'AbcD')
Variable (i.e. S)
Function Uppercase('abc');
Concatenation + Op1 + Op2 (i.e. S+'cd')

3. Boolean

Constant (i.e. true)
Variable (i.e. T)
Function Good();
And & Op1 & Op2
Or | Op1 | Op2
Not ! ! Op

Relational operators (Result ALWAYS Boolean)
Numeric: (Op1 and Op2 are numeric expressions)
Equality = Op1 = Op2
Inequality != Op1 != Op2
Less-than < Op1 < Op2
Greater-than > Op1 > Op2
Less-than or equal to <= Op1 <= Op2
Greater-than or equal to >= Op1 >= Op2

String: (Op1 and Op2 are string expressions)
Equality = Op1 = Op2
Inequality <> Op1 <> Op2

Calling Order:
Let say we wold like to play with the "myscenario" scenario. The system first start to load all the triggers and libraries from the default directory After looking for triggers and libraries in the "myscenario" scenario directory:
i.e.:
first ...\default\mod\*.ctr (triggers)
...\default\mod\*.clb (libraries)
after
...\myscenario\mod\*.ctr (triggers)
...\myscenario\mod\*.clb (libraries)
If the system find triggers in the "myscenario" library with the same names like the defaults, then the system will use those "myscenario" triggers to control the game.

It looks like a good start to me. I'm having trouble seeing a rational way for the person using the macro language to get their hands on runtime-generated handles. I assume you have something in mind, but its not clear to me from the writeup. FE there will be no variable named RomansCultureHistoricalPowerOfAristocracy. In the code it will be something like getCiv("Romans").getCulture().getHistoricalPowerOfAristocracy()... But I can't use your Functions to break this down because they don't return objects, just numbers, strings & such. Am I missing something?

And then the next issue is another level beyond the above. FE the BigBad empire may split through a revolt, During the game, into the states Big and Bad. But it may not... This is not explicitly planned in the scenario, it may just happen due to the game dynamics of the situation. If it splits I may want the macro to do something to one of the successor states After the split. How do I get info on Big and Bad which don't even exist before runtime? Perhaps we can put in an 'Inheritance' tree of civs that evolve out of progenitor civs or something...

Perhaps this is too picky, but we need to talk this stuff out

What I sent already that is only the syntax of the Clash language. I tried to build an easy to understand but flexible macro language. My later task is to produce the interface between the Clash system and the macro interpreter.

Let say we have system variables and arrays in the macro language. First the programmer needs to send the value of the variable to a special interface class. The macro language interpreter can read the value from there.

When something happen in the Clash game (end of turn, civilization split, war start, war end, etc) the programmer call a pseudo method from this special interface class. The interface class code start the macrocode (if exist) or do nothing (if don't exist).

I understand your problem with the macro system. IMO we have two possibilities to produce a working system.

1. I start to code the macro interpreter. We can use my syntax, or anything, which get the majority support from the team. When the macro system ready, than we can start to collect ALL the useful variables and events to connect to the macro system.

2. We (the programmer team) start to check the system description to build up the best combination of the useful variables and events for the macro language. The programmers must produce the interface part, when they produce the program code. I write the macro language interpreter.

The macro writers can use only that system variables and events what we provide to them. The rest will be completely hidden. With your example: If we realy wants to provide this information to the users we can produce a 3 dimensional system array:
FE: Civvalues[civs,area,subarea]
Civvalues[Romans,Culture,HistoricalPowerOfAristocracy] := 0.25;
Of course ALL the macro system variables MUST be exist always, so they cannot be runtime generated. I cannot see any other possibility, but maybe the others.

Most scripting languages I know of don't require variable declarations, and variables are typically typeless (whether operands are valid is determined at runtime). So if you need a variable, you just assign it a value, and it will exist.

Likewise, functions typically don't have return types, and neither do the function parameters. Thus, a function definition might look like:
myFunction(x, y, name)
{
// function body
return someValue
}

This typically makes scripting languages more easy to use.

It is depend how many macro language code we want to include in the game. For short rutins your idea is better. (easier to understand, shorter code, etc.) For longer rutins the system can debug automatically a lot of common problems. (think about the BASIC language)

//I.E. one of the most common problem, mistyping:
aut = 15;
bet = uat;
//

The user(s) can spend a lot of time to find out why the bet variable different than the aut variable.

The strict rules are more difficult to implement to a macro language, but later easier to write good programs without (or almost without) bugs.

BTW there is only three types: Number, String and Boolean. I think that makes sense to define the variable, because the interpreter can automaticaly find out the variable and procedure names mistyping.
I agree to rid off the function return type.