X39 – User talk

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Added additional note to nular command to differentiate more precise)
m (Blanking)
Tag: Blanking
 
(55 intermediate revisions by 3 users not shown)
Line 1: Line 1:
__TOC__
<code style="display: inline; margin: 0px; padding: 2px;">Status Quo Function</code> is the successor of <code style="display: inline; margin: 0px; padding: 2px;">[[SQS_syntax|Status Quo Script]]</code> which is deprecated since [[Armed Assault]].
SQF was first introduced in [[Operation_Flashpoint:_Resistance_Introduction|Operation Flashpoint: Resistance]].


An SQF Expression has to be terminated via either <code style="display: inline; margin: 0px; padding: 2px;">;</code> or <code style="display: inline; margin: 0px; padding: 2px;">,</code>.
Example:
_num = 10;
_num = _num + 20; [[systemChat]] _num;
In the above example, there are three expressions.
# <code style="display: inline; margin: 0px; padding: 2px;">_num = 10</code>
# <code style="display: inline; margin: 0px; padding: 2px;">_num = _num + 20</code>
# <code style="display: inline; margin: 0px; padding: 2px;">[[systemChat]] _num</code>
All get separated, not via a new line but the <code style="display: inline; margin: 0px; padding: 2px;">;</code>.
SQF also allows [[Array|arrays]] and [[Block|codeblocks]] to have expressions inside of them.
An [[Array|array]] always is started with <code style="display: inline; margin: 0px; padding: 2px;">[</code> and ends with <code style="display: inline; margin: 0px; padding: 2px;">]</code>. The array may contain another [[Data_Types|value type]] including other arrays.
A [[Block|Codeblocks]] is a separate [[Data_Types|value type]] containing numerous SQF expressions. It will be executed when used with eg. [[call]] and can be assigned to a [[Variables|variable]] just like any other [[Data_Types|value type]]. [[Block|Codeblocks]] start with <code style="display: inline; margin: 0px; padding: 2px;">{</code> and end with <code style="display: inline; margin: 0px; padding: 2px;">}</code>
== Language Structure ==
The SQF Language is fairly simple in how it is built.
In fact: there are barely any actual language structures at all.
The functionality is provided via so called ''operators'' (or more commonly known [[:Category:Scripting_Commands_Arma_3|scripting commands]]).
Those operators are one of the following types: [[#nular|Nular]], [[#unary|Unary]],  or [[#binary|Binary]].
=== Comments ===
A comment is additional text that gets ignored when a script is parsed.
They exists they exist for the to allow you, the coder, to add additional info to your code so that if somebody else (including your future you) is looking into the code can understand what you did there.
In SQF, there are two kind of comments:
{{codecomment|//In-line comment that ends on new line}}
{{codecomment|/* Block Comment that can span above multiple lines and ends on the following character combination: */}}
A comment can occur anywhere but inside a string.
For example, the following would be valid:
1 + {{codecomment|/* Some random coment in an expression. */}} 1
It should be mentioned, that there is a [[comment]] unary operator that should not be used as it will actually be executed (thus taking time to execute) but does nothing besides consuming a string.
There is no benefit in using it and the reason it exists is solely for Backward Compatibility.
Another way to make a ''comment'' that way, is to just place a string: <code style="display: inline; margin: 0px; padding: 2px;">[...]; "i can be considered as a comment but should not be used"; [...]</code>
''Comments are removed during the PreProcessing phase.'' This is important to know as that prevents usage in eg. a string that gets compiled using the [[compile]] unary Operator or when only using [[loadFile]].
=== <span id="nular">Nular Operators</span> ===
A Nular Operator is more or less a computed variable. Each time accessed, it will return the current state of something.
It is tempting to think of a Nular Operator as nothing more but a magic [[Variables|Global Variable]], but it is important to differentiate!
Consider following example in a mission with eg. 5 units:
{{codecomment|//Put the result of [[allUnits]] into a [[Variables|variable]].}}
_unitsArray = [[allUnits]];
{{codecomment|//Display the current array size using [[systemChat]].}}
[[systemChat]] [[str]] [[count]] _unitsArray;
{{codecomment|//Create a new unit in the player group.}}
[[group]] [[player]] [[createUnit]] ["B_RangeMaster_F", [[position]] [[player]], [], 0, "FORM"];
{{codecomment|//Output the array size again}}
[[systemChat]] [[str]] [[count]] _unitsArray;
{{codecomment|//Output the size of [[allUnits]]}}
[[systemChat]] [[str]] [[count]] [[allUnits]];
Now, what would the output of this look like?
System: 5
System: 5
System: 6
As you can see, <code style="display: inline; margin: 0px; padding: 2px;">_unitsArray</code> was not automatically updated as it would have been if it was not generated each time. If [[allUnits]] was just a [[Variables|Global Variable]], our private variable should have had reflected the change as [[Data_Types|value types]] are passed by reference.
The reason for this is because [[allUnits]] and other Nular commands just return the current state of something and do not return a reference to eg. an [[Array]] containing all units.
It is generated each time, which is why some of theese commands are more expensive to run then ''just'' using a variable.
=== <span id="unary">Unary Operators</span> ===
The Unary Operators are operators that expect an argument on their right side (<code style="display: inline; margin: 0px; padding: 2px;">unary &lt;argument&gt;</code>). They always will take the first argument that occurs.
A common mistake would be the following:
{{codecomment|//Create some array containing three arrays.}}
_arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]];
{{codecomment|//Wrongly use the [[select]] command to get the count of the third array.}}
[[count]] _arr [[select]] 2; <span style="color: Red;">//Error</span>
Now, what went wrong?
Let's put some brackets in the right places to make the mistake understandible:
([[count]] _arr) [[select]] 2; <span style="color: Red;">//Error</span>
Due to the nature of Unary operators, count instantly consumes our [[Variables|variable]] ''_arr'' and returns the number ''3''.
The ''3'' then is passed to [[select]] which does not knows what to do with a number as left argument and thus errors out.
To do it correctly, one would have to put the <code style="display: inline; margin: 0px; padding: 2px;">_arr select 2</code> in brackets.
The correct code thus would be:
{{codecomment|//Create some array containing three arrays.}}
_arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]];
{{codecomment|//Use Brackets to correctly get count of the third array.}}
[[count]] (_arr [[select]] 2); {{codecomment|//Good :)}}
=== <span id="binary">Binary Operators</span> ===
Binary Operators expect two arguments (<code style="display: inline; margin: 0px; padding: 2px;">&lt;1st argument&gt; binary &lt;2nd argument&gt;</code>) and are executed according to their [[#precedence|precedence]]. If their [[#precedence|precedence]] is equal, they are executed left to right.
As example, we will look into the following Expression:
{{codecomment|//Create a nested [[Array]] with 5 levels.}}
_arr = [[[[[1]]]]];
{{codecomment|//Receive the nested number with some random math expressions.}}
_arr select 0 select 1 - 1 select 15 / 3 - 5 select 0 select 10 * 10 + 4 * 0 - 100
Now, let us analyze why this is happening for the first few expressions:
# _arr is loaded
# 0 is loaded
# [[select]] is executed with the result of 1. & 2.
# 1 is loaded
# 1 is loaded
# [a_minus_b|-] is executed with the result of 4. & 5.
# [[select]] is executed with the result of 3. & 6.
# ...
If we now would put brackets at the correct spots, the expression will get more clear:
((((_arr select 0) select (1 - 1)) select ((15 / 3) - 5)) select 0) select (((10 * 10) + (4 * 0)) - 100)
As you can see the [[a_*_b|*]] and [[a_/_b|/]] are executed first which matches their [[#precedence|precedence]]. Afterwards, the [[a_plus_b|+]] and [[a_minus_b|-]] operators will get executed followed by our [[select]] commands, which are executed from the left to the right.
== <span id="precedence">Rules Of Precedence</span> ==
{|
|1 '''Lowest Precedence'''
|<code>[[a or b|<nowiki>||</nowiki>]] [[a or b|or]]</code>
|-
|2
|<code>[[and|&&]] [[and]]</code>
|-
|3
|<code>[[==]] [[!=]] [[a_greater_b|&gt;]] [[a_less_b|&lt;]] [[a_less=_b|&gt;=]] [[a_less=_b|&lt;=]] [[config_greater_greater_name|&gt;&gt;]]</code>
|-
|4
|''ALL BINARY OPERATORS''
|-
|5
|<code>[[else]]</code>
|-
|6
|<code>[[a_plus_b|+]] [[a_minus_b|-]] [[max]] [[min]]</code>
|-
|7
|<code>[[a_*_b|*]] [[a_/_b|/]] [[mod|%]] [[mod]] [[atan2]]</code>
|-
|8
|<code>[[a_^_b|^]]</code>
|-
|9
|<code>[[select|#]]</code>
|-
|10
|''ALL UNARY OPERATORS''
|-
|11 '''Highest Precedence'''
|''ALL NULAR OPERATORS, VARIABLES, VALUES OR BRACED EXPRESSIONS''
|}
== See also ==
* [[Control Structures]]
* [[SQS syntax]]
* [[Function]]
* [[Statement]]
* [[Block]]
* [[Missions#Locations_of_Mission_Files|Location of script files]]
* [[SQS to SQF conversion]]
<!-- [[Category: Syntax]] [[Category:Scripting Topics]] -->

Latest revision as of 21:12, 18 November 2019

Retrieved from "https://community.bistudio.com/wiki?title=User_talk:X39&oldid=138731"