String expansion - Revision history

Cholmondely: Added link to list of expansions in Missiontext.plist

2025-03-31T09:41:33Z

Added link to list of expansions in Missiontext.plist

Massively Locked: cleared up wording

2022-09-19T20:53:00Z

cleared up wording

Milo: corrected operator examples

2020-06-24T16:17:10Z

corrected operator examples

Milo: more detailed explanation of string expansion

2020-06-20T21:00:42Z

more detailed explanation of string expansion

Cim: /* When are things switched */ Note correlation issues

2013-11-30T16:50:50Z

‎When are things switched: Note correlation issues

Svengali: changed links from Misc_plists to their redirects

2013-01-12T14:11:54Z

changed links from Misc_plists to their redirects

Ahruman: Language cleanup, uniqueness constraint note.

2007-10-23T07:02:48Z

Language cleanup, uniqueness constraint note.

Eric Walch: /* What is switched */

2007-10-04T12:20:54Z

‎What is switched

Eric Walch: /* When are things switched */

2007-09-27T21:38:38Z

‎When are things switched

Eric Walch: /* When are things switched */

2007-09-27T21:36:21Z

‎When are things switched

@@ Line 42: / Line 42: @@
 *#* As a last resort, Oolite attempts to expand a key by treating it as a legacy script query method and invoking it. Only [[whitelist.plist|whitelisted]] query_methods and query_method_aliases are permitted. Examples:  [systemGovernment_string] (a whitelisted query method), [fuelLevel_number] (a whitelisted query method) or [fuel_level_number] (a whitelisted alias for [fuelLevel_number])
 * If no suitable replacement is found, the text will be displayed unchanged and a warning will be logged.
 '''Operators:'''

@@ Line 64: / Line 64: @@
 *In [[Oolite_JavaScript_Reference:_Global#expandDescription|expandDescription]] and [[Oolite_JavaScript_Reference:_Global#expandMissionText|expandMissionText]].
-The way things work means that you can create complicated structures. You can use for example:
   addSystemShips: my_ship 1 0.[d100_number]
-This line will then be executed and the ship is placed at the calculated random position. You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ship roles. When you then use:
+You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ship roles.  When you use:
   addSystemShips: [my_random_ship] 1 0.[d100_number]
-the system will randomly pick a ship from the list and replace the d100_number with a value and return the expanded string. This will than be executed.
+the system will randomly pick a ship from the list, replace [d100_number] with a value and return the expanded string.  This will then be executed.
 [[Category:Oolite scripting]]

@@ Line 46: / Line 46: @@
 If a vertical bar ('|') is found between square brackets, Oolite will interpret whatever is on the left side of the bar as the ''key'' and whatever is on the right side of the bar as an ''operator''. An ''operator'' tells Oolite to apply a change after the key has been expanded. Some operators also require an input value, a colon (':'). The available ''operators'' are:
-* dcr       - displays the text as a credit value, interpreting the value as floating point deci-credits (e.g., if the value is 100.7, display 10.7 credits)
+* cr        - displays the text as a credit value, interpreting the value as floating point credits (e.g., if the value is 1007.7, display 1007.7 ₢)
-* cr        - displays the text as a credit value, interpreting the value as floating point credits (e.g., if the value is 100.7, display 100.7 credits)
+* dcr       - displays the text as a credit value, interpreting the value as floating point deci-credits (e.g., if the value is 1007.7, display 100.7 ₢)
-* icr       - displays the text as a credit value, interpreting the value as integer credits (e.g., if the value is 100.7, display 100.0 credits)
+* icr       - displays the text as a credit value, interpreting the value as integer credits (e.g., if the value is 1007.7, display 1007 ₢)
-* idcr      - displays the text as a credit value, interpreting the value as integer deci-credits, rounded (e.g., if the value is 100.7, display 10.0 credits)
+* idcr      - displays the text as a credit value, interpreting the value as integer deci-credits, rounded (e.g., if the value is 1007.7, display 101 ₢)
 * precision - displays the text as a floating point value with an integer-specified number of decimal places, must be specified as ''precision'':number (e.g., [distance|precision:2])
 * multiply  - displays the text as a floating point value multiplied with another floating point value, which must be provided as ''multiply'':othervalue (e.g., [fuelLevel_number|multiply:0.5])

@@ Line 1: / Line 1: @@
 == Format ==
-Oolite has a mechanism to replace text in strings by other text. At some places during script evaluation oolite searches for text between the square brackets []. If it finds this, it treats the text between the brackets as a kind of variable and tries to switch it, including the brackets fore the new text.
+Oolite has a mechanism to replace text in strings with other text. At certain times before displaying text (details below), Oolite searches for % symbols and square brackets [ ]. If it finds them, it checks if what immediately follows the % symbols, or what is between the square brackets, has a recognized special meaning, and if so, substitutes replacement text.  Oolite also recognizes vertical bars ('|') and colons (':') inside square brackets as special characters. When you do not want Oolite to replace text, use a double % ('%%') to display a single %, and put a backslash ('\') before each square bracket to display the brackets and text inside them without substitution ('\[example\]' will be displayed as '[example]').  Additionally, the special value '\n' will be replaced by a new line, which can be prevented by preceding it with an extra slash ('\\n' will display '\n').
 == What is switched ==
-If the text is a [mission_variable], a [local_variable] or a system variable like [shipsFound_number], the content is replaced by the content of that variable. If not it looks at the key's in the [[descriptions.plist]]. If it finds a match it uses one of the strings belonging to that key for switching. (Note that OXP-specific entries in descriptions.plist and missiontext.plist should have an OXP or creator-specific prefix to ensure uniqueness.)
+'''Recognized % codes:'''
-If you use [0] till [32] the number is replaced by strings from the "System Descriptions" key of the descriptions.plist inside Oolite itself. [0] is the first set of 5 arrays, [1] the second and so on. This was not meant for OXP use but a few numbers are still suitable.
+* %H       - Current System name, e.g., Lave
 == When are things switched ==
-Oolite calls only at certain places the switching routine.
+Oolite calls the switching routine only at certain places ('''this is not a complete list'''):
-*The most often used place is in [[missiontext.plist]]. In every text line the text between brackets is replaced by a variable or a [[descriptions.plist]] entry.
+*The most often used place is in [[missiontext.plist]]. Every text line is evaluated for string replacement. Most commonly this is used to replace text in brackets with the content of a variable or a [[descriptions.plist]] entry.
-*Inside a [[descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the description.plist inside Oolite were it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.). Because of the random number generator used for expansion the use of deep recursion may cause correlations which are not random - consider for example that "mud" is always followed by "tennis" or "hockey" in planetary descriptions, never anything else. In Oolite 1.79 certain ways of expanding descriptions from Javascript will use a higher quality random number generator which does not have correlation problems.
+*Inside a [[descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the descriptions.plist in Oolite's Resources\Config folder where it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.). Because of the random number generator used for expansion, the use of deep recursion may cause correlations which are not random - consider for example that "mud" is always followed by "tennis" or "hockey" in planetary descriptions, never anything else. In Oolite 1.79, certain ways of expanding descriptions from JavaScript will use a higher quality random number generator, which does not have correlation problems.
-*During evaluation of a AI.plist it only uses the switching on the content of a "commsMessage".
+*During evaluation of a [[OXP howto AI|plist-based AI]], it only uses switching on the content of a "commsMessage".
-*During evaluation of a [[script.plist]] all the lines in the DO or ELSE part of a condition statement are switched. For some reason nothing is switched in the  CONDITIONS part of a command so you can not use anything in brackets there.
+*During evaluation of a [[script.plist]] all the lines in the DO or ELSE part of a condition statement are switched. Nothing is switched in the CONDITIONS part of a command so you cannot use anything in brackets there.
-The way thing work means that you can create complicated structures. You can use for example:
+The way things work means that you can create complicated structures. You can use for example:
   addSystemShips: my_ship 1 0.[d100_number]
-Oolite first offers above line to the replacement routine. That one replaces [d100_number] by a random number. e.g. 46. Than the routine returns:
+Oolite first offers the above line to the replacement routine. That replaces [d100_number] by a random number. e.g. 46. Than the routine returns:
   addSystemShips: my_ship 1 0.46
-This line will then be executed and the ship is placed at the calculated random position. You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ships roles. When you then use:
+This line will then be executed and the ship is placed at the calculated random position. You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ship roles. When you then use:
   addSystemShips: [my_random_ship] 1 0.[d100_number]
-the system will randomly pick a ship from the list and replace the d100_number for a value and returns the expanded string. This will than be excecuted.
+the system will randomly pick a ship from the list and replace the d100_number with a value and return the expanded string. This will than be executed.
 [[Category:Oolite scripting]]

@@ Line 10: / Line 10: @@
 Oolite calls only at certain places the switching routine.
 *The most often used place is in [[missiontext.plist]]. In every text line the text between brackets is replaced by a variable or a [[descriptions.plist]] entry.
-*Inside a [[descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the description.plist inside Oolite were it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.)
+*Inside a [[descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the description.plist inside Oolite were it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.). Because of the random number generator used for expansion the use of deep recursion may cause correlations which are not random - consider for example that "mud" is always followed by "tennis" or "hockey" in planetary descriptions, never anything else. In Oolite 1.79 certain ways of expanding descriptions from Javascript will use a higher quality random number generator which does not have correlation problems.
 *During evaluation of a AI.plist it only uses the switching on the content of a "commsMessage".
 *During evaluation of a [[script.plist]] all the lines in the DO or ELSE part of a condition statement are switched. For some reason nothing is switched in the  CONDITIONS part of a command so you can not use anything in brackets there.

@@ Line 3: / Line 3: @@
 == What is switched ==
-If the text is a [mission_variable], a [local_variable] or a system variable like [shipsFound_number], the content is replaced by the content of that variable. If not it looks at the key's in the [[misc plists|descriptions.plist]]. If it finds a match it uses one of the strings belonging to that key for switching.
+If the text is a [mission_variable], a [local_variable] or a system variable like [shipsFound_number], the content is replaced by the content of that variable. If not it looks at the key's in the [[misc plists|descriptions.plist]]. If it finds a match it uses one of the strings belonging to that key for switching. (Note that OXP-specific entries in descriptions.plist and missiontext.plist should have an OXP or creator-specific prefix to ensure uniqueness.)
-If you use [0] till [32] the number is replaced by strings from the "System Descriptions" key of the descriptions.plist inside Oolite itself. [0] is the first set of 5 arrays, [1] the second and so on. This was not mend for OXP use but a few numbers are still suitable.
+If you use [0] till [32] the number is replaced by strings from the "System Descriptions" key of the descriptions.plist inside Oolite itself. [0] is the first set of 5 arrays, [1] the second and so on. This was not meant for OXP use but a few numbers are still suitable.
 == When are things switched ==
 Oolite calls only at certain places the switching routine.
 *The most often used place is in [[missiontext.plist]]. In every text line the text between brackets is replaced by a variable or a [[misc plists|descriptions.plist]] entry.
-*Inside a [[misc plists|descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the description.plist inside Oolite were it generates random names in a recursive way. (recursion is maximized to about 32 times to prevent infinite looping)
+*Inside a [[misc plists|descriptions.plist]] entry you can also use brackets. This way you can get a recursive process. Look for example in the description.plist inside Oolite were it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.)
 *During evaluation of a AI.plist it only uses the switching on the content of a "commsMessage".
 *During evaluation of a [[script.plist]] all the lines in the DO or ELSE part of a condition statement are switched. For some reason nothing is switched in the  CONDITIONS part of a command so you can not use anything in brackets there.