[_CDCSL_93-16_]<1>Cedar>release>UserProfile>UserProfile.mesa

UserProfile.mesa

Teitelman on December 16, 1982 11:59 am

Russ Atkinson (RRA) February 5, 1985 3:22:36 pm PST

Doug Wyatt, January 18, 1987 11:09:25 pm PST

JKF August 31, 1988 3:13:06 pm PDT

DIRECTORY Rope USING [ROPE];

UserProfile: CEDAR DEFINITIONS = BEGIN OPEN Rope;

Overview

UserProfile is a package for reading information from the disk file <YourName>.profile, or if none exists, User.profile. The purpose of the profile is to allow personalized tailoring of the system. The current catalogue of ways the Cedar system can be parameterized may be found in the file UserProfileDoc.tioga.

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, or (4) a ListOfTokens (for more details, see UserProfileDoc.tioga). When Cedar is booted, rolledBack, or any file whose extension is "profile" is edited, the profile is parsed and a data structure which describes the information that was found in the profile is constructed. 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 UserProfile.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 a file with extension ".profile" 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.

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 [key: ROPE, default: BOOL ¬ FALSE] RETURNS [value: BOOL];

Number: PROC [key: ROPE, default: INT ¬ 0] RETURNS [value: INT];

Token: PROC [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 [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 [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".

GetProfileName: PROC RETURNS [ROPE];

returns name of file used to build the profile, i.e. either <YourName>.profile, or UserName.Profile. Returns NIL if no profile.

-- Formerly of UserProfileExtras:

RopeProfile is another source of profile information and is last in the evaluation "chain". The RopeProfile is set to NIL anytime ProfileChanged is called with a reason other than firstTime. For example, editing of a profile file will NIL-out any existing RopeProfile.

GetRopeProfile: PROC RETURNS [Rope.ROPE];

Returns the current RopeProfile.

SetRopeProfile: PROC [rope: Rope.ROPE ¬ NIL];

Sets the RopeProfile to a new value, causes re-evaluation of all profile information, and all ProfileChangedProcs to be called. The syntax of the RopeProfile is identical to that of a profile file. Duplicate entries in the RopeProfile are not considered to be an error and are not reported. The filename "RopeProfile" is used if and when any errors are reported.

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 ← UserProfile.Boolean["ClientCheckpoint", TRUE];

the implementor should write:

ClientCheckpointFlag: BOOL;

Init: ProfileChangedProc = {

ClientCheckpointFlag ← UserProfile.Boolean["ClientCheckpoint", TRUE];

};

UserProfile.CallWhenProfileChanges[Init];

CallWhenProfileChanges: PROC [proc: ProfileChangedProc];

proc is called when it is first registered with reason = firstTime.

ProfileChangedProc: TYPE = PROC [reason: ProfileChangeReason];

ProfileChangeReason: TYPE = {firstTime, rollBack, edit, newUser};

ProfileChanged: PROC [reason: ProfileChangeReason];

Calls all of the ProfileChangedProcs. This procedure is automatically called after a rollback, whenever the a file with extension 'profile' is saved by tioga, or whenever the logged-in user changes.

GetErrorLog: PROC RETURNS [fileName: ROPE];

if there were any errors reported, this closes the stream and returns the name of the file.

END.

Edited on December 14, 1982 3:50 pm, by Teitelman

changes to comments only

changes to: ListOfTokens, Line

Russ Atkinson (RRA) February 5, 1985 3:21:37 pm PST

reformatted

Jim Foote August 31, 1988 3:11:10 pm PDT

Folded in UserProfileExtras.