Profiles.mesa
Copyright Ó 1985, 1986, 1987, 1988, 1991 by Xerox Corporation. All rights reserved.
Teitelman on December 16, 1982 11:59 am
Russ Atkinson (RRA) November 28, 1988 10:22:25 pm PST
Doug Wyatt, January 18, 1987 11:09:25 pm PST
Eric Nickell, May 17, 1988 4:41:37 pm PDT
Overview
Profile is a package for reading information from a disk file <YourName>.profile, or if none exists, User.profile. The purpose of a profile is to allow personalized tailoring of the system.
Entries in the user's profile are of the form: <key>: <value>RETURN, where value is either (1) a BOOL, (2) an INT, (3) a TOKEN, (4) a ListOfTokens, or (5) an expression which can be assigned to some Cedar type (for more details, see ProfileDoc.tioga). Comments (indicated using the standard "--" convention) can appear anywhere in the profile and will be ignored. The parsing will also ignore extra spaces or blank lines. Any errors or anomalies discovered when parsing or accessing the profile will cause diagnostics to be printed to the file Profile.log. The user will be informed that problems have been encountered via the Message Window. In no case however will the system break.
Access to individual profile entries via the procedures below is relatively efficient, since this access does not require any file reads or parsing. Therefore, many simple applications can simply read information from the profile as needed. However, some applications derive complex data structures from the profile (consider the effect of the "UserCategory" profile entry on the state of Tioga), and hence cannot afford to interrogate the profile whenever some information derived from it is used. Such an application must register a ProfileChangedProc and perform all of its profile interrogations from within this procedure. This guarantees that the corresponding values will be updated whenever the profile changes. The ProfileChangedProc will be called when it is first registered, whenever the system is booted or rolled-back, or whenever the profile file is saved.
Note: Since the ProfileChangedProc for an application is not called from that application's process(es), the application must explicitly synchronize its reads to variables derived from the profile with the ProfileChangedProc's writes to these variables. This may involve adding a monitor to an application that previously did not require one.
Creating the Profile
Profile: TYPE ~ REF ProfileRep;
ProfileRep: TYPE; --Private
Create:
PROC [files:
LIST
OF
ROPE, keepFresh:
BOOL ¬
TRUE]
RETURNS [profile: Profile];
Parses a set of profile files and returns the data structure which can be used to access the values.
keepFresh implies that the implementation will track changes in the profile, either by editing or upon checkpoint or rollback, etc.
CreateFromRope:
PROC [slices:
LIST
OF
ROPE]
RETURNS [profile: Profile];
Parses a set of profile files and returns the data structure which can be used to access the values.
keepFresh implies that the implementation will track changes in the profile, either by editing or upon checkpoint or rollback, etc.
Slice:
TYPE ~
RECORD [
SELECT type: *
FROM
rope => [text: Rope.ROPE],
file => [fileName: Rope.ROPE],
ENDCASE
];
CreateFromSlices:
PROC [slices:
LIST
OF Slice, keepFresh:
BOOL ¬
TRUE]
RETURNS [profile: Profile];
Parses a set of profile files and returns the data structure which can be used to access the values.
keepFresh implies that the implementation will track changes in the profile, either by editing or upon checkpoint or rollback, etc.
LetProfileGetStale:
PROC [profile: Profile];
If profile was created with Create[keepFresh~TRUE], then the implementation must be holding on the profile in order to know when to update it upon appropriate changes.
Calling LetProfileGetStale will remove any references the implementation has to profile.
If the profile is not currently being kept fresh, then this operation is a noop.
Accessing the Profile
The procedures described below all read simple results from the value field given a key. The default value is passed in as an argument so that the client can specify what the procedure returns should the value be absent or malformed, or the profile be missing.
Boolean:
PROC [profile: Profile, key:
ROPE, default:
BOOL ¬
FALSE]
RETURNS [value:
BOOL];
Number:
PROC [profile: Profile, key:
ROPE, default:
INT ¬ 0]
RETURNS [value:
INT];
Token:
PROC [profile: Profile, key:
ROPE, default:
ROPE ¬
NIL]
RETURNS [value:
ROPE];
returns next token following <key>:, i.e. effectively does an IO.GetTokenRope[... IDBreak]. If the first character encountered is ", then reads everything to the next matching ", and returns this as a single rope.
For example, if your profile contains:
PreRun: Clock.bcd Foo.bcd Bar.bcd
then Token["PreRun"] will return "Clock.bcd".
if your profile contains:
PreRun: "nay doo run run run" Foo.bcd Bar.bcd
then Token["PreRun"] will return "nay doo run run run".
ListOfTokens:
PROC [profile: Profile, key:
ROPE, default:
LIST
OF
ROPE ¬
NIL]
RETURNS [value:
LIST
OF
ROPE];
For example, if your profile contains:
PreRun: Clock.bcd, VersionMapOpsImpl.bcd, HideousKludge.bcd, -- just until 3.4 -- WalnutSend.bcd
then ListOfTOkens["PreRun"] will return ("Clock.bcd", "VersionMapOpsImpl.bcd", "HideousKludge.bcd", "WalnutSend.bcd).
Note that if the user profile contains Key:{cr}, then ListOfTokens["key", default] will return NIL, not default, i.e. the entry for "key" is neither malformed or absent.
Line:
PROC [profile: Profile, key:
ROPE, default:
ROPE ¬
NIL]
RETURNS [value:
ROPE];
Like ListOfTokens except returns the result as a single rope, e.g. for above example, the value of Line["PreRun"] would be "Clock.bcd VersionMapOpsImpl.bcd HideousKludge.bcd WalnutSend.bcd".
EnumerateKeys:
PROC [profile: Profile, pattern:
ROPE, proc: EnumProc];
EnumProc: TYPE ~ PROC [key: ROPE] RETURNS [quit: BOOL ¬ FALSE];
Pattern is any acceptable to Rope.Match
HasEntry:
PROC [profile: Profile, key:
ROPE]
RETURNS [
BOOL];
Returns TRUE iff key is defined in profile.
GetProfileNames:
PROC [profile: Profile]
RETURNS [
LIST
OF
ROPE];
returns name of file used to build the profile.
GetProfileSlices:
PROC [profile: Profile]
RETURNS [
LIST
OF Slice];
returns pieces used to build the profile.
Registering procedures for accessing the profile
As mentioned above, if the result of accessing the user profile is going to be cached by the client, then the profile should not be accessed directly, but via a ProfileChangedProc which has been registered with CallWhenProfileChanges. This guarantees that the corresponding values will be updated whenever the profile changes.
In other words, rather than writing:
ClientCheckpointFlag: BOOL ← Profile.Boolean[profile, "ClientCheckpoint", TRUE];
the implementor should write:
ClientCheckpointFlag: BOOL;
Init: ProfileChangedProc = {
ClientCheckpointFlag ← Profile.Boolean[profile, "ClientCheckpoint", TRUE];
};
Profile.CallWhenProfileChanges[profile, Init];
CallWhenProfileChanges:
PROC [profile: Profile, proc: ProfileChangedProc, clientData:
REF];
proc is called when it is first registered with reason = firstTime.
ProfileChangedProc: TYPE = PROC [profile: Profile, reason: ProfileChangeReason, clientData: REF ¬ NIL];
ProfileChangeReason: TYPE = {firstTime, rollBack, edit};
ProfileChanged: ProfileChangedProc;
Calls all of the ProfileChangedProcs. This procedure is automatically called after a rollback, whenever any of its associated files are saved by tioga, or whenever the logged-in user changes.