Class Soup

From TrainzOnline
Jump to: navigation, search


A Soup object is the script interface to data stored in the ACS Text Format, such as config.txt files. Soups are used in various places within Trainz as a way to load and save data, such as property settings.

  • Soups can save items which can be represented as boolean values, floating point numbers, integers, strings, KUID references or nested SubSoups.
  • All data items are saved in key-value pairs and saved information can be stored or retrieved by referring to the name (unique key) of the data item.
  • Soups are used by calls to GetProperties() and SetProperties() as a mechanism for saving object data to the session and retrieving it on a subsequent load.
  • It is possible in some cases to save data as one data type and retrieve it as another.
  • Soups descend directly from GSObject enabling them to be passed as parameters to script libraries.
  • A Soup object, with four simple tags and a nested SubSoup might be represented thus: 
forename   "Gordon"
surname    "Bennett"
married    0
height     1.65 
address {
   0       "1 High Street"
   1       "Southend"
   2       "Essex"
}
  • A new Soup can be created using Constructors.NewSoup() or as a result of method calls: 
Soup soup = Constructors.NewSoup();       // this soup will be empty
Soup soup = GetAsset().GetConfigSoup();   // this will contain the contents of config.txt in Soup format.


Contents

Clear

public native void Clear(void)
Parameters
  • None
Returned Value
  • None
Syntax 
soup.Clear();
Notes
  • Deletes all tags and values leaving an empty Soup.


Copy

public native void Copy(Soup value)
Parameters
  • value = Soup to copy from.
Returned Value
  • None
Syntax 
Soup source;
Soup destination;
destination.Copy(source);
Notes
  • Clears destination and copies all tags from source creating a duplicate of the original Soup.


CountTags

public native int CountTags(void)
Parameters
  • None
Returned Value
  • The total number of tags found at the highest level of the Soup being queried. Nested SubSoups are counted as one tag.
Syntax 
int items = soup.CountTags();
Notes
  • Note that since a call to GetNamedSoup() will always return a valid Soup object, the use of CountTags() is in some circumstances, necessary to establish whether or not a Soup object actually contains data. 
GetAsset().GetConfigSoup().GetNamedSoup("extensions")                   // always returns true
GetAsset().GetConfigSoup().GetNamedSoup("extensions").CountTags()       // returns true only if there is data present


GetIndexedTagName

public native string GetIndexedTagName(int index)
Parameters
  • index = Integer denoting the tag to search for.
Returned Value
  • The tag name of the indexth tag in the database.
  • Index must be in the range 0 .. soup.CountTags() - 1
Syntax 
string tagname = soup.GetIndexedTagName(1);
Notes
  • Tag ordering is arbitrary; the Soup is neither guaranteed to be order-preserving nor sorted.
  • Remember that the value returned may be a SubSoup. 
soup1: zero    "1 High Street"
       one     "Southend"
       two     "Essex"

string result = soup1.GetNamedTag(soup1.GetIndexedTagName(1));   // returns "Southend"
 
soup1.GetIndexedTagName(1) would return "one"

GetIndexForNamedTag

public native int GetIndexForNamedTag(string name)
Parameters
  • name = Tag name to search for.
Returned Value
  • The zero based index of the position of the tag name at the highest level of the database.
  • If the named tag is not present the method returns -1.
Syntax 
int index = soup.GetIndexForNamedTag("one");
Notes 
soup1:  zero    "1 High Street"
        one     "Southend"
        two     "Essex"

string result = soup1.GetIndexForNamedTag("one");   // returns 1


GetNamedSoup

public native Soup GetNamedSoup(string name)
Parameters
  • name = name of SubSoup to retrieve
Returned Value
  • The named SubSoup, which will be created if it does not exist
  • This method always returns a Soup object
Syntax 
Soup table = soup.GetNamedSoup("table");
Notes
  • CountTags() can be used to establish whether or not the returned Soup has any data. 
Soup soup = GetAsset().GetConfigSoup().GetNamedSoup("Not Present");  // always returns true
if (soup and soup.CountTags() > 0)                                   // returns false if soup is empty

soup1:  forename   "Gordon"
        surname    "Bennett"
        married    0
        height     1.65 
        address {
           0       "1 High Street"
           1       "Southend"
           2       "Essex"
        }

Soup address = soup.GetNamedSoup("address"); 

returns 0       "1 High Street"
        1       "Southend"
        2       "Essex"


GetNamedTag

public native string GetNamedTag(string name)
Parameters
  • name = name of tag from which data is required.
Returned Value
  • String value associated with the name parameter.
  • If the tag does not exist an empty string is returned.
Syntax 
string value = soup.GetNamedTag("tagName");
Notes 
soup1:  forename   "Gordon"
        surname    "Bennett"

string data = soup1.GetNamedTag("surname");   // returns "Bennett"


GetNamedTagAsBool

public native bool GetNamedTagAsBool(string name)
public native bool GetNamedTagAsBool(string name, bool default)
Parameters
  • name = name of tag from which data is required.
Returned Value
  • Boolean value associated with the name parameter.
Syntax 
bool found = soup.GetNamedTagAsBool("tagName");
bool found = soup.GetNamedTagAsBool("tagName", true);
Notes
  • For the first variant if the tag does not exist false is returned.
  • For the second variant if the tag does not exist it will be created and assigned the value of default.
  • In this case default will be returned by the method.


GetNamedTagAsFloat

public native float GetNamedTagAsFloat(string name)
public native float GetNamedTagAsFloat(string name, float defaultValue)
Parameters
  • name = name of tag from which data is required.
  • defaultValue = value to return if the tag is undefined.
Returned Value
  • Float value associated with the name parameter
  • If the tag does not exist defaultValue will be returned, or 0.00 for the first variant.
Syntax 
float speed = soup.GetNamedTagAsFloat("speed")
Notes


GetNamedTagAsInt

public native int GetNamedTagAsInt(string name)
public native int GetNamedTagAsInt(string name, int default)
Parameters
  • name = name of tag from which data is required.
Returned Value
  • Integer value associated with the name parameter.
Syntax 
int count = soup.GetNamedTagAsInt("count");
int count = soup.GetNamedTagAsInt("count", 25);
Notes
  • For the first variant if the tag does not exist 0 is returned.
  • For the second variant if the tag does not exist it will be created and assigned the value of default.
  • In this case default will be returned by the method.


GetNamedTagAsKUID

public native KUID GetNamedTagAsKUID(string name)
Parameters
  • name = name of tag from which data is required.
Returned Value
  • KUID reference associated with the name parameter.
  • if the tag does not exist null is returned.
Syntax 
KUID kuid = soup.GetNamedTagAsKUID("kuidValue");
Notes
  • SetNamedTag() can write a KUID in string format for retrieval by this method.


IsLocked

public native bool IsLocked(void)
Parameters
  • None
Returned Value
  • Boolean value indicating whether data can be written to the Soup.
Syntax 
bool canWriteData = !soup.IsLocked();
Notes
  • Config.txt data returned by GetConfigSoup() is always read-only
  • Attempting to write data to a locked soup will cause an exception with the message "parent soup is locked"
  • It is not possible to write directly to a nested soup. 
To update a sub soup:

soup1:   forename   "Gordon"
         surname    "Bennett"
         married    0
         height     1.65 
         address {
            0       "1 High Street"
            1       "Southend"
            2       "Essex"
         }

Soup subSoup = soup.GetNamedSoup("address");     // copy the sub soup data to a temporary soup
subSoup.SetNamedTag(3,"SS2 3PX");                // add a new tag
soup.SetNamedSoup("address",subSoup);            // write the amended sub soup back to its parent

result:  data:  forename   "Gordon"
         surname    "Bennett"
         married    0
         height     1.65 
         address {
            0       "1 High Street"
            1       "Southend"
            2       "Essex"
            3       "SS2 3PX"
         }


RemoveNamedTag

public native void RemoveNamedTag(string name)
Parameters
  • name = name of tag to delete.
Returned Value
  • None
Syntax 
soup.RemoveNamedTag("address");
Notes
  • Deletes the named tag and its associated value.
  • If the tag references a sub soup the entire soup will be removed.


SetNamedSoup

public native void SetNamedSoup(string name, Soup value)
Parameters
  • name = name of subsoup tag to assign.
  • value = Soup data to write to this tag
Returned Value
  • None
Syntax 
soup1.SetNamedSoup("address",soup2);
Notes
  • Creates a new database tag and writes value to it as a new sub soup.
  • If the tag already exists it will be updated. 
soup1:   forename   "Gordon"
         surname    "Bennett"
         married    0
         height     1.65 

soup2:   address {
            0       "1 High Street"
            1       "Southend"
            2       "Essex"
         }

soup1.SetNamedSoup("address",soup2);            // write the sub soup data to the address tag

result:  forename   "Gordon"
         surname    "Bennett"
         married    0
         height     1.65 
         address {
            0       "1 High Street"
            1       "Southend"
            2       "Essex"
         }


SetNamedTag

public void SetNamedTag(string name, bool value)
public void SetNamedTag(string name, float value)
public void SetNamedTag(string name, int value)
public void SetNamedTag(string name, KUID value)
public void SetNamedTag(string name, string value)
Parameters
  • name = tag name to assign a value to.
  • value = data to assign to tag, this can be of type bool, float, int KUID or string.
Returned Value
  • None
Syntax 
soup.SetNamedTag("index",1);
soup.SetNamedTag("open",true);
soup.SetNamedTag("myKUID","<KUID:1234:5678>");
Notes
  • The tag value is created if it does not already exist and overwritten otherwise
  • KUIDs may be entered as strings or as KUID references.


Code Examples

Soup to Array Conversion
  • Soups cannot directly store Array types but conversion between Arrays and Soups is fairly straightforward.
  • Similar code can be used for other array types as long as the Soup class supports the base type of the array.
  • Lists of GameObjects can be saved by reference to their session name, using GameObject.GetName(), or if the list is needed during the current session only, by referencing their ID using GameObject.GetId(). 
Soup IntArrayToSoup(int[] numbers) {
   int i;
   Soup soup = Constructors.NewSoup();
   for (i = 0; i < numbers.size(); i++) {
      soup.SetNamedTag(i,numbers[i]);
   }
   return soup;
}

int[] SoupToIntArray(Soup soup) {  // any non integer values will be saved as zero
   int i;
   int[] numbers = new int[0];
   for (i = 0; i < soup.CountTags(); i++) {
      string tag = soup.GetIndexedTagName(i);
      numbers[numbers.size()] = soup.GetNamedTagAsInt(tag);
   }
   return numbers;
}


Related Methods

Asset.GetConfigSoup()
Constructors.NewSoup()
PropertyObject.GetProperties()
PropertyObject.SetProperties()

Categories

Retrieved from "https://game.ts2009.com/mediaWiki/index.php?title=Class_Soup&oldid=1850"
Personal tools