LavishSettings:LavishScript Usage Walkthrough

Setting up a main configuration set for a script

Scripts should use a single "main" configuration set, which can hold all settings used by the script, within sub-sets if necessary. Start by selecting a unique name for the set, such as the name of the script, and create the set within the LavishSettings root as follows:

LavishSettings:AddSet[Uncle John's Uber Script]

A set will now exist, called "Uncle John's Uber Script", under the LavishSettings root set. If the set already existed, then nothing would have changed -- the set would not be destroyed first, and if anything else existed within that set, it would still be there. The same is true for creating any set multiple times, so the setting hierarchy for a script can be re-created whenever the script starts, and not lose anything if the script already existed, and have no ill effects if settings are loaded from disk.

The main set created can now be accessed as LavishSettings[Uncle John's Uber Script].

Designing a configuration hierarchy

There are essentially two types of settings used by any software -- overall settings, and profiled settings. Overall settings apply to the software itself, or to all users, all profiles, and so on. Profiled settings are sectioned off such that they are per user, per server, per this or that. These types of settings are generally separated by sets. Here's an example:

• Uncle John's Uber Script
  • General
    • - GUI Enabled
    • - Auto-Update Enabled
  • Users
    • Shukahaka Server
      • Bork Bork
        • - Skin
        • Inventory
          • - Gold
          • Pack 1
            • - Bork Bork's Fork
          • Pack 2
      • Uncle John
        • - Skin
        • Inventory
          • - Gold
          • Pack 1
            • - Uncle John's Bathroom Reader
          • Pack 2

The above example has two sets within Uncle John's Uber Script. They can be created as follows:

LavishSettings[Uncle John's Uber Script]:AddSet[General]
LavishSettings[Uncle John's Uber Script]:AddSet[Users]

Server and User names are probably not known in advance, so those additional sets (within Users) can simply be created as needed. The additional sets and settings used in the example will be created in the sections below.

Working with set references

Referring to sub-sets nested several levels deep can get fairly daunting, besides being inefficient to have LavishSettings perform all those lookups each and every time. For this reason, sets can be referenced by ID number, or with set reference objects. Reference objects are a good way to keep a direct reference to any set for permanent usage -- the reference will work until the set is removed.

variable settingsetref General
variable settingsetref Users
Users:Set[${LavishSettings[Uncle John's Uber Script].FindSet[Users]}]
General:Set[${LavishSettings[Uncle John's Uber Script].FindSet[General]}]

These reference objects may now be used directly as if they were a settingset object. Once the server and user are known for profiled settings, the Users object can be used to create the sets:

variable settingsetref User
Users:AddSet[${ServerName}]
Users.FindSet[${ServerName}]:AddSet[${UserName}]
User:Set[${Users.FindSet[${ServerName}].FindSet[${UserName}]}]

The User object is now a direct reference to the set for the current user as well. The additional sub-sets for the user can now be added using the User object.

variable settingsetref Inventory
User:AddSet[Inventory]
Inventory:Set[${User.FindSet[Inventory]}]
Inventory:AddSet[Pack 1]
Inventory:AddSet[Pack 2]

Using Settings

Adding Settings

General:AddSetting[GUI Enabled,1]
General:AddSetting[Auto-Update Enabled,1]
User:AddSetting[Skin,Smurfberry]

Retrieving settings

echo GUI=${General.FindSetting[GUI Enabled]}
echo Auto-Update=${General.FindSetting[Auto-Update Enabled]}
echo current user's skin=${User.FindSetting[Skin]}

Settings can also be automatically created first if they do not exist, by supplying the default value as another parameter to FindSetting:

echo GUI=${General.FindSetting[GUI Enabled,1]}
echo Auto-Update=${General.FindSetting[Auto-Update Enabled,1]}
echo current user's skin=${User.FindSetting[Skin,Smurfberry]}

Destroying settings

General.FindSetting[GUI Enabled]:Remove
General.FindSetting[Auto-Update Enabled]:Remove
User.FindSetting[Skin]:Remove

Iterating sub-sets and settings

variable iterator ServerIterator
variable iterator UserIterator

/* list each server,user combination as "User on Server" such as "Bork Bork on Shukahaka Server" */
Users:GetSetIterator[ServerIterator]
if ${ServerIterator:First(exists)}
{
  do
  {
     ServerIterator.Value:GetSetIterator[UserIterator]
     if ${UserIterator:First(exists)}
     {
       do
       {
          echo ${UserIterator.Key} on ${ServerIterator.Key}
          /* The iterator.Value refers to the settingset objects themselves; Key is the name */
       }
       while ${UserIterator:Next(exists)}
     }
  }
  while ${ServerIterator:Next(exists)}
}

Iterating settings works much the same:

variable iterator SettingIterator
General:GetSettingIterator[SettingIterator]
if ${SettingIterator:First(exists)}
{
  do
  {
    echo "${SettingIterator.Key}=${SettingIterator.Value}"
    /* iterator.Key is the name of the setting, and iterator.Value is the setting object, which reduces to the value of the setting */
  }
  while ${SettingIterator:Next(exists)}
}

Storage and Retrieval

In the case of this example, it is logical for the entire configuration hierarchy to be stored in the same file. The base system for storage in LavishSettings is XML, but no knowledge of XML is required unless you wish to edit the stored file.

Storage

LavishSettings[Uncle John's Uber Script]:Export[UberScript.xml]

Retrieval

LavishSettings[Uncle John's Uber Script]:Import[UberScript.xml]

The file path and name given is, as with any LavishScript file paths, considered relative to the Current Working Directory (CWD) -- performed within a script, the CWD defaults to the path of the main file.

Note that any given set can be exported, and any given set can accept imports. In this example, the entire contents of the Uncle John's Uber Script was stored. It is just as easy to store the Users tree into a separate file, or fairly easy to store each individual user into a separate file as well (as you may have already guessed, that would require iterating through the users).

General:Export[UberScript.xml]
Users:Export[Users.xml]

To import later:

General:Import[UberScript.xml]
Users:Import[Users.xml]

See Also

• LavishScript
• LavishSettings