THE CUSTOMIZE INTERFACE Customize Documentation for the Customize Interface Christian P. Jacobi c Copyright 1989, 1991 Xerox Corporation. All rights reserved. Abstract: The Customize interface defines a database manager, including queries. It serves similar purposes as a user profile would, however there is more expressive power and no restriction to a single file. The data base file syntax and query precedence rules are a superset of the X-Window standard for resource files. Created by: Christian P. Jacobi Maintained by: Jacobi.pa Keywords: customization, userprofile, xrdb, database, resources XEROX Xerox Corporation Palo Alto Research Center 3333 Coyote Hill Road Palo Alto, California 94304 For Internal Xerox Use Only 1. Introduction What it does Some people call this a database; I think of it more as a glorified userprofile. This is kind of a simple data base system. The entries in this profile are of the form : . Queries are a subset of regular expressions; on a query the value is returned where its key matches; Very often several entries do match; there is a precedence order defined so the best match is returned. It is sort of unusual but quite interesting that queries don't have wildcards; but the database entries may have wildcards. This is handy in user-profile like applications where a database access should find a font, or a color: The query is well defined by the program requiring the value, but the database might be human written and contain all kinds of generalizations. The interface has three parts: Input and updating of databases. Building queries. Querying the data base. Relationship to X Windows The idea comes from X Windows. However this package in no way imports or implies X Windows.. This package can read unmodified X Window resource files. This makes it usefull in the X Window application, but its main advantage is: Go read the X Windows documentation; I don't have to write it. Heureka. There are some features missing: The X Windows version does allow batching of similar queries for speed reasons. This has not been implemented here because we do pre-processing of the database when it is created. Furthermore, I believe typical queries will contain only small number of components. Query types are reusable, which allows to do multiple queries without memory allocations. 2. Formats The database format Whitespace <" "> or <"\t"> is ignored except in ComponentName and String ResourceFile = {ResourceLine ("\n" | "\l")}. ResourceLine = Comment | ResourceSpec Comment = "!" String | ResourceSpec = ResourceName ":" Value ResourceName = [Binding] ComponentName {Binding ComponentName} Binding = "." | "*" | "?" ComponentName = { "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"} Value = String String = {} This is a superset of the standard X window xrdb format. The query format Query = QueryStep { QueryStep }. QueryStep = "(" ComponentName {"|" ComponentName} ")". The parsed format is more lenient. Restrict usage to the defined format to not get surprised on internal changes. Precedence order: 1) Left components are more specific than right components. 2) Database entries with explicite component names are more specific then database entries using wildcards ("*", "?"). Database entries with "?" are more specific then database entries using "*" 3) ComponentName's names which occur to the left of other ComponentName's in the same QueryStep are more specific then ComponentName's to the right. Examples For the data base ! ! ExampleCustomize.xrdb ! defaultFont: Helvetica otherFont: TimesRoman *scrollbar.color: blue mailtool*scrollbar.color: red mailtool?scrollbar.pixel: 276 mailtool.mainwindow.scrollbar.pixel: 275 mailtool.mainwindow.scrollbar.color: green commandtool*size: 23 *Container.size: 32 mailtool.mainwindow.pixel: 133 Some query results "(defaultFont | otherFont) " ==> Helvetica precedence rule 2 "(mailtool | tool) (mainwindow | Container) (scrollbar | Scrollbar) (color)" ==> green precedence rule 1 "(mailtool | tool) (mumble | Container) (scrollbar | Scrollbar) (color | pixel)" ==> red precedence rule 1 "(mailtool | tool) (mumble | Container) (foreground | Foo) ==> no match found "(commandtool) (Container) (size)" => 23 precedence rule 3 3. The Interface AnyString: TYPE = REF; --Either ROPE or REF TEXT DBreadonly: TYPE = REF READONLY DBRec; DB: TYPE = REF DBRec; DBRec: PRIVATE TYPE; CreateDB: PROC [] RETURNS [DB]; UpdateDB: PROC [db: DB, stream: IO.STREAM] RETURNS [errors: ROPE]; UpdateDBString: PROC [db: DB, string: AnyString] RETURNS [errors: ROPE]; UpdateDBExplicite: PROC [db: DB, key: AnyString, value: REF] RETURNS [errors: ROPE]; UpdateDBFromFile: PROC [file: REF, inputDb: DB _ NIL] RETURNS [db: DB, errors: ROPE]; DoQuery: PROC [db: DBreadonly, query: Query] RETURNS [REF]; DoQueryString: PROC [db: DBreadonly, string: AnyString _ NIL] RETURNS [REF]; Query: TYPE = REF QueryRep; QueryRep: TYPE; QueryState: PROC [query: Query] RETURNS [state: NAT]; NewQuery: PROC [reserve: NAT _ 16, useMemory: Query _ NIL] RETURNS [Query]; ResetQuery: PROC [query: Query, state: NAT _ 0]; CopyQuery: PROC [query: Query, reserve: NAT _ 0] RETURNS [Query]; AppendStepOnly: PROC [query: Query] RETURNS [Query]; AppendOptionOnly: PROC [query: Query, option: AnyString _ NIL] RETURNS [Query]; AppendStep: PROC [query: Query, val1, val2: AnyString _ NIL] RETURNS [Query]; FreeQuery: PRIVATE PROC [query: Query]; ParseQuery: PROC [string: AnyString _ NIL] RETURNS [Query]; QueryError: ERROR [what: ROPE]; 4. References The thing inspiring this package X WINDOW SYSTEM C Library and Protocol Reference Robert W. Scheifler, James Gettys, Ron Newman Chapter 10.11. Using the Resource Manager describes the X Window version of this functionality. Pages 324 and 325 are interesting. Chapter 10.11.1. Resource Manager Matching Rules [page 326 and 327] describes the format of the resource data base files. These four pages should be scanned in, into this document. 5. Restrictions Temporary restriction Since I don't want to deal with all the DFS, UFS, TFS... until we have PFS, the procedure accessing a database from a file must be used with caution. It might not be implemented in some worlds. 6. Open Design Questions What do you think? Use SymTab instead of Atoms and RefTab for arquivalency?. Build a localized atom table which can be garbage collected together with the db? The interface does hide this! Have a default db [~user profile like]. Problem: thats NOT the one you want to use with X. Extend the database format? like a symbol which matches exactly one component? X11R5 brought that. Extend query formats? Wildcards in query? Warning: Query must not be less efficient; otherwise I can't use it any more with X. Is it worth while introducing Database operations? Copy a database?. Merge two data bases? Is it worth while introducing any feature which won't really be used by the X software? Will it have other users?. ่ CustomizeDoc.tioga Copyright ำ 1989, 1991 by Xerox Corporation. All rights reserved. Written by: Christian Jacobi Christian Jacobi, November 22, 1991 3:40 pm PST Programming hints Errors: Four classes of errors are distinguished. 1) A database might have a syntax error. This is considered an user error; Customize tries to continue and returns just an error message to its caller. 2) A query might be malformed. This is a client error which causes an error to be raised. 3) A returned value might have an unexpected form. This is a user error, and the client application has to deal with that; Customize doesn't notice. 4) A type converter might raise an error. This is considered a client error. It is assumed that the conversion goal type sufficiently restrict type converters to the ones desired by the client application. Multi-programming: The obvious care is recommended. 1) Constructing the same query, or, updating the same database from different threads is an error. 2) Querying a database while updating it might cause the query to miss an entry. The database itself is not affected. 3) Multiple queries on the same database need not be monitored. 4) Changing the query data while a query is in progress may cause the query to fail, but it will not affect the database. Do not use the same query concurrently on different databases. Database creation The database representation. Creates new, empty DB. Parse and merge database entries into . If a specification is identical to one that already exists, the later one takes precedence. Parse and and merge database entries into . Parse and add as database entry into . Database values may be overwriten, but, they can't be removed. Conveniance procedure: is updated and returned again. a STREAM or a string (string is interpreted as a file name). Not found files are reported like syntax errors in the data base. Querying Query the database with . Conveniance procedure. Query the database strings. Query construction Even doing queries might have side effects on QueryRep. Returns of query in construction. Meaning of numerical value is private. Creates new empty query. Query does not yet have any steps or options. : allocates enough memory for about steps or options. Resets state of query to . =0 means reset to empty. Creates new copy which does not share memory with query. is a guess: allocates enough memory to append about more steps or options. Appends step to ; The new step has no options yet. Returns or new query if new memory allocation needed. Append query option to the current step of . must not be empty. Returns or new query if new memory allocation needed. Conveniance proc Appends step to ; Also appends up to two options to new step. Returns or new query if new memory allocation needed. Returns query for re-use. Caller asserts that he won't modify query anymore. It is ok to not worry but leave query's to the garbage collector. Parses into a query. May raise error QueryError. Done November 22, 1991 3:31:13 pm PST Done November 22, 1991 3:31:13 pm PST สฃ•NewlineDelimiter –(cedardoc) style™•Mark LastEditedšœ™Icode– LastEdited™BJ– LastEditedšœ™K– LastEditedšœ/™/J– LastEdited™—Iunleaded– centerHeaderšฯkœ œ œ˜Ititlešœ ˜ Isubtitlešœ)˜)Iabstractšœ˜Ošะmsฯs?œ˜AOšฯb œผ˜ลOš  œ˜Oš œ ˜Oš  œ6˜?Iblock˜P˜I boilerplateš ฯqฯoœขœขœขœัbox˜Žhead˜ ˜ Ilead1˜PSšœญ˜ญSšœ"˜" šœ˜S˜L—— ˜Sšœ]˜]Sšœา˜าS˜‡—— ˜ ˜J˜IJ˜J˜-J˜%J˜(J˜)J˜@J˜J˜:J˜J˜?J˜J˜8J˜— ˜J˜%J˜9J˜J˜rJ˜— š ˜S˜;S˜รS˜”S˜— ˜Jš ˜J˜J˜J˜J˜J˜J˜J˜J˜"J˜"J˜*J˜,J˜J˜J˜"J˜J˜Jš ˜J˜˜*Jšฯi˜—˜VJšค˜—˜XJšค˜—˜EJšค˜—˜(Jšค˜——— ˜˜šœ œœฯc˜0K˜——K˜šัael™K™š œ+™1Jšœ@ œW™›Jšœ* œ*™ZJšœ> œT™–Jšœฯ™ฯJ™—š œ"™3Jšœd™dJšœx™xJšœA™AJšœน™นJ™——K™šฆ™K˜Kšœ œœœ˜&šœœœ˜Kšœ™Kšœœ˜—K˜šฯnœœœœ˜K™K˜—šงœœœ œœœ œ˜BKšœ’™’K™—š งœœœœ œ˜HKšœ:™:K™—š งœœœœœ œ˜TKšœ:™:Kšœ@™@K™—šงœœœ œœœœ œ˜UKšœJœw™วK˜——K˜šฆ™K˜šงœœ œœ˜;Kšœ&™&K˜—š ง œœ&œœœ˜LKšœ™Kšœ ™ K˜——K˜šฆ™K˜šœœœ ˜Kšœ œ˜Kšœ:™:K˜—šง œœœ œ˜5KšœS™SK˜—š งœœ œœœ ˜KKšœG™GKšœH™HK˜—šง œœœ˜0KšœA™AK˜—šง œœœœ ˜AKšœ9™9Kšœ^™^K™—šงœœœ ˜4Kšœ9™9Kšœ=™=K™—šงœœ$œœ ˜OKšœ4™4Kšœ™Kšœ=™=K™—šง œœ(œœ ˜MKšœ™KšœD™DKšœ=™=K™—šง œœœ˜'KšœM™MKšœA™AK˜—šง œœœœ ˜;Kšœ™Kšœ™Kšง œœœ˜K˜——— ˜ ˜ J˜J˜ J˜-J˜Jšข)œ8ขœ!˜ƒJšข1œJ˜{J˜:—— ˜ ˜Jšœย˜ย—— ˜ ˜˜ฌJ™%—J˜J˜[J˜˜dJ™%J˜—J˜J˜J˜ZJ˜J˜s——K™—…—/™