A registry key is like a directory. A registry value is like a file in which you store some data. A value is therefore created inside of a key. For the rest of this tutorial, 'directory' will be substituted for 'key', and 'file' will be substituted for 'value'.
Reginald will create/delete directories only under the "Current User" directory of the registry. One nice thing about this registry directory is that, each user who logs onto the system with his own profile, has his own "Current User" directory that is automatically set upon log-on. So, when you create/delete/read/write/query registry directories and files, they are per-user settings. For example, if you create a registry directory named 'My Key' and a registry file named 'My Value' inside of it, and store the data 'This is some data' in that file, this will appear in the 'Current User' directory of only whomever was logged in on the system. If another person logs in, there will be no such directory and file in his 'Current User' directory. So your script can store personalized data for each person who uses the system, and have that data automatically accessible when the person logs in. You don't have to do any extra work to implement personalized 'user profiles'.
You create/delete/read/write/query registry directories and files using an extension to Reginald's VALUE() built-in function.
To access the registry, you pass WIN32 for the environment arg to VALUE().
To create a directory, you must pass a directory name as the name arg to VALUE(). The directory name must end with a \ character. You must omit the new_value arg. For example, here we create a directory named My Directory:
error = VALUE("My Directory\", , "WIN32")
If all goes well, VALUE() will return an empty string. Otherwise, it will raise a SYNTAX error with error number 40.37.
Note: If the directory already exists, then this is not an error. VALUE() will return an empty string without disturbing the contents of the directory, nor raising SYNTAX.
You can even create a directory inside of another directory. But that other directory must exist first, or SYNTAX is raised. You also must specify the full path to the new directory. For example, here we create a sub-directory named My Sub-Directory inside of My Directory:
error = VALUE("My Directory\My Sub-Directory\", , "WIN32")
You create a registry file, and write some data to it, with a single call to VALUE(). For the name arg, you pass the name of the file to create. This name must include the full path (ie, directories). It must not end with a \ character. For the data that you wish to write, you pass this as the new_value arg. If all goes well, VALUE() will return the previous contents of that file. Otherwise, VALUE() will raise a SYNTAX condition with error 80.5.
For example, here we create a file named My File inside of the directory My Directory\My Sub-Directory, and write the data This is some data. to it:
previous = VALUE("My Directory\My Sub-Directory\My File", "This is some data.", "WIN32")
Note: If the file previously existed, its old contents are overwritten.
If you wish to read the contents of some registry file, then you specify the name of that file as the name arg. This name must include the full path (ie, directories). It must not end with a \ character. You should omit the new_value arg in order not to change the contents of the file. If all goes well, VALUE() will return the contents of that file. But if the file doesn't exist, then VALUE() simply returns an empty string. (So, if it's important to distinguish between a file that doesn't exist versus a file whose contents is an empty string, first query if the file exists).
For example, here we read the contents of a registry file named My File inside of the directory My Directory\My Sub-Directory:
data = VALUE("My Directory\My Sub-Directory\My File", , "WIN32")
As another example, here we query and print the value of
Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Personal:
SAY VALUE("Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Personal", , "WIN32")
The above would normally print "C:\MY DOCUMENTS", which is where you would typically save your data files that should reside on disk.
Note: To obtain the location of special directories such as where the current user stores documents, where his desktop is located, etc, you should instead use Reginald's SEARCHPATH() built-in.
To query if a registry file exists, you specify the name of the directories (containing the file) as the name arg. This name must include the full path (ie, directories). and end with a \ character. For the new_value arg, you pass only the name of the file without its directories. If the file exists, a 1 is returned, otherwise an empty string is returned.
For example, here we query if a registry file named My File exists inside of the directory My Directory\My Sub-Directory:
IF VALUE("My Directory\My Sub-Directory\", "My File", "WIN32") == 1
THEN SAY "It exists."
To delete a file, you must specify an empty string for the name arg. For the new_value arg, you pass the name of that file. This name must include the full path (ie, directories). It must not end with a \ character.
For example, here we delete the registry file named My File inside of the directory My Directory\My Sub-Directory:
CALL VALUE("", "My Directory\My Sub-Directory\My File", "WIN32")
Note: It is not an error to delete a file that doesn't exist.
To delete a directory, you must specify an empty string for the name arg. For the new_value arg, you pass the name of the directory. This name must include the full path (ie, directories). It must end with a \ character.
For example, here we delete the registry directory named My Sub-Directory inside of the directory My Directory:
CALL VALUE("", "My Directory\My Sub-Directory\", "WIN32")
Note: It is not an error to delete a directory that doesn't exist.