View source for SEXP Container

''This page is about the FRED feature. For cargo containers, see [[Containers]].''

[[File:Containers_sample.png|200px|thumb|right|FRED's Events Editor with many different examples of how SEXP containers can be used.]]

'''SEXP containers''' allow FREDders to store groups of pieces of information for later use.

As opposed to a [[Variable|SEXP variable]], which stores only one value, a SEXP container stores a collection of values.

Since containers allow for handling data in much more sophisticated ways than variables, it's recommended that FREDders become comfortable with using variables before trying to use containers.

Containers first appeared in FS2 Open 22.2.0.

==Overview==

Get started with containers using FRED's "Add/Modify Container" dialog, which you can reach from the right-click menu in the Events Editor's SEXP tree.

[[File:Fred right click menu.png|200px|thumb|right|FRED's Events Editor with the "Add/Modify Container" right-click menu option highlighted.]]

The new [[#SEXPs and Replace Container Name|Replace Container Name]] and [[#Replace Container Data|Replace Container Data]] submenus are explained below.

Containers come in two types:
* '''List container''' - an ordered sequence of values, sort of a cross between Python lists and deques
* '''Map container''' - pairs of keys associated with data, like Lua tables or Python dictionaries

Just as variables have a type of either string or number, a container's data and a map container's keys have a type of either string or number.

==Features==

===Replace Container Data===

[[File:Containers_sample_replace.png|200px|thumb|right|Example of Replace Container Data.]]

Similar to how Replace Variable allows you to access data stored in variables, Replace Container Data allows you to access data stored in containers.

Use one of the following list modifiers to access data in list containers:
* Get_First
* Remove_First
* Get_Last
* Remove_Last
* Get_Random
* Remove_Random
* At

The list modifier options appear in the Replace Data submenu in FRED.

The At list modifier allows you to access data at a specific position in the list. Specify the index using Number under the Add Data submenu. The first item is at index 0.

The Get_First, Get_Last, and At list modifiers just retrieve the data, but the Remove_First and Remove_Last modifiers both retrieve the data and remove it from the container.

To access map container data, specify the key using Edit Data.

The container modifier can also be the value of a variable (use Replace Variable), the "special argument" if relevant (use Replace Data), or even a nested usage of Replace Container Data.

====Restrictions on Replace Container Data usage====

You can't use Replace Container Data in the "argument list" of special argument SEXPs, such as any-of, but you can use it in the "condition" or "actions" parts of those SEXPs. This applies for all special argument SEXPs, not just the ones that now take containers as arguments (see [[#Special argument list options|Special argument list options]] below).


===Text replacement===

[[File:Containers_sample_text.png|200px|thumb|right|Example of text replacement with containers.]]

Similar to text replacement for variables with $VariableName$, you can access container data in the text used in
* Command briefings
* Briefings
* Debriefings
* Messages
* Scripting
* Subtitles
* Debug SEXP

For list containers, use the format '''&ListContainerName&ListModifier&''', where '''ListModifier''' is one of the modifiers listed above. To access the first data item in the list, use the modifier '''At0'''.

For map containers, use the format '''&MapContainerName&MapKey&'''.

Container data and map keys ''are'' case-sensitive, but container names and list modifiers ''are not''.


===SEXPs and Replace Container Name===

[[File:Containers sample sexps.png|200px|thumb|right|Example of using SEXPs and Replace Container Name with containers.]]

You can access the Status and Change SEXPs from the new Containers subcategory in the Status and Change categories for Replace/Insert/Add Operator.

====Status SEXPs====
* is-container-empty
* get-container-size
* list-has-data
* list-data-index
* map-has-key
* map-has-data-item

====Change SEXPs====
* add-to-list
* remove-from-list
* add-to-map
* remove-from-map
* get-map-keys
* clear-container
* copy-container
* apply-container-filter

====Conditional SEXPs====
* for-container-data
* for-map-container-keys

FRED's built-in SEXP help explains how they work.

To specify the SEXP arguments that are container names, use the Replace Container Name submenu from FRED's right-click menu. You can specify those arguments using Replace Variable or Replace Container Data, too.


===Persistence===

[[File:Containers persistence options.png|200px|thumb|right|FRED's Add/Modify Container dialog with the Persistence options highlighted.]]

Containers support the same persistence options that variables do, except for "Network" (Issue #3708).


===Multidimensionality===

[[File:Containers sample multidim.png|200px|thumb|right|Example of multidimensionality with containers (part 1). The last three lines mean, "From the (map) container named Traitors, get the value whose key is the special argument. The value should be the name of a container with '&' added to the front and end of the name. Then, from that container, get the value whose key is 'MESSAGE - Treason'."]]

[[File:Containers sample multidim2.png|200px|thumb|right|Example of multidimensionality with containers (part 2). This shows the contents of the "Traitors" container. If the selected special argument is "Taurus", then the associated value is "&Taurus&", which refers to getting data from the container named "Taurus".]]

[[File:Containers sample multidim3.png|200px|thumb|right|Example of multidimensionality with containers (part 3). This shows the contents of the container named "Taurus". It shows that the key "MESSGE-Treason" is mapped to the string "Taurus - Treason".]]

[[File:Containers sample multidim4.png|200px|thumb|right|Example of multidimensionality with containers (part 4). This shows that "Taurus - Treason" is the name of a message whose text is "Ah! A plot is revealed".]]

For both text replacement and Replace Container Data, you can chain accesses to container data. The data stored in the first container should be formatted as &ContainerName&.

Unlike the other containers features, there is no equivalent feature for variables.

====Multidimensionality example 1====

In the screen shots on the right, if the random-of in the first screen shot happens to select "Taurus" as the special argument, then the ship "Taurus" will send the message "Ah! A plot is revealed".

====Multidimensionality example 2====

If I have two map containers, Map1 and Map2, and I want to display the data associated with the key "Key 1" from one of the two map containers, selected at random, I'd have a list container called Maps whose entries are '''&Map1&''' and '''&Map2&'''.

The expression to use in text replacement is '''&Maps&Get_Random&Key 1&'''.

To do the same thing in FRED's SEXP tree, I'd first use Replace Container Data with Maps using the list modifier Get_Random, and then I'd add "Key 1" using the String option under the Add Data submenu.


===Special argument list options===

[[File:Containers sample special arg.png|200px|thumb|right|Example of using containers in special argument lists.]]

For some SEXPs that are used with when-argument, you can use a mix of strings, list containers of string data, and/or map containers of string keys (map data can be any type) as arguments.

The string data/keys will then be included among the options for the special argument in that SEXP.

When the containers' contents change, the special argument options they provide will change as well.

These SEXPs are supported:
* any-of
* every-of
* number-of
* first-of
* random-multiple-of

Use the "Replace Container Name" submenu to include containers as arguments.

====Restrictions on usage in special argument list====

# You can't use validate-argument or invalidate-argument with containers. However, validate-all-arguments and invalidate-all-arguments will apply to container arguments as well.
# You also can't use validate-argument or invalidate-argument with arguments retrieved from containers.
# You can't use change SEXPs or Remove_* list modifiers on a container as part of a when-argument SEXP if the container is one of the arguments. However, it's OK to use the container with Get_*/At list modifiers or as an argument to any status SEXP or to a change SEXP that doesn't modify it, such as the map container in get-map-keys. It's also OK to modify containers that aren't among the arguments.

==Remaining features==

# Network persistence ([https://github.com/scp-fs2open/fs2open.github.com/issues/3708 Issue #3708])
# Add/Modify Container dialog for qtFRED ([https://github.com/scp-fs2open/fs2open.github.com/issues/3818 Issue #3818]) but qtFRED's SEXP tree should fully support containers.

[[Category:FRED]]