Lets talk about properties (or "settings" or "preferences").
They are, essentially, a mapping from string to string.
The "key" is a property name - a string
The "value" is the current value of the property - a string
A given property has a scope
"System" - Created by Java Runtime system and accessed via System.getProperty()
"global" - visible to / applies to all users - accessed via Preferences.getString
"user" - each user has own copy - accessed via Preferences.getString
There are also a handful of weird properties - "per-user-global" where the property is stored in the GLOBAL map as a name from defaults.txt with ".USERNAME" appended. There appear to be exactly three of these:
displayName
getBreakfast
saveState (not visible to gCLI or ASH)
These are done this way because the Login Frame uses them, having loaded GLOBAL prefs, without having to load user prefs.
Those don't seem to actually be accessible; they are in GLOBAL_prefs - and go into the "global" map - but get and prefref don't show the values. I'm not sure why.
Each property is of one of two types
"built-in" - Created & maintained by KoLmafia itself. These can be global or user
"custom" - Created and maintained by a script. These are (currently) always user
Each "built-in" property must be defined in defaults.txt, and therefore has a default value.
A "custom" property has no "default" value; it has whatever value it is given when it is created.
The "prefref" command lists properties and shows:
Name
Value
Default
Scope
It does not directly say whether a property is built-in or custom - although it will say "N/A" for a property that does not appear in defaults.txt.
(I am amused to see that preferences that moved from global to user remain in the global table but are now marked as N/A, since they no longer appear in defaults.txt - and, in fact, KoLmafia will never look at the global values.)
The "get" and "set" CLI commands will retrieve or set the neamed property from whichever map it is in.
The get_property() and set_property() ASH functions do the same. In fact, the latter is implemented in terms of the CLI "set" command. This is because the following all have special behaviors when they are set:
battleAction
customCombatScript
combatHotkey[0-9]
_userMods
And that is the extent of programming support.
I can think of a variety of things I'd like to be able to program.
- I'd like to be able to iterate over a (possibly filtered) list of all properties.
- I'd like to know if a property is built-in or custom, if it is user or global, and what the default is
- I'd like to be able to remove a custom property.
With those facilities, I could write the equivalent of prefref, and I could prune orphaned global properties that have been moved to the user map.
(If we ever decided to allow custom global properties, that last one would not work.)
I see a couple ways to do this.
1) Add a few functions:
boolean [string] get_all_properties( string filter )
boolean [string] get_all_properties( string filter, boolean scope )
the "boolean" is true for global, false for user
boolean remove_property( string name )
returns false (and does nothing) if the property is built-in, otherwise removes the custom property from whichever map it is in
boolean property_is_global( string name )
boolean property_is_custom( string name )
string property_default_value( string name )
2) Alternatively, I could create a "property" data type and make scope, type, and default be proxy fields rather than having those last three functions.
I need the three functions (or proxy fields) for a little project.
The others would be nice for sanity checking defaults.txt and eyeballing whether all seeming "custom" are actually built-in and should be in defaults.txt.
What do you think?
They are, essentially, a mapping from string to string.
The "key" is a property name - a string
The "value" is the current value of the property - a string
A given property has a scope
"System" - Created by Java Runtime system and accessed via System.getProperty()
"global" - visible to / applies to all users - accessed via Preferences.getString
"user" - each user has own copy - accessed via Preferences.getString
There are also a handful of weird properties - "per-user-global" where the property is stored in the GLOBAL map as a name from defaults.txt with ".USERNAME" appended. There appear to be exactly three of these:
displayName
getBreakfast
saveState (not visible to gCLI or ASH)
These are done this way because the Login Frame uses them, having loaded GLOBAL prefs, without having to load user prefs.
Those don't seem to actually be accessible; they are in GLOBAL_prefs - and go into the "global" map - but get and prefref don't show the values. I'm not sure why.
Each property is of one of two types
"built-in" - Created & maintained by KoLmafia itself. These can be global or user
"custom" - Created and maintained by a script. These are (currently) always user
Each "built-in" property must be defined in defaults.txt, and therefore has a default value.
A "custom" property has no "default" value; it has whatever value it is given when it is created.
The "prefref" command lists properties and shows:
Name
Value
Default
Scope
It does not directly say whether a property is built-in or custom - although it will say "N/A" for a property that does not appear in defaults.txt.
(I am amused to see that preferences that moved from global to user remain in the global table but are now marked as N/A, since they no longer appear in defaults.txt - and, in fact, KoLmafia will never look at the global values.)
The "get" and "set" CLI commands will retrieve or set the neamed property from whichever map it is in.
The get_property() and set_property() ASH functions do the same. In fact, the latter is implemented in terms of the CLI "set" command. This is because the following all have special behaviors when they are set:
battleAction
customCombatScript
combatHotkey[0-9]
_userMods
And that is the extent of programming support.
I can think of a variety of things I'd like to be able to program.
- I'd like to be able to iterate over a (possibly filtered) list of all properties.
- I'd like to know if a property is built-in or custom, if it is user or global, and what the default is
- I'd like to be able to remove a custom property.
With those facilities, I could write the equivalent of prefref, and I could prune orphaned global properties that have been moved to the user map.
(If we ever decided to allow custom global properties, that last one would not work.)
I see a couple ways to do this.
1) Add a few functions:
boolean [string] get_all_properties( string filter )
boolean [string] get_all_properties( string filter, boolean scope )
the "boolean" is true for global, false for user
boolean remove_property( string name )
returns false (and does nothing) if the property is built-in, otherwise removes the custom property from whichever map it is in
boolean property_is_global( string name )
boolean property_is_custom( string name )
string property_default_value( string name )
2) Alternatively, I could create a "property" data type and make scope, type, and default be proxy fields rather than having those last three functions.
I need the three functions (or proxy fields) for a little project.
The others would be nice for sanity checking defaults.txt and eyeballing whether all seeming "custom" are actually built-in and should be in defaults.txt.
What do you think?