Sometimes it may be convenient for a macro to store a user preference or configuration until a later time. A Registry object is responsible for persisting such values until later. There are three shared registries, each providing a different lifetime for the values it stores.
Each value stored in the registry is identified by a unique name, just like a Hash key. Since registry objects provide shared storage that will be used by many different macros the name should be globally unique. To that end each name should follow a period-delimited reverse domain syntax, eg: ‘com.company.scope.valueName’.
As an example, consider a macro written by Nisus that stores the path where the user would like to place backups. The value’s name could be ‘com.nisus.backupMacro.backupFolderPath’. This naming convention is not enforced, but your macros should use it to be a “good citizen” for other macro authors. If you do not have a company, it may be appropriate to use your real name or an alias instead, eg: ‘name.BenHurmak.sequenceMacro.runCount’.
Registry Type Commands
Registry.macroRegistry v1.1
Returns the Registry object that persist all of its values until the first (root) macro finishes execution. Once currently executing macros have finished, all values stored in the registry are cleared. This registry is useful for passing values between macros that call each other.
Registry.applicationRegistry v1.1
Returns the Registry object that persist all of its values until the application is quit. Once the application quits all values stored in the registry are cleared.
Registry.userRegistry v1.1
Returns the Registry object that persists all of its values as long as the user running the macro has an account on the computer. In other words, the values in this registry will be saved in the active user’s home directory (in the Macros folder) and are basically permanent.
Note: the user registry places a restriction on the types of values it will persist. Only numbers (int and float) and strings (without attributes) can be saved between application launches. Starting with v2.0 the user registry will also persist Array and Hash objects (which may contains numbers, strings, and nested arrays/hashes).
Registry Commands
.saveValueWithName value, name v1.1
Stores the value in the registry, allowing it to be retrieved later using the same name. The name should be unique as outlined in the introduction on Registry objects above.
.loadValueWithName name v1.1
Returns the value that was previously saved in the registry using the given name. If the name is unknown because the value has not yet been stored returns the @undefined value.
.removeValueWithName name v1.1
Removes the value with the given name from the registry so it is no longer persisted.
.allValueNames v1.1
Returns an array of all names that have been stored in the registry.
Registry Examples
This macro simply counts the number of times it has been run by the user:
$countName = 'com.Nisus.example.runCount'
$registry = Registry.userRegistry
$count = $registry.loadValueWithName($countName)
$count += 1
$registry.saveValueWithName($count, $countName)
Prompt "You've run this macro $count times."
| Previous Chapter System Properties |
<< index >> |
Next Chapter NSUserDefaults |