SJSON search documentation

[AndreLouisIssa]

Add SJSON search ("_search" keyword) documentation to this wiki post

see: https://discord.com/channels/667753182608359424/667757899111596071/982896736299274311

[reviniere]

Some suggestions for content on that page:

Add _search as a sequence keyword with description like:

• "_search" Searches for any containers which match all the given matching conditions, and merges the provided updates to all matching containers.

Add subheadings under Mirroring Structure heading to make it clearer to identify what each codeblock is for, e.g.

• Sample input file
• Merging changes to a sequence by index number
• Merging changes to a sequence by search terms
• Appending to a sequence
• Replacing a sequence
• Deleting a key

Under the new subheading regarding search terms, content such as:

Merging changes to a sequence by search terms

As an alternative to explicitly specifying the list index to update a container at, you can also search for containers which match a set of conditions. This search feature will merge your replacement values to all containers in the list which match all your search terms.

The format of using this search is as follows:

Sequence = [
    "_search", [
        { TargetKey = "target_value" }
        { TargetKey = "replacement_value" }
        ...
    ]
]

The keys for both the target_value and replacement_value can be the same or different. The target_value and replacement_value containers may also both contain multiple key-value pairs, e.g.

Sequence = [
    "_search", [
        { 
            Name = "WeaponThrow" 
            FullyAutomatic = true
        }
        { 
            FullyAutomatic = false
            Control = "Attack2"
            MinChargeToFire = 1.0
            LoseControlOnRelease = true
            SwapOnFire = "_delete"
        }
    ]
]

To perform multiple searches at the same level, add further pairs of match conditions and replacement values, e.g.

Sequence = [
    "_search", [
        { TargetKey = "target_value" }
        { TargetKey = "replacement_value" }
        { OtherTargetKey = "another_target_value" }
        { OtherTargetReplacement = "another_replacement_value" }
    ]
]

To make the same change as the previous example where a container was updated using an explicit index number, to change the value at MyKey to "newvalue", this is the corresponding merge sjson which identifies the container to update by finding containers where OtherKey = 45

{
  Sequence = [
    "_search"
    [
        { OtherKey = 45 }
        { MyKey = "newvalue" }
    ]
  ]
}